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