Add initial version of api. (#331)

Author: kristijanhusak

.github/workflows/docgen.yml

@@ -21,10 +21,37 @@ jobs:
         env:
           COMMIT_MSG: |
             [docgen] Update doc/orgmode.txt
-            skip-checks: true
         run: |
           git config user.name github-actions
           git config user.email [email protected]
           git add doc/orgmode.txt
           # Only commit and push if we have changes
           git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push)
+
+  api_docgen:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Neovim
+        uses: rhysd/action-setup-vim@v1
+        id: neovim
+        with:
+          neovim: true
+          version: v0.7.0
+      - name: Install mini.nvim
+        uses: actions/checkout@v2
+        with:
+          repository: echasnovski/mini.nvim
+          path: mini.nvim
+      - name: Generate api docs
+        run: make api_docs
+      - name: Commit changes
+        env:
+          COMMIT_MSG: |
+            [docgen] Update doc/orgmode_api.txt
+        run: |
+          git config user.name github-actions
+          git config user.email [email protected]
+          git add doc/orgmode_api.txt
+          # Only commit and push if we have changes
+          git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push)

.gitignore

@@ -41,3 +41,4 @@ luac.out
 
 plenary.nvim/
 nvim-treesitter/
+mini.nvim/

Makefile

@@ -6,5 +6,7 @@ ci:
 	nvim --noplugin --clean -u tests/minimal_init.vim -c "TSUpdateSync org" -c "qa!" && make test
 docs:
 	md2vim -desc "*orgmode* *orgmode.nvim*\n* NOTE: This file is autogenerated from DOCS.md file" DOCS.md doc/orgmode.txt
+api_docs:
+	nvim --headless --clean -u ./scripts/gendoc.lua
 format:
 	stylua lua/ tests/

doc/orgmode_api.txt

@@ -0,0 +1,114 @@
+==============================================================================
+------------------------------------------------------------------------------
+                                                                 *OrgApi.load()*
+                             `OrgApi.load`({name})
+Parameters~
+{name} `(optional)` `(string|string[])` specific file names to return (absolute path). If ommitted, returns all loaded files
+Return~
+OrgFile|OrgFile[]
+
+------------------------------------------------------------------------------
+                                                              *OrgApi.current()*
+                               `OrgApi.current`()
+Get current org buffer file
+Return~
+OrgFile
+
+
+==============================================================================
+------------------------------------------------------------------------------
+                                                                       *OrgFile*
+                                   `OrgFile`
+Class~
+{OrgFile}
+Fields~
+{category} `(string)` current file category name. By default only filename without extension unless defined via #+CATEGORY directive
+{filename} `(string)` absolute path of the current file
+{headlines} OrgHeadline[]
+{is_archive_file} `(boolean)`
+
+------------------------------------------------------------------------------
+                                                              *OrgFile:reload()*
+                               `OrgFile:reload`()
+Return refreshed instance of the file
+Return~
+OrgFile
+
+
+==============================================================================
+------------------------------------------------------------------------------
+                                                                   *OrgHeadline*
+                                 `OrgHeadline`
+Class~
+{OrgHeadline}
+Fields~
+{title} `(string)` headline title without todo keyword, tags and priority. Ex. `* TODO I am a headline  :SOMETAG:` returns `I am a headline`
+{line} `(string)` full headline line
+{todo_value} `(optional)` `(string)` todo keyword of the headline (Example: TODO, DONE)
+{todo_type} `(optional)` `(string)` | "'TODO'" | "'DONE'" | "''"
+{tags} `(string[])` List of own tags
+{deadline} `(Date|nil)`
+{scheduled} `(Date|nil)`
+{closed} `(Date|nil)`
+{dates} Date[] List of all dates that are not "plan" dates
+{position} Range
+{all_tags} `(string[])` List of all tags (own + inherited)
+{file} OrgFile
+{parent} `(OrgHeadline|nil)`
+{priority} `(string|nil)`
+{headlines} OrgHeadline[]
+
+------------------------------------------------------------------------------
+                                                          *OrgHeadline:reload()*
+                             `OrgHeadline:reload`()
+Return updated version of headline
+Return~
+OrgHeadline
+
+------------------------------------------------------------------------------
+                                                        *OrgHeadline:set_tags()*
+                         `OrgHeadline:set_tags`({tags})
+Set tags on the headline. This replaces all current tags with provided ones
+Parameters~
+{tags} `(string[])`
+Return~
+Promise
+
+------------------------------------------------------------------------------
+                                                     *OrgHeadline:priority_up()*
+                          `OrgHeadline:priority_up`()
+Increase priority on a headline
+Return~
+Promise
+
+------------------------------------------------------------------------------
+                                                   *OrgHeadline:priority_down()*
+                         `OrgHeadline:priority_down`()
+Decrease priority on a headline
+Return~
+Promise
+
+------------------------------------------------------------------------------
+                                                    *OrgHeadline:set_priority()*
+                     `OrgHeadline:set_priority`({priority})
+Set specific priority on a headline. Empty string clears the priority
+Parameters~
+{priority} `(string)`
+Return~
+Promise
+
+
+==============================================================================
+------------------------------------------------------------------------------
+                                                                   *OrgPosition*
+                                 `OrgPosition`
+Class~
+{OrgPosition}
+Fields~
+{start_line} `(number)` start line number
+{end_line} `(number)` end line number
+{start_col} `(number)` start column number
+{end_col} `(number)` end column number
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl:

