Plugins infrastructure

[kristijanhusak]

Any suggestions how to improve infrastructure for building orgmode plugins should be posted here.

[lyndsysimon]

I just discovered this project and am interested in helping, but don't have enough context yet to make any concrete suggestions.

Once I figure out the out-of-the-box functionality, I know I'm going to want to integrate this into telescope.nvim. Beyond that, I'm not sure - but by all means, if there's something in particular that you are interested in, let me know. I plan to spend some time on this if I can get it to suit my needs, and to use it as a means of keeping my Lua skills from getting too rusty :)

[kristijanhusak]

@lyndsysimon what would integration with Telescope do? I still didn't expose any particular API publicly , since no one showed interest in it. Let me know what you would need for your plugin.

[samyak-jain]

I'm not sure how things work on emacs land but one thing that could be pretty helpful is accessing the parser and functionality as APIs. To be more specific stuff like

• I want to parse the org file and then every time there's a change in any tasks, to sync with my caldav server.
• The ability to manipulate the UI. If I have each org task to have a unique identifier, I don't want to clutter the file with this metadata. So, maybe someway to hide this kind of information.
• The ability to make changes. Say when I'm pulling changes from my caldav server, and a task is now marked as DONE. I would want the ability for the plugin to be able to modify the keywords of a particular task.

Also, do we maintain some sort of AST internally to represent this file. Would it be possible to read and manipulate that directly?

These are just some few examples but overall I think having the APIs to parse org file, manipulate the UI and then make changes to the Org file are going to be valuable for plugin developers. Not sure which of these things would come under the purview of this plugin infrastructure but it would be nice to hear some thoughts on this.

[joshpetit]

Hey I think this issue should be pinned!

And I second part of what @samyak-jain mentioned:

one thing that could be pretty helpful is accessing the parser and functionality as APIs.

This is probably the largest thing for me, being able to get access to read properties and tags through the API would be great. I'm new to org mode (have never used it in emacs) so am thinking of something similar to orgparse. That would be very very powerful.

I can see myself turning vim into a keyboard driven acme editor with that haha. Thanks for all the work you've done on this plugin!

[kristijanhusak]

@joshpetit good idea, pinned :)

I would like to start with this, at least to provide something for start. Can you give me the list of things that you would find useful? You can use orgparse as a reference if that helps.

[joshpetit]

I've only ever had a cursory look at orgparse, but the features I find most important would be allow you to:

• Get a list of all the "nodes" (headings) in the file

This is kind of obvious haha. The question about this is whether it would get only top level nodes (*) or nested nodes as well.

• Get Sub trees of a node

So if you get the top level node, have some property like "children" that allow you to get the ones under it.

Access:

