message Plugin

The message plugin allows messages to be sent to files at various points during the execution of the application.

For example, the following code in a plugin will print Hello, World! after the application starts and Goodbye, World! before it finishes. It also prints information every time a com.acme.some-event fires. All of these printings are made to file log.txt.

<?xml version="1.0"?>
<?plugin version="0.1.0"?>
<plugin id="test.message.plugin">
	<extension point="message.start" file="log.txt">Hello, World!<br/></extension>
	<extension point="message.stop" file="log.txt">Goodbye, World!<br/></extension>
	<extension point="com.acme.some-event" listener="message.listener" file="log.txt">
The ${event.id} event has just fired at <print import="print.time.now/>.
It had ${event.num-args} arguments.
Argument 0, which must be a string for this to work, was "<arg import="print.string"/>".
	</extension>
</plugin>
			

<extension point="message.start"
    file?    = file-name default "/dev/stdout"
    append?  = boolean default "true">
    <!-- Content: ( PCDATA | print | br )* -->
</extension>
<!-- Contained by: plugin -->

By extending the point, message.start, plugins can have text written to a file after the application has started.

Text will be variable expanded.

Attribute file

This attribute determines which file the text will be output to. By default it will print text to the standard output.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute append

This attribute determines if the file will be appended to or created afresh. By default the file will be appended to.

The attribute is variable expanded in the context of the extending plugin.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

<extension point="message.end"
    file?    = file-name default "/dev/stdout"
    append?  = boolean default "true">
    <!-- Content: ( PCDATA | print | br )* -->
</extension>
<!-- Contained by: plugin -->

By extending the point, message.end, plugins can have text written to a file before the application stops.

Text will be variable expanded.

Attribute file

This attribute determines which file the text will be output to. By default it will print text to the standard output.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute append

This attribute determines if the file will be appended to or created afresh. By default the file will be appended to.

The attribute is variable expanded in the context of the extending plugin.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

<listener import="message.listener"
    file?    = file-name default "/dev/stdout"
    append?  = boolean default "true">
    <!-- Content: ( PCDATA | print | arg | br )* -->
</extension>
<!-- Contained by: extension for event -->

This exports an event listener that can be used to print (basic) information about events to files.

Text will be variable expanded. Additional variables are provided: event.id and event.num-args.

Attribute file

This attribute determines which file the text will be output to. By default it will print text to the standard output.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute append

This attribute determines if the file will be appended to or created afresh. By default the file will be appended to.

The attribute is variable expanded in the context of the extending plugin.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

<br>
    <!-- Content: EMPTY -->
</br>
<!-- Contained by: message.start, message.stop, message.listener -->

Prints a new line.

<print
    symbol?  = symbol name
    library? = library id
    import?  = extension point id>
    <!-- Content: EMPTY -->
</print>
<!-- Contained by: message.start, message.stop, message.listener -->

A print element calls a function to print text to the file. The function must have signature:

void (*)( FILE* file )

Attribute symbol

The symbol attribute gives the name of a symbol for the function in one of the extending plugin's libraries. The particular library can be specified with the library attribute.

This attribute may not be used if import is used.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute library

The library attribute gives the name of the library in which a symbol for the function is found.

The attribute must not be used unless attribute, symbol, is also given.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute import

The import attribute gives the name of a symbol exported by another plugin.

This attribute may not be used if symbol is used.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

<arg
    index    = positive integer
    symbol?  = symbol name
    library? = library id
    import?  = extension point id
    format?  = string>
    <!-- Content: EMPTY -->
</arg>
<!-- Contained by: message.start, message.stop, message.listener -->

This element prints the value of an argument to the file. The printer function is given by an import or by a symbol in a library of this plugin.

The printer function must have the following prototype:

void (*)( FILE* file, void* value )

Attribute index

The index of the argument to print

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute symbol

The symbol attribute gives the name of a symbol for the function in one of the extending plugin's libraries. The particular library can be specified with the library attribute.

This attribute may not be used if import or format is used.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute library

The library attribute gives the name of the library in which a symbol for the function is found.

The attribute must not be used unless attribute, symbol, is also given.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute import

The import attribute gives the name of a symbol exported by another plugin.

This attribute may not be used if symbol or format is used.

This attribute is variable expanded. Variables are resolved in the context of the plugin.

Attribute format

This attribute allows something similar to printf to be acheived. The format string is that part of a printf format string after a %. No other characters are permitted.

For example: <arg index="1" format="4.2f"/> will assume that the 1st argument is a float and prints it as you might expect from printf( "%4.2f", arg ).

This attribute may not be used if import or symbol is used.

This attribute is variable expanded. Variables are resolved in the context of the plugin.