Geany Filetype Plugins

[codebrainz]

This issue is to track the design and implementation of filetype-specific plugin API to allow tighter integration and for plugins to provide advanced IDE functionality to replace or enhance functionality what Geany currently provides in a generic and basic form.

One of the key features of Geany is its lightweight, generally useful language-agnostic support (eg. TM/ctags, generic build commands, customizable default filetype configurations, etc) and it would not be good to start embedding deep knowledge of specific programming languages into the core, this is why it's crucial that such advanced (read: bloated) features remain completely contained in some kind of plugin. No user should pay the cost for such language support for languages they don't use. It's also important that Geany always provide at least its current baseline functionality. Some of the default functionality could indeed be moved into such a plugin, but it should always be the default/fallback and should work out-of-the-box.

I have experimented in the past at trying to integrate libclang into a plugin to provide some of this support for C/C++, but I assume much of it would transfer over to other languages such as using libpython to enhance Python support, or V8 engine to enhance JavaScript.

Requirements

Though there are probably some things I have not thought of, some of the requirements I've come up while experimenting with implementing this kind of advanced language features and run into road-blocks with are as follows:

• Allow plugins to provide syntax highlight.

  Remark:
  This could be in the form of providing the Scintilla lexer, either by allowing plugging in as "container lexers" or by allowing plugins to provide a lexer library loaded dynamically into Scintilla (already supported by Scintilla). Alternatively we could provide some kind of interface non-specific to Scintilla for this and have Geany deal with making the styles appear on the screen. This is to allow for advanced semantic highlighting and the likes.

• Allow plugins to provide the symbols for the tagbar tree, based on their own knowledge of the current document.

  Remark:
  It has been suggested that TagManager (with appropriate enhancements) may be suitable as a means of providing this information to Geany. Some kind of hook/provider interface would still be required in all cases.

• Allow plugins to provide the auto-complete list, given the current location in the document and the part of the word already typed.

  Remark:
  In the future this could be extended to allow plugins to provide information required to insert those templates where, for example, if a particular function is completed, it inserts a "template" of the prototype and the caret jumps to the first editable position, like the function argument name, or if no arguments into the body of the template where the user probably wants to start typing, when you press tab it keeps jumping to the next editable template placeholder. Some IDEs such as XCode provide this, and I believe Scintilla has some kind of builtin support for implementing this. Further research is required. This particular enhancement could be added afterwards and should not block this issue.

• Allow plugins to provide a list of calltips to be shown when Geany shows the calltips.

  Remark:
  In the future this could be extended to support additional features like enhanced keyboard navigation, ability to display documentation comment text, etc. Such enhancements should not block this issue.

• Allow plugins to hook into the build system runner.

  Remark:
  Plugins should be able to provide not only the default build commands, but to dynamically modify them based on user's input (eg. through some configuration dialog they provide). This would allow plugins to do stuff like generating a Makefile based on the user's choices/source code and to update the build commands to run the Makefile in some particular directory, environment, etc.

• Allow plugins to provide diagnostics when build commands are run.

  Remark:
  This could include not just allowing them to add compiler messages (which is already kind of supported if the plugin inserts Make-like change-directory messages and such into the compiler tab view), but also a more specific than current API for displaying diagnostic messages such as adding those various coloured squiggly lines below errors, putting diagnostic icons (eg. warning, info, error, etc) into the margin for affected lines, and also providing Scintilla annotations or tooltips to give the user more detailed information about the error when hovering over the squigglied text or margin markers. It should also be possible for plugins to nest further information in the compiler messages tab's treeview, so that it can show more than one line, like perhaps in the case of multiple definitions, where the original location was or other such information which may not make sense as the main information line in the compiler tab but can still be useful for some kinds of errors.

Development/Contribution Strategy

A branch will be pushed to the main Geany Github repository, for example ft-plugins, against which all pull requests should be made. This branch will be merged at appropriate/convenient intervals into Geany's stable/development branch (master).

Discussion Guidelines

Since Github comments are not an ideal discussion platform and can grow out of control, as well as to include more people, foster broader discussions (bikesheds), and in order to keep this issue nice and clean, I propose that we do most of the discussion not relating to a particular change on the development mailing list. This suggestion is only for this particular Github meta-issue, and need not apply to all related PRs, of course. If nobody minds, I would like to delete extaneous comments on this Github Issue, and keep the comments limited to such stuff as progress reports, meta discussions about the Github issue iself (assignees, labels, milestones), notes about a related PR, etc.

If there is a particular item you wish to discuss, quote it in your mailing list message and provide your suggestions, comments, issues, etc. I propose we choose some unique kind of tag (eg. "FT-plugins") to put in the subject line of each related mailing list thread to improve searchability. This way we can look back in the archives and easily find related discussions regardless whether they all happened to be nested under a single thread.

Please feel free to "add your reaction" (thumbs up or down) whether you like the overal proposal presented here, in principle, even if not some of the details.

[codebrainz]

I have edited the description to remove references about GObject interfaces as well as the Draconian contribution strategy. For the latter, I just wanted to foster active code-based contribution where feasible, but I shouldn't exclude armchair contributions :)

[codebrainz]

Related:
http://lists.geany.org/pipermail/devel/2016-August/010067.html
http://lists.geany.org/pipermail/devel/2016-August/010088.html
http://lists.geany.org/pipermail/devel/2016-August/010093.html

[codebrainz]

Meta Issue Description todo:

• Update the requirements list, showing potential callback signatures (as discussed in the '[FT-plugins] Proposed "Features' on the mailing list).
• Update the signatures proposed for at least sidebar symbol tree, and most likely auto-completion and calltips to have the ft-plugin provide information to Geany using TMTag structures (as mentioned in the same thread as above).
• Add more details about underlying basic implementation strategy once fleshed-out more on the mailing list "Proposed Design" thread.
• Remove "Development/Contribution Strategy" section. @b4n confirmed it's OK to make a new branch, and we will have to see how it goes with keeping the changes in-sync with master branch. (updated)
• Replace the "Discussion Guidelines" with a simple note about not polluting this particular Github issue, and using the mailing list instead. (oops, already done)
• Eventually add "requirement" for a callback/hook to tell the ft-plugin to re-parse the sources as per the specific suggestion at "Essentially I'd propose a signal that's emitted when Geany begins (re-)parsing a file" in this message. This will almost surely be required no matter what, to avoid duplication of it in each plugin. Needs discussion.

[codebrainz]

I haven't touched this in a year. If anyone wants to move forward with FT plugins, we should re-open this issue and continue along.

[denizzzka]

I want API for plugins!
May be just add it as copy and paste from any other IDE plugin API? And tag it as experimental.

[codebrainz]

@denizzzka if you want to move this forward, please feel free to send any pull requests, I'll re-open/update this issue if people want to work on it.