@argdown/core
    Preparing search index...

    Class ArgdownApplication

    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:

    • any [[IArgdownPlugin.prepare]] methods: these methods can be used to add plugin default settings to the request and to check that all required data is present in the response object.
    • any event listeners defined in [[IArgdownPlugin.tokenListeners]] and [[IArgdownPlugin.ruleListeners]]. If any plugin in a processor defines such listeners, an ArgdownTreeWalker will be added to this processor which will visit all nodes in the abstract syntax tree (response.ast).
    • any [[IArgdownPlugin.run]] methods: these methods should be used to transform response data not contained within response.ast.

    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:

    • the AST
    • metaData contained in the front matter
    • statements and arguments dictionaries
    • the relations list
    • tag list and tagDictionary
    • the sections tree
    • metaData of arguments, statements and headings

    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.

    The @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 plugin.run(...); methods.


    import {
    ArgdownApplication,
    IArgdownRequest,
    IHtmlResponse,
    ParserPlugin,
    ModelPlugin,
    ColorPlugin,
    HtmlExportPlugin
    } from "@argdown/core";

    const app = new ArgdownApplication();

    const parserPlugin = new ParserPlugin();
    app.addPlugin(parserPlugin, "parse-input");

    const modelPlugin = new ModelPlugin();
    app.addPlugin(modelPlugin, "build-model");

    const colorPlugin = new ColorPlugin();
    app.addPlugin(colorPlugin, "build-model");

    const htmlExportPlugin = new HtmlExportPlugin();
    app.addPlugin(htmlExportPlugin, "export-html");

    const input = `
    # My first Argdown document

    [S1]: a statement
       - [A1]: an argument
    `;
    const request:IArgdownRequest = {
     input,
     process: ["parse-input", "build-model", "export-html"],
     logLevel: "verbose"
    }
    const response:IHtmlResponse = app.run(request);
    console.log(response.html);
    Index

    Constructors

    constructor

    Properties

    defaultLogger defaultProcesses logger processors

    Methods

    addPlugin getPlugin getPlugins removePlugin removeProcessor replacePlugin run

    Constructors

    Properties

    defaultLogger: IArgdownLogger = ...
    defaultProcesses: { [name: string]: string[] } = {}
    logger: IArgdownLogger
    processors: { [name: string]: IArgdownProcessor } = {}

    Methods

    • Adds a plugin to the application. Registers any tokenListeners or ruleListeners with the ArgdownTreeWalker event emitter.

      Parameters

      • plugin: IArgdownPlugin
      • OptionalprocessorId: string

        if processorId is undefined, the plugin will be added to the "default" processor

      Returns void

    • Removes a plugin from the application. Removes all tokenListeners and ruleListeners from the ArgdownTreeWalker event emitter.

      Parameters

      Returns void

    • Remove a processor and all its plugins from an application.

      Parameters

      • processorId: string

      Returns void

    • Replaces a plugin within a processor, keeping the original plugin execution order within the processor

      Parameters

      • oldPluginId: string

        the id of the plugin that should be removed

      • newPlugin: IArgdownPlugin

        the new plugin that should be added

      • OptionalprocessorId: string

        the processor to which the plugin should be added (if undefined, the default processor is used)

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods