Interface description for Aneamal modules

For programmers who develop modules for Aneamal

Content

Introduction

A module is a program which adds a feature that the Aneamal Translator itself does not provide. There are currently three kinds of modules:

Users can install a module easily by uploading the module folder into the aneamal directory. The name of the folder must be math for math modules and start with t- for t-modules or x- for x-modules.

In order for the Aneamal Translator to recognize the module, its folder must contain a file index.php. The structure of that file needs to look like this:

<?php
// Set an individual namespace to avoid naming conflicts
// with other modules.
namespace your\own\name\space;

// Include your additional php files, classes, functions,
// constants and so forth here.

// Finally, return an anonymous function to the Aneamal
// Translator. It is the entry point of your module. It
// is called whenever an author invokes your module. The
// function must accept an array as its first argument.
// The Aneamal Translator passes data to your module via
// this array.
return function (array $_): string {
    
// Do your main processing here and return the result.
    // The return value of this function is the output of
    // your module that is integrated in the web page.
};
// Mind the semicolon to end the return statement.

Data passed from Aneamal to modules

You can find all the data that the Aneamal Translator passes to your module in the first argument of your returned function, an array. You could name the array freely, but it is recommended to name it $_ like in the code above and in the explanations below.

The array contains some values with integer indices for backwards compatibility with older modules. Please access data only using the string indices outlined below. They are available from version 28 of the Animal Translator onwards except otherwise noted.

Data passed to all modules

$_['base'], string
The URL path component to the directory where the Aneamal file which invoked the module resides.
$_['clue'], string or null
The clue from the file token in the Aneamal file which invoked the module. It is always null for math modules which are invoked without file token and null for t- and x-modules in cases where the author did not provide a clue.
$_['here'], string
The URL path component to the module’s directory. Use this, if you need to link to stylesheets, JavaScript or media files supplied with your module.
$_['home'], string
The URL path component to the Aneamal root directory.
$_['lang'], string
A language code such as en for English that applies to where the module was invoked. Use this for localization.
$_['meta'], string or null
The metadata value assigned to the module’s name in the Aneamal file which invoked the module. This is the recommended way to accept settings from authors for your module. It is null, if no value was assigned to your module’s name. It is recommended to treat an empty string value equally.
$_['name'], string
The name of the module folder. This does not include a submodule’s subfolder name. Available since version 29.
$_['pixl'], string
The setting for the size of automatically generated preview images. How to interpret it will be explained later. Here is a German article that explains the idea and the math behind it for the time being.
$_['root'], string
The path of the Aneamal root directory in the server file system.
$_['type'], string
The full type from the file token in the Aneamal file which invoked the module. This is equal to the module folder name and, in case of a submodule, a slash and the submodule’s subfolder name. Available since version 29.

Example

Consider that Aneamal is installed for https://example.org/ and the directory on the server which corresponds to that address and inside which the aneamal folder is located is /usr/eve/public/. Also consider that the following Aneamal text is inside a file https://example.org/test/quick.nml:

@lang: en
@t-poetry: initials

[t-poetry:funny little rhyme]
|The quick brown hog jumps over the foxy dog.

The data provided by the Aneamal Translator will be:

$_['base'] = '/test';
$_['clue'] = 'funny little rhyme';
$_['here'] = '/aneamal/t-poetry';
$_['home'] = '';
$_['lang'] = 'en';
$_['meta'] = 'initials';
$_['name'] = 't-poetry';
$_['pixl'] = '-640,-640'// default value
$_['root'] = '/usr/eve/public';
$_['type'] = 't-poetry';

The Aneamal Translator will also supply data that is exclusive to t-modules for this example – see the section on t-modules.

Data passed to math modules only

$_['kind'], string
Either block or string, corresponding to whether the module was invoked to process a math block or a math string.
$_['math'], string
The text of the mathematical formula. Math modules should support AMS-LaTeX.

Example

Consider the following Aneamal text:

If $c$ is the longest side in a right triangle, \
its length can be calculated as

$$c=\sqrt{a^2+b^2}$$ #(1)

The math module will be invoked once when the first line is processed and again when the last line is processed. The exclusively math-related data provided by the Aneamal Translator will be

$_['kind'] = 'string';
$_['math'] = 'c';

in the first case and

$_['kind'] = 'block';
$_['math'] = 'c=\sqrt{a^2+b^2}';

in the second case.

Data passed to t-modules only

$_['text'], string
The content of the linked or embedded text file.

Example

Consider the following Aneamal text:

[t-poetry]
|The quick brown hog jumps over the foxy dog.

The data provided by the Aneamal Translator that is exclusive to t-modules will be:

$_['text'] = 'The quick brown hog jumps over the foxy dog.';

Data passed to x-modules only

$_['files'], array of string/null items
The links turned into paths in the server file system. The items will be null in cases where an interpretation as local file system paths does not make sense, for example when the provided link is a data URI or an absolute URL.
$_['hrefs'], array of string items
The links interpreted as URLs that can be used in the web page. Mind that you should still convert characters that would otherwise have a special meaning in HTML with a function such as PHP's htmlspecialchars before using these URLs in HTML output.
$_['links'], array of string items
The links as they were provided by the author.

Example

Consider that Aneamal is installed for https://example.org/ and the directory on the server which corresponds to that address and inside which the aneamal folder is located is /usr/eve/public/. Also consider that the following Aneamal text is inside https://example.org/test/index.nml:

[x-ample]->foo->https://aneamal.org/markup/->/bar

The data provided by the Aneamal Translator that is exclusive to x-modules will be:

$_['files'] = [
    
'/usr/eve/public/test/foo',
    
null,
    
'/usr/eve/public/bar',
];
$_['hrefs'] = [
    
'/test/foo',
    
'https://aneamal.org/markup/',
    
'/bar',
];
$_['links'] = [
    
'foo',
    
'https://aneamal.org/markup/',
    
'/bar',
];

without trailing slash

Data passed from modules to Aneamal

The main way to pass data from your module to the Aneamal Translator is via the return value of the returned function.

By all modules

The return value of your returned function will be integrated in the web page at the place which corresponds to where your module was invoked in the Aneamal file.

return function (array $_): string {
    
// Do your main processing here.

    // Return the result: you do not have to use a
    // variable named $output, it is just an example.
    
return $output;
};

By x-modules only

x-modules can communicate to the the Aneamal Translator how many links they expect authors to provide when using the module. This is done by adding the arguments $min and $max with default values to the argument list of your returned function:

return function (array $_$min 1$max 3): string {
    
// Do your main processing here and return the result.
};
$max
A positive integer default value tells the Aneamal Translator to accept at most that many file links. If you do not set $max, the Aneamal Translator will only allow one link. The Aneamal Translator will not accept more than 64206 links at once, even if you set a higher value.
$min
A positive integer default value tells the Aneamal Translator to require at least that many file links. If you do not set $min, the Aneamal Translator will require one link.