• Properties of a node (I'd assume SCHEDULED, DEADLINE, etc. would be properties? not sure)
• Tags of a node
• The node that the cursor is currently within (what heading they're currently under).
• Properties and tags set for an entire file.
• Content of a node (The text under the heading).

Some things that can be implemented with these apis above that would be useful:

• Get nodes with certain tag, property
• Get nodes scheduled for date

I think being able to get the values within the file is primarily useful, then being able to modify them would be useful as well.

This is probably pretty basic, I haven't really gotten to the point of using org in a more advanced way so there's definitely lots of things that can be added.

[joshpetit]

@lyndsysimon what would integration with Telescope do? I still didn't expose any particular API publicly , since no one showed interest in it. Let me know what you would need for your plugin.

I think one integration that would be useful with telescope is being able to go to specific headline. For example I can go to a headline in the file, or a headline in the directory by filtering with telescope.

[levouh]

+1 to tags and dates for a given node.

A first attempt at an orgparse-style API might be a good precursor to #135 as it would provide an easier way for users to read metadata about items and filter as they please.

It seems like a good breakdown of tasks here would be:

1. Read the content of a single node
2. Update the content of a single node
3. The relationships from one node to other nodes around it
4. Metadata about the file, perhaps with some easy wrappers for filtering nodes contained within a single file. Obviously the file portion can be extended to be global (where file-local stuff would be more akin to the *-tree things that Emacs has).

This leads itself quite nicely into some of the harder parts of #135, like dealing with custom configuration settings within a given scope. With a wrapper to the API, we can pretty much monkey-patch a config option onto it that can be used while filtering for a given scope, then thrown away.

[joshpetit]

@kristijanhusak If you think copying the orgparse API would be ok then I can help with it. Do you think it makes sense to make an org parser in lua for nvim? Don't see one that's already been made.

[levouh]

The Treesitter grammar should do most of what we would need for parsing. A lot of it is already implemented as well (e.g. all headlines for a given file), it just needs to be exposed in a "simple" way.

[kristijanhusak]

@joshpetit We could copy some ideas from there, but I don't want to make it 1 to 1. I'll set up something basic in following weeks and we can expand on it easily.

[lyndsysimon]

@lyndsysimon what would integration with Telescope do? I still didn't expose any particular API publicly , since no one showed interest in it. Let me know what you would need for your plugin.

I ended up not continuing to use this plugin so I still don't have the necessary context, but generally speaking I was looking at making all of the navigation tasks (agenda, todos, etc.) present in telescope if it is installed.

[NickHu]

I'm writing a Google calendar plugin, and I'd really like some way to hook into how the agenda view is built and maybe also some way to override what happens when you hit Enter on an agenda entry.

[jgollenz]

@kristijanhusak do you know how these things work in emacs? Is there an exposed API?

[kristijanhusak]

Initial version of the api was added in #331. It has just few basic things like listing the org files, their headlines, and updating basic things (priority, tags). Docs are generated with mini.nvim automatically, you can read it here https://github.com/nvim-orgmode/orgmode/blob/master/doc/orgmode_api.txt. Here's small example how to get list of all headline lines from all files:

local api = require('orgmode.api')
local files = api.load()
local headlines = {}
for _, file in ipairs(files) do
  vim.list_extend(headlines, vim.tbl_map(function(h) return h.line end, file.headlines))
end
return headlines

Plan is to expand more on this by introducing more actions to manipulate the files.

[kristijanhusak]

@jgollenz I don't know. From what I saw, people are calling some orgmode code in the plugins, but I'm not sure if it's just the builtin one or there is some exposed api for that.

[joshpetit]

One thing I think would be pretty valuable is having a properties field within the OrgHeadline object. I feel like I co

[joaomsa]

Started a plugin for telescope integration, feedback welcome:

https://github.com/joaomsa/telescope-orgmode.nvim

Had to dig into a few internal things beyond what's currently exposed on OrgHeadline like Section:level and Section:is_archived(), can I just do a PR adding them or was there some reasoning for not exposing it?

Also I ended up having to dig into the internal Capture:refile* functions to get the refile working. I think we can make commands be a bit more composable or perhaps allow overriding the selection UI by plugins. Any thoughts on this?

[kristijanhusak]

Had to dig into a few internal things beyond what's currently exposed on OrgHeadline like Section:level and Section:is_archived(), can I just do a PR adding them or was there some reasoning for not exposing it?
Also I ended up having to dig into the internal Capture:refile* functions to get the refile working. I think we can make commands be a bit more composable or perhaps allow overriding the selection UI by plugins. Any thoughts on this?

I wouldn't suggest using internals since those might be changed. If you can please create a PR to expose the functionality through the api, so we have a compatible layer in case of any changes.

[mdietrich16]

I would love to have access to the running clock to make pomodoro possible and also implement an idle timer. So, API access to the instance members would be nice, as well as an easy link to the currently clocked in headline.

[lyz-code]

@kristijanhusak I'm trying to use OrgApiHeadline to do some actions:

• set_todo
• clock_in

The first one works with headline._section:set_todo("DOING"), but headline._section:clock_in() doesn't work, If I do headline._section:is_clocked_in() afterwards it shows as false.

I guess that accessing the private attribute _section is not the ideal. In these cases shall I create a public method that just calls the private one and create a PR?