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).