D 2019-06-22T11:44:12.288
L modules
N text/x-markdown
U jef
W 3192
### abc2svg - modules
This small document explains how to write a module for abc2svg.
#### Constraints
Modules in abc2svg may add a lot of specific features, but they are not easy
to develop, and anything may not be possible.
The main principle is: 'eval' is forbidden.
So, the code of the modules is not inserted in the Abc object.
Then, a module may call only a subset of the core functions, and,
also, it may put hooks (i.e. execute code before or after
a core function) only on a smaller subset of functions.
#### Shared functions and objects
The abc2svg functions and objects that are seen by the modules are
the ones defined by
`Abc.prototype.xxx`
either in `core/tail.js` or in the other core source files,
close to the function bodies.
From the module, they are seen as methods of the `Abc` instance.
At the hook level, the variable `this` points to this instance.
In the lower levels, the pointer has to be passed as a parameter.
For example, getting the state of the ABC parser (hook level) is done by:
` this.parser.state`
#### Hook functions
The functions of the modules are called from the core by *hooks*.
A hook is a shared function which is called by the Abc instance
in the core itself (in the core, the Abc instance is the variable `self`).
In turn, this function may be replaced by a function of a module thanks to
a *bind*. For exemple (`abc` is the Abc instance):
`abc.do_pscom = abc2svg.mymodule.do_pscom.bind(abc, abc.do_pscom)`
The associated function in the module is called with one more argument
than the native function:
```
do_pscom: function(of, text) {
}
```
*of* is the original (core) function which may be called (or not) with
its normal arguments
` of(text)`
#### Module layout
The core of the module is an object which is added to the abc2svg object.
Example:
```
abc2svg.mymodule = {
fn1: function(param) {
},
fn2: function(args) {
}
}
```
This object contains 3 parts:
- the internal variables and functions of the module
- the functions which are directly called by hooks
- the declaration of the hooks
The declaration of the hooks is a single function which is put in the
array `abc2svg.modules.hooks`.
The argument of this function is the Abc instance.
Apart its core object, a module contains two lines of code:
- a first one which adds the hook declaration function in the core:
` abc2svg.modules.hooks.push(abc2svg.mymodule.set_hooks)`
- and a second one which declares the module as 'loaded':
` abc2svg.modules.mymodule.loaded = true`
#### Usage
The modules may be loaded before or after the creation of the Abc instances.
A module may be:
- included with the core (single script),
- explicitly loaded in a specific batch script (after the abc2svg core),
- explicitly loaded as the first file in the command line when running
one of the abc2svg batch scripts,
- explicitly loaded by a script element in web pages,
- automatically loaded when it is associated to a specific command
(pseudo-comment) and when this command is declared in the module table
of the core (in js/modules.js).
Z f92537f599e51ca9979ed402995a72fa