Modules

Banpipe modules are not to be confused with Prolog modules. A banpipe module is simply a collection of source files residing in a particular directory. The name of the module is the same as the directory, e.g., if a module is placed in /home/user/modules/foo then the name of the module is foo.

In the module directory, banpipe expects to find a file called interface.pl. This is a Prolog file provided by the the module creator which contains declarations and predicates for invoking the module.

Task declarations and implementations

The interface file contains declarations of task predicates provided by the module. An task declaration has the form,

:- task(<taskname>(<input-file-types>,<options>,<output-file-types>)).

The declaration specifies that the module provides a task predicate with the name <taskname>. Such predicates always takes three arguments, a list of input files, a list of options and a list of output files. <input-file-types> is a Prolog list of terms which specifies the number and types of input files that the task predicate expects. The types are used defined and any Prolog term is a valid type. Similarly, <output-file-types> is a list of terms. The terms may contain variables, which may be shared between input types and output types. In this way, an output file type, may depend on an input file type. <options> is a of terms of arity one. The functor serves as key and the argument serves as value. Options may also contain variables.

The connection between modules and banpipe scripts

Suppose that the interface file /home/user/modules/foo/interface.pl, i.e. of the module foo includes a task declaration:

:- task(bar([_],[],[_])

The name of task is bar and it takes one input file (of unspecified type _), it takes no options and it writes one output file (of unspecified type _). Furthermore, the interface file contains a task predicate,

bar([InFile],_,[OutFile]) :- ...

This predicate will be called (see below) with ground filenames. Banpipe guarantees that InFile is available when the predicate is called and expects are OutFile is available (has been written) when the predicate terminates.

The task predicate gets called when a goal of a dependency rule in the banpipe script refers to the task predicate in its body, e.g.,

foobar <- foo::bar(['file:://tmp/infile']).

When the goal banpipe::run(foobar,File) is called then a new Prolog process will be started and the /home/user/modules/foo/interface.pl will be consulted (from the /home/user/modules/foo/ directory). This prolog process will then call the bar task predicate with Infile='/tmp/infile' and OutFile being a unique filename generated by the system. When banpipe::run(foobar,File) finishes File is unified to this unique file.

The invoke_with/1 predicate

Interface files may also contain an optional invoke_with/1 declaration, i.e., the declaration

:- invoke_with(swipl)

specifies that the interface.pl should be loaded with SWI-prolog. The current list of valid arguments for invoke_with/1 are

• prism (PRISM - this is the default)
• bp (B-Prolog)
• swipl (SWI-Prolog)
• gprolog (GNU-Prolog)