An ArgdownApplication chains together a collection of plugins, passing a request and response object between them. Each plugin uses configuration settings from the provided request object to produce or transform data saved in the provided response object. Without any plugins the ArgdownApplication will do nothing. Even the parsing and lexing of Argdown input is accomplished by the ParserPlugin.
Plugins are grouped into processors that will be executed after one another each time the run method is called. Which processors are executed in a run is determined by the request.process list.
For each processor ArgdownApplication will try to execute plugin methods in the following order:
All plugin methods called by ArgdownApplication receive a request, response and logger object as parameters. In each of the three rounds the plugins are called in the order they were added to the processor.
Most runs will first have to call the ParserPlugin, DataPlugin, ModelPlugin and TagPlugin to add the basic Argdown data to the response object. This includes:
Plugins are expected at the beginning of their prepare method to check for any missing required data in the response object. If required properties are missing, the plugin should throw an ArgdownPluginError. Throwing an error in any of the plugin methods called by ArgdownApplication will cancel the run of the current processor and skip to the next processor. All errors will be caught, collected and optionally logged by the ArgdownApplication.
Plugins should not keep any local mutable state. Instead they should use the request object for configuration and the response object for returning produced or transformed data. The only obvious exceptions are I/O plugins, for example export plugins that save the exported data as new files.
@argdown/node package provides a subclass called
AsyncArgdownApplication which adds a
AsyncArgdownApplication.runAsync method to this class.
This can be used to support Promises and async/await in I/O operations.
The app.runAsync method works exactly like the app.run method
except that it tries to call
await plugin.runAsyc(...); before calling any
Adds a plugin to the application. Registers any tokenListeners or ruleListeners with the ArgdownTreeWalker event emitter.
if processorId is undefined, the plugin will be added to the "default" processor
Get a plugin that is already part of a processor
Get the plugin list of a processor. Careful, this is not a copy!
Removes a plugin from the application. Removes all tokenListeners and ruleListeners from the ArgdownTreeWalker event emitter.
Remove a processor and all its plugins from an application.
Replaces a plugin within a processor, keeping the original plugin execution order within the processor
the id of the plugin that should be removed
the new plugin that should be added
the processor to which the plugin should be added (if undefined, the default processor is used)
Execute a chain of processors
Use request.process to define the list of processors to run. Use request.input to add ArgdownSourceCode to be processed.
Can be optionally used to start with a response from a previous run. Use this if you want to avoid to run processors again that have already done their work.
the transformed response object after all plugins have added their data.
Generated using TypeDoc