lua/orgmode/api/file.lua

@@ -0,0 +1,75 @@
+local OrgHeadline = require('orgmode.api.headline')
+
+---@class OrgFile
+---@field category string current file category name. By default only filename without extension unless defined via #+CATEGORY directive
+---@field filename string absolute path of the current file
+---@field headlines OrgHeadline[]
+---@field is_archive_file boolean
+local OrgFile = {}
+
+---@param headline OrgHeadline
+---@param headlines_by_id table<string, OrgHeadline>
+---@private
+local function map_child_headlines(headline, headlines_by_id)
+  if #headline._section.sections == 0 then
+    return headline
+  end
+
+  local child_headlines = {}
+  for _, child_section in ipairs(headline._section.sections) do
+    local child_headline = headlines_by_id[child_section.id]
+    child_headline.parent = headline
+    table.insert(child_headlines, child_headline)
+    map_child_headlines(child_headline, headlines_by_id)
+  end
+  headline.headlines = child_headlines
+  return headline
+end
+
+---@private
+function OrgFile:_new(opts)
+  local data = {}
+  data.category = opts.category
+  data.filename = opts.filename
+  data.headlines = opts.headlines
+  data.is_archive_file = opts.is_archive_file or false
+  data._file = opts._file
+  setmetatable(data, self)
+  self.__index = self
+  return data
+end
+
+---@param file File
+---@private
+function OrgFile._build_from_internal_file(file)
+  local headlines = {}
+  local headlines_by_id = {}
+  for i, section in ipairs(file.sections) do
+    local headline = OrgHeadline._build_from_internal_section(section, i)
+    table.insert(headlines, headline)
+    headlines_by_id[section.id] = headline
+  end
+
+  local instance = OrgFile:_new({
+    _file = file,
+    category = file.category,
+    filename = file.filename,
+    headlines = headlines,
+    is_archive_file = file.is_archive_file,
+  })
+
+  for _, headline in ipairs(instance.headlines) do
+    map_child_headlines(headline, headlines_by_id)
+    headline.file = instance
+  end
+
+  return instance
+end
+
+--- Return refreshed instance of the file
+---@return OrgFile
+function OrgFile:reload()
+  return OrgFile._build_from_internal_file(self._file:refresh())
+end
+
+return OrgFile

lua/orgmode/api/headline.lua

