How tpope/vim-projectionist works
Project type and purpose
• This is a Vim‐plugin, written in Vimscript, called “projectionist.vim.”
File structure
• Top‐level:
– README.markdown, CONTRIBUTING.markdown – project docs
– .github – CI/funding metadata
• autoload/
– projectionist.vim – core logic loaded on-demand via Vim’s autoload mechanism
• plugin/
– projectionist.vim – entry point, defines commands and autocommands at startup
• doc/
– projectionist.txt – help file (generated from README for :help)
• (Optional) .projections.json – user’s per‐project config (not in repo, but supported)
README for additional insights
• The README describes:
– “g:projectionist_heuristics” (global configuration)
– .projections.json (per-project config)
– Navigation commands (E*, A*, S*, V*, T* variants)
– Alternate file lookup, buffer‐local configuration (make, dispatch)
– Integration points (e.g., dispatch.vim, Rails/Vim plugins)
Main components
a. Vim Editor (host environment)
b. Plugin Manager / Package Loader
c. projectionist.vim (plugin/ – startup entrypoint)
d. projectionist#* functions (autoload/ – core logic)
e. User Configuration
• g:projectionist_heuristics (global Vimscript variable)
• .projections.json (per‐project JSON file)
f. File System (project files & directories)
g. External Integrations (optional plugins, e.g., dispatch.vim)
Relationships and interactions
• On Vim startup, the Package Loader sources plugin/projectionist.vim.
• That script:
– registers :E*, :A*, etc. commands
– sets up autocommands to lazily load autoload/projectionist.vim on first use
• When a projectionist command runs:
– autoload/projectionist.vim is sourced
– it reads configuration (g:projectionist_heuristics and/or .projections.json)
– it resolves globs against the File System
– generates navigation targets or boilerplate templates
– optionally invokes external tools (e.g., dispatch.vim commands)
• Results are returned to the user as new buffers, splits, etc.
Architectural patterns and design principles
• Vimscript “plugin + autoload” pattern for fast startup + lazy loading
• Declarative configuration (heuristics JSON) separated from code
• Command-pattern: each projection type yields a Vim command (:Ehook, :Eplugin, etc.)
• Single responsibility:
– plugin/ script = interface/registration
– autoload/ = core logic + JSON parsing + FS ops
– doc/ = user help
• Extensibility: users and other plugins can define new projection types