/ 
Devel-ModInfo-2.04
River stage one • 1 direct dependent • 1 total dependent
/ Devel::ModInfo::Tutorial

ModInfo - A Perl Interface Definition System

Purpose

ModInfo was developed to fulfill a lack of introspective metadata for modules in the current Perl language. When creating a complex system of inter-related object-oriented packages in Perl (or any language), it is useful to be able to not only document the interfaces (i.e., the methods, constructors, and functions) you are creating as you go along.

ModInfo was designed to be simple to use, easy to maintain, and flexible enough to be applied in other ways. The developer simply adds comment lines to the Perl module code which conform to a predefined syntax, and ModInfo utilities use these comments to create persist the interface definition metadata to XML. A Perl object model is used to present the metadata to the developer.

The XML files are named the same as the modules they describe and are given the .mfo extension. They are intended to reside in the @INC path alongside the modules. ModInfo uses the @INC path to locate the .mfo files and parses them as XML to generate the in-memory objects that describe the interface.

Usage

To use ModInfo in your own code, you should comment your code using the special ModInfo directives (see below). These will define the methods, properties, etc that you want to be made visible through ModInfo. To get a head start, you can run your module through the pl2modinfo.pl processing script. This will automatically "stub out" your code with some preliminary ModInfo code. On the command line, you might do it like this:

perl pl2modinfo.pl -wi MyModule.pm

This will overwrite your current MyModule.pm with a new version that has the ModInfo directives in it. You might want to make a backup of your original module before doing this, just in case something goes wrong. Once your module is stubbed out, you can remove the ModInfo directives for things you don't want to be made visible, and change the things that the stubber got wrong. (For more information on pl2modinfo.pl, enter "perldoc pl2modinfo.pl" or "pl2modinfo.pl -h" on the command line)

Once you've commented your code, you need to run your module through the modinfo2xml.pl processor. This will create a .mfo file for your module that distills the ModInfo directives into XML. The .mfo file is what ModInfo itself uses when queried about your module's interface.

On the command line, it might look like this:

perl modinfo2xml.pl -i MyModule.pm

This will create a file named MyModule.mfo in the same directory as MyModule.pm. It is important that the .mfo file stay alongside the .pm file. In fact, you should consider making the file part of your Module's distribution if you upload it to CPAN. (For more information on modinfo2xml.pl, enter "perldoc modinfo2xml.pl" or "modinfo2xml.pl -h" on the command line)

One example of how ModInfo can be used is included in the distribution. It is a simple script that uses the Template Toolkit to convert the ModInfo object model into HTML documentation. It can operate on a single module, or on an entire directory structure. If you were to run it on our previous example module, the command line would look like this:

perl modinfo2html.pl -m MyModule

Note that this script only takes the package name, not the file name. The module (.pm file) must be in your @INC path, and the .mfo file must be in the same location. By default the HTML will go to STDOUT. If you want to simply create a file of the same basename as the .pm file, but with a .html extension, you can supply the -f parameter as well.

(For more information on modinfo2html.pl, enter "perldoc modinfo2html.pl" or "modinfo2html.pl -h" on the command line)

ModInfo Directives

ModInfo directives are simple Perl comments embedded in Perl code, which the modinfo2xml.pl processor can interpret.

Each directive begins with the standard Perl comment character and the word MODINFO in all caps. The directive then follows, like so:

# MODINFO directive parameter parameter

Some directives are "delimiting," meaning they mark the beginning of a new scope, such as the scope of an entire module, or the scope of a single function. Delimiters are considered to be in effect until the next delimiter of same or higher scope is encountered.

The following directives are currently recognized by the processor:

  • module [name] [short description]

    A delimiting directive that defines a Perl package. The package may or may not be object-oriented. The package directive is considered to be in effect until another package directive is encountered.

  • icon [file_path] (valid within: package)

    A directive used to define the path for an icon that can be used to represent the module. Path should be relative to the module itself.

  • constructor [name] [short description] (valid within: package)

    A delimiting directive that defines an object-oriented constructor for an object-oriented package.

  • method [name] [short description] (valid within: package)

  • function [name] [short description] (valid within: package)

  • param [name] [datatype] [short description] (valid within: function/method/constructor)

  • paramarray [name] [short description] (valid within: function/method/constructor)

  • paramhash [name] [short description] (valid within: function/method/constructor)

  • key [name] [datatype] [short description] (valid within: paramhash)

  • retval [datatype] or: retval (valid within: function/method/constructor)

    The second option indicates that the function does not return a value

  • property [name] [datatype] [short description] (valid within: function/method/constructor)

  • read [name] [short description] (valid within: property)

  • write [name] [short description] (valid within: property)

AUTHOR

    jtillman@bigfoot.com

    tcushard@bigfoot.com

SEE ALSO

ModInfo

pl2modinfo.pl

modinfo2xml.pl

modinfo2html.pl

perl(1)