RFC: Plugin architecture about geometry HOT 17 CLOSED

I'll leave this issue open for general discussion and feedback while keeping most technical details/implementation discussion on a PR.

from geometry.

I like this idea. It's starting to become difficult to maintain and the original idea behind geometry was trying to keep it minimal. I'd rather have a clean option with sane, minimal defaults and try to remove the unused code overhead.

What's your take on option flags? For example the git conflict count. Would it still be set by an environment variable?

from geometry.

Yeah, I think so. All plugin-related environment variables will be defined -set up, defaults etc- in the plugin code, thus will be, sort of, invisible to geometry.

from geometry.

I'm definitely up for this. There are a few things we would need to decide though:

• define minimal features
• define plugin function API
• define naming guidelines (function, variables and option flags)

from geometry.

As Minimal features:

• Ability to load informative prompts at run time (git, virtualenv, docker)
• Ability to load custom prompts

Plugin interface:

# One-time only function to setup plugin configuration variables
# and register with geometry as a plugin
geometry_prompt_<plugin_name>_setup

# Prompt rendering function
geometry_prompt_<plugin_name>_render

# These probably belong to the plugin itself rather than geometry
GEOMETRY_PROMPT_<plugin_name>_ENABLED (?)
GEOMETRY_PROMPT_<plugin_name>_COLOR (?)

On the geometry_prompt_<plugin_name>_setup function the plugin will register itself with geometry as a plugin as follows:

geometry_prompt_<plugin_name>_setup () {
    geometry_plugin_register <plugin_name>
}    

On geometry_prompt_<plugin_name>_render it will render itself, probably already colorized. Returning the final result.

Naming guidelines could be as simple as:

`geometry_prompt_<plugin_name>_*` for functions, and `-geometry_prompt_<plugin_name>_*` for "private" functions.

`GEOMETRY_PROMPT_<plugin_name>_*` for configuration variables/flags.

Prompt rendering order will depend on the registration/loading order, so it'll be fully manipulable by the user.

I'm probably missing something out, but that's an initial attempt.

from geometry.

I'm fine with the setup/render approach. The function and variable naming goes with what we already have set up. I'm finishing a README draft that can include those recommendations for contibuting.

A couple more topics:

How would you implement the plugin file sourcing by geometry?

What would the register function do, internally?

What would be the core of geometry? I'm inclined to just use the theme with async properties.

I also think we should have a plugins/ directory, containing a directory per plugin with <plugin>.zsh and a README.md

from geometry.

How would you implement the plugin file sourcing by geometry?

In geometry's own setup function it'll iterate over the registered plugins and try to load the plugin by naming convention from geometry's own plugins: $GEOMETRY_ROOT/plugins/geometry_prompt_<plugin_name>.zsh

Custom plugins will be sourced by the user after geometry:

source geometry.zsh # Will load default plugins: git, virtualenv etc
source custom_geometry_prompt.zsh # will register itself with geometry

To enable/disable default prompts:

GEOMETRY_PROMPT_DEFAULT_PROMPTS=(git virtualenv etc) 

Before sourcing geometry.

What would the register function do, internally?

It will add the plugin name to the registered plugins' array. Probably pre-formatting the prompt to keep performance reasonable.

What would be the core of geometry? I'm inclined to just use the theme with async properties.

Agreed. Most rprompt functions should be default plugins with git enabled by default.

I also think we should have a plugins/ directory, containing a directory per plugin with .zsh and a README.md

Agreed.

from geometry.

I'm also thinking shutdown and unregister functions.

BTW these changes can be fully backward compatible if we choose to load all default plugins by default and let them choose to be rendered or not (setup could return a flag to further be registered or not).

from geometry.

I like that the plugins get a setup function but if geometry will be iterating over the global array and the plugins will always be in the default directory, do they still need to register with geometry? The way I see that would be if it was a custom plugin that isn't bundled with geometry.

from geometry.

Can you elaborate on the shutdown function?

from geometry.

Geometry itself will register the default plugins from GEOMETRY_PROMPT_DEFAULT_PROMPTS array in the setup function. Instead of registering they could be sourced, but I'd prefer to use the plugin interface.

The shutdown function will be defined, if needed, by plugins in order to call unfunction, remove variables, hooks etc. Probably called on the unregister function, used to remove informative prompts at run time.

from geometry.

I'm fine with using the interface.

However, I think this work should start in a separate branch and break backwards compatibility. Most of the current option flags should be set aside to an external plugin and leave only some defaults like git and async, as well as the prompt symbol/colors customization. I really like the idea of stripping down the prompt in order to get it minimal and have it grow according to the needs of each developer, not having a lot of defaults. We can bundle a bunch of plugins with the prompt to be set if the user wants to.

from geometry.

Fine. I'll create a feature branch today and sketch the minimal working version, we'll move from there.

from geometry.

Cool. We can leave this issue open for future reference and for anyone to jump in and give their opinion, but we should probably keep PRs open to accompany progress and make decisions as they come up.

from geometry.

Once #45 gets merged, the new plugin architecture will be implemented. However, as you mentioned, there are still a couple of things remaining. Off the top of my head:

• README (on it)
• Add a README with documentation for each plugin
• Compile step of default plugins into geometry (not necessary for 2.0, just a nice to-have)
• Complete config for custom separator (some plugins still use default :: as far as I could tell)
• Enforce naming conventions
• Left prompt customization

from geometry.

Alright. I'll be creating github issues for the point listed above. We can move from there.

from geometry.

I'm closing this up as plugin structure is already set up and deployed. Missing/pending points have their own issues to keep track of them.

from geometry.