@@ -0,0 +1,138 @@
+local Files = require('orgmode.parser.files')
+local utils = require('orgmode.utils')
+local ts_org = require('orgmode.treesitter')
+local OrgPosition = require('orgmode.api.position')
+local PriorityState = require('orgmode.objects.priority_state')
+
+---@class OrgHeadline
+---@field title string headline title without todo keyword, tags and priority. Ex. `* TODO I am a headline  :SOMETAG:` returns `I am a headline`
+---@field line string full headline line
+---@field todo_value? string todo keyword of the headline (Example: TODO, DONE)
+---@field todo_type? string | "'TODO'" | "'DONE'" | "''"
+---@field tags string[] List of own tags
+---@field deadline Date|nil
+---@field scheduled Date|nil
+---@field closed Date|nil
+---@field dates Date[] List of all dates that are not "plan" dates
+---@field position Range
+---@field all_tags string[] List of all tags (own + inherited)
+---@field file OrgFile
+---@field parent OrgHeadline|nil
+---@field priority string|nil
+---@field headlines OrgHeadline[]
+local OrgHeadline = {}
+
+---@private
+function OrgHeadline:_new(opts)
+  local data = {}
+  data.file = opts.file
+  data.todo_type = opts.todo_type
+  data.todo_value = opts.todo_value
+  data.title = opts.title
+  data.line = opts.line
+  data.category = opts.category
+  data.position = opts.position
+  data.tags = opts.tags
+  data.all_tags = opts.all_tags
+  data.priority = opts.priority
+  data.deadline = opts.deadline
+  data.scheduled = opts.scheduled
+  data.closed = opts.closed
+  data.dates = opts.dates
+  data.parent = opts.parent
+  data.headlines = opts.headlines or {}
+  data._section = opts._section
+  data._index = opts._index
+
+  setmetatable(data, self)
+  self.__index = self
+  return data
+end
+
+---@param section Section
+---@param index number
+---@private
+function OrgHeadline._build_from_internal_section(section, index)
+  return OrgHeadline:_new({
+    title = section.title,
+    line = section.line,
+    todo_type = section.todo_keyword.type,
+    todo_value = section.todo_keyword.value,
+    all_tags = { unpack(section.tags) },
+    tags = section:get_own_tags(),
+    position = OrgPosition:_build_from_internal_range(section.range),
+    deadline = section:get_deadline_date(),
+    scheduled = section:get_scheduled_date(),
+    closed = section:get_closed_date(),
+    dates = vim.tbl_filter(function(date)
+      return date:is_none()
+    end, section.dates),
+    priority = section.priority,
+    _section = section,
+    _index = index,
+  })
+end
+
+--- Return updated version of headline
+---@return OrgHeadline
+function OrgHeadline:reload()
+  local file = self.file:reload()
+  return file.headlines[self._index]
+end
+
+--- Set tags on the headline. This replaces all current tags with provided ones
+---@param tags string[]
+---@return Promise
+function OrgHeadline:set_tags(tags)
+  return self:_do_action(function()
+    local headline = ts_org.closest_headline()
+    return headline:set_tags(string.format(':%s:', table.concat(tags, ':')))
+  end)
+end
+
+--- Increase priority on a headline
+---@return Promise
+function OrgHeadline:priority_up()
+  return self:_do_action(function()
+    local headline = ts_org.closest_headline()
+    local _, current_priority = headline:priority()
+    local priority_state = PriorityState:new(current_priority)
+    return headline:set_priority(priority_state:increase())
+  end)
+end
+
+--- Decrease priority on a headline
+---@return Promise
+function OrgHeadline:priority_down()
+  return self:_do_action(function()
+    local headline = ts_org.closest_headline()
+    local _, current_priority = headline:priority()
+    local priority_state = PriorityState:new(current_priority)
+    return headline:set_priority(priority_state:decrease())
+  end)
+end
+
+--- Set specific priority on a headline. Empty string clears the priority
+---@param priority string
+---@return Promise
+function OrgHeadline:set_priority(priority)
+  return self:_do_action(function()
+    local headline = ts_org.closest_headline()
+    return headline:set_priority(priority)
+  end)
+end
+
+---@param action function
+---@private
+function OrgHeadline:_do_action(action)
+  return Files.update_file(self.file.filename, function()
+    local view = vim.fn.winsaveview()
+    vim.fn.cursor({ self.position.start_line, 0 })
+    return utils.promisify(action()):next(function()
+      vim.fn.winrestview(view)
+      return self:reload()
+    end)
+  end)
+end
+
+return OrgHeadline