feat(properties): add setting org_use_property_inheritance

Author: troiganto

docs/configuration.org

@@ -533,6 +533,22 @@ Prefix added to the generated id when [[#org_id_method][org_id_method]] is set t
 If =true=, generate ID with the Org ID module and append it to the
 headline as property. More info on [[#org_store_link][org_store_link]]
 
+*** =org_use_property_inheritance=
+:PROPERTIES:
+:CUSTOM_ID: org_use_property_inheritance
+:END:
+- Type: =boolean | string | string[]=
+- Default: =false=
+Determine whether properties of one headline are inherited by sub-headlines.
+
+- =false= - properties only pertain to the file or headline that defines them
+- =true= - properties of a headlines also pertain to all its sub-headlines
+- =string[]= - only the properties named in the given list are inherited
+- =string= - only properties matching the given regex are inherited
+
+Note that for a select few properties, the inheritance behavior is hard-coded withing their special applications.
+See [[https://orgmode.org/manual/Property-Inheritance.html][Property Inheritance]] for details.
+
 *** =org_babel_default_header_args=
 :PROPERTIES:
 :CUSTOM_ID: org_babel_default_header_args

lua/orgmode/clock/init.lua

@@ -118,7 +118,7 @@ function Clock:get_statusline()
     return ''
   end
 
-  local effort = self.clocked_headline:get_property('effort')
+  local effort = self.clocked_headline:get_property('effort', false)
   local total = self.clocked_headline:get_logbook():get_total_with_active():to_string()
   if effort then
     return string.format('(Org) [%s/%s] (%s)', total, effort or '', self.clocked_headline:get_title())

lua/orgmode/config/_meta.lua

@@ -235,6 +235,7 @@
 ---@field org_id_method? 'uuid' | 'ts' | 'org' What method to use to generate ids via org.id module. Default: 'uuid'
 ---@field org_id_prefix? string | nil Prefix to apply to id when `org_id_method = 'org'`. Default: nil
 ---@field org_id_link_to_org_use_id? boolean If true, Storing a link to the headline will automatically generate ID for that headline. Default: false
+---@field org_use_property_inheritance boolean | string | string[] If true, properties are inherited by sub-headlines; may also be a regex or list of property names. Default: false
 ---@field org_babel_default_header_args? table<string, string> Default header args for org-babel blocks: Default: { [':tangle'] = 'no', [':noweb'] = 'no' }
 ---@field win_split_mode? 'horizontal' | 'vertical' | 'auto' | 'float' | string[] How to open agenda and capture windows. Default: 'horizontal'
 ---@field win_border? 'none' | 'single' | 'double' | 'rounded' | 'solid' | 'shadow' | string[] Border configuration for `win_split_mode = 'float'`. Default: 'single'

lua/orgmode/config/defaults.lua

@@ -66,6 +66,7 @@ local DefaultConfig = {
   org_id_method = 'uuid',
   org_id_prefix = nil,
   org_id_link_to_org_use_id = false,
+  org_use_property_inheritance = false,
   org_babel_default_header_args = {
     [':tangle'] = 'no',
     [':noweb'] = 'no',

lua/orgmode/config/init.lua

@@ -539,6 +539,25 @@ function Config:parse_header_args(args)
   return results
 end
 
+---@param property_name string
+---@return boolean uses_inheritance
+function Config:use_property_inheritance(property_name)
+  property_name = string.lower(property_name)
+
+  local use_inheritance = self.opts.org_use_property_inheritance or false
+
+  if type(use_inheritance) == 'table' then
+    return vim.tbl_contains(use_inheritance, function(value)
+      return vim.stricmp(value, property_name) == 0
+    end, { predicate = true })
+  elseif type(use_inheritance) == 'string' then
+    local regex = vim.regex(use_inheritance)
+    return regex:match_str(property_name) and true or false
+  else
+    return use_inheritance and true or false
+  end
+end
+
 ---@type OrgConfig
 instance = Config:new()
 return instance

lua/orgmode/files/headline.lua

@@ -422,7 +422,7 @@ end
 function Headline:set_property(name, value)
   local bufnr = self.file:get_valid_bufnr()
   if not value then
-    local existing_property, property_node = self:get_property(name)
+    local existing_property, property_node = self:get_property(name, false)
     if existing_property and property_node then
       vim.fn.deletebufline(bufnr, property_node:start() + 1)
     end
@@ -443,7 +443,7 @@ function Headline:set_property(name, value)
   end
 
   local property = (':%s: %s'):format(name, value)
-  local existing_property, property_node = self:get_property(name)
+  local existing_property, property_node = self:get_property(name, false)
   if existing_property then
     return self:_set_node_text(property_node, property)
   end
@@ -472,7 +472,10 @@ function Headline:add_note(note)
 end
 
 ---@param property_name string
----@param search_parents? boolean
+---@param search_parents? boolean if true, search parent headlines;
+---                               if false, only search this headline;
+---                               if nil (default), check
+---                               `org_use_property_inheritance`
 ---@return string | nil, TSNode | nil
 function Headline:get_property(property_name, search_parents)
   local _, properties = self:get_properties()
@@ -486,6 +489,10 @@ function Headline:get_property(property_name, search_parents)
     end
   end
 
+  if search_parents == nil then
+    search_parents = config:use_property_inheritance(property_name)
+  end
+
   if not search_parents then
     return nil, nil
   end
@@ -495,7 +502,7 @@ function Headline:get_property(property_name, search_parents)
     local headline_node = parent_section:field('headline')[1]
     if headline_node then
       local headline = Headline:new(headline_node, self.file)
-      local property, property_node = headline:get_property(property_name)
+      local property, property_node = headline:get_property(property_name, false)
       if property then
         return property, property_node
       end
@@ -918,7 +925,7 @@ function Headline:is_same(other_headline)
 end
 
 function Headline:id_get_or_create()
-  local id_prop = self:get_property('ID')
+  local id_prop = self:get_property('ID', false)
   if id_prop then
     return vim.trim(id_prop)
   end

lua/orgmode/org/hyperlinks/init.lua

@@ -57,7 +57,7 @@ function Hyperlinks.as_custom_id_anchors(url)
   return function(headlines)
     return vim.tbl_map(function(headline)
       ---@cast headline OrgHeadline
-      local custom_id = headline:get_property('custom_id')
+      local custom_id = headline:get_property('custom_id', false)
       return ('%s#%s'):format(prefix, custom_id)
     end, headlines)
   end

lua/orgmode/org/links/types/custom_id.lua

@@ -60,7 +60,7 @@ function OrgLinkCustomId:autocomplete(link)
   local prefix = opts.type == 'internal' and '' or opts.link_url:get_path_with_protocol() .. '::'
 
   return vim.tbl_map(function(headline)
-    local custom_id = headline:get_property('custom_id')
+    local custom_id = headline:get_property('custom_id', false)
     return prefix .. '#' .. custom_id
   end, headlines)
 end

tests/plenary/files/headline_spec.lua

@@ -1,4 +1,5 @@
 local helpers = require('tests.plenary.helpers')
+local config = require('orgmode.config')
 
 describe('Headline', function()
   describe('get_category', function()
@@ -54,6 +55,50 @@ describe('Headline', function()
     end)
   end)
 
+  describe('use_property_inheritance', function()
+    local file = helpers.create_file_instance({
+      '#+CATEGORY: file_category',
+      '* Headline 1',
+      ':PROPERTIES:',
+      ':DIR: some/dir/',
+      ':THING: 0',
+      ':COLUMNS:',
+      ':END:',
+      '** Headline 2',
+      '   some body text',
+    }, 'category.org')
+    after_each(function()
+      config:extend({ org_use_property_inheritance = false })
+    end)
+    it('is false by default', function()
+      assert.is.Nil(file:get_headlines()[2]:get_property('dir'))
+    end)
+    it('is active if true', function()
+      config:extend({ org_use_property_inheritance = true })
+      assert.are.same('some/dir/', file:get_headlines()[2]:get_property('dir'))
+      assert.are.same('0', file:get_headlines()[2]:get_property('thing'))
+    end)
+    it('is selective if a list', function()
+      config:extend({ org_use_property_inheritance = { 'dir' } })
+      assert.are.same('some/dir/', file:get_headlines()[2]:get_property('dir'))
+      assert.is.Nil(file:get_headlines()[2]:get_property('thing'))
+    end)
+    it('is selective if a regex', function()
+      config:extend({ org_use_property_inheritance = '^di.$' })
+      assert.are.same('some/dir/', file:get_headlines()[2]:get_property('dir'))
+      assert.is.Nil(file:get_headlines()[2]:get_property('thing'))
+    end)
+    it('can be overridden with true', function()
+      assert.is.Nil(file:get_headlines()[2]:get_property('dir'))
+      assert.are.same('some/dir/', file:get_headlines()[2]:get_property('dir', true))
+    end)
+    it('can be overridden with false', function()
+      config:extend({ org_use_property_inheritance = true })
+      assert.are.same('some/dir/', file:get_headlines()[2]:get_property('dir'))
+      assert.is.Nil(file:get_headlines()[2]:get_property('dir', false))
+    end)
+  end)
+
   describe('get_all_dates', function()
     it('should properly parse dates from the headline and body', function()
       local file = helpers.create_file({