NAME

OWL2Perl - Perl extension for the automatic generation of perl modules from OWL classes

SYNOPSIS

# to get started, run the install script (do this only once, upon initial install)
owl2perl-install.pl

# load the OWL2Perl module
use OWL2Perl;

# instantiate an OWL2Perl module
# we will output to /tmp/ and follow ontology imports
my $owl2perl = OWL2Perl->new(
   outdir => '/tmp/',
   follow_imports => 1,
);

# get the output directory
my $outdir = $owl2perl->outdir();

# set the output directory
$owl2perl->outdir($outdir);

# do we follow imports?
print 'following imports', "\n" if $owl2perl->follow_imports();

# parse an OWL document that we will generate modules for
# we will parse the URL: http://sadiframework.org/ontologies/records.owl
my $ontology_url = 'http://sadiframework.org/ontologies/records.owl';

# this may take minutes to complete
my $ontology = $owl2perl->process_owl([$ontology_url]);

# generate the actual Perl modules
$owl2perl->generate_datatypes($ontology);

# generate the actual Perl modules (for print to STDOUT)
my $out = '';
$owl2perl->generate_datatypes($ontology, \$out);
print STDOUT $out;

DESCRIPTION

A module to aid in the genesis of Perl modules that represent OWL entities in OWL ontologies.

Upgrading from a version prior to Version 0.97

For those of you upgrading from a version prior to version 0.97, you will need to regenerate your modules for any OWL ontologies that you use. This latest version of OWL2Perl utilizes new methods for serializing OWL/RDF and is not compatible with previous versions. The generated modules themselves should still behave as expected and should not have changed too much (except for the additional perldoc in each generated class).

Upgrading from a version prior to Version 0.96

For those of you upgrading from a version prior to version 0.96, you may need to regenerate your modules for any OWL ontologies that you use.

Not every one will need to regenerate their source code. Only those of you that use owl:hasValue and owl:maxCardinality property restrictions. Even if you use these constructs, you dont have to regenerate your source code unless you want OWL2Perl to catch those instances where you may provide too many property restrictions or where you don't explicitly provide the hasValue restriction.

OWL2Perl Installation

Assuming that you have already installed this package, the very first thing that you should do is run the script owl2perl-install.pl.

This script will do the following:

Check your system for prerequisite modules

Run you through the configuration of the OWL2Perl module

Create the logging and generator configuration files

Once the installation process is complete you can generate Perl modules for your ontology!

Bits and Pieces

Requirements

The following modules (all available from CPAN) are required for the proper function of this module:

Carp

File::Spec

File::Path

File::HomeDir

File::ShareDir

Config::Simple

Log::Log4perl

A great port of the Log4j and enables logging in OWL2Perl

HTTP::Date

Template

This wonderful module is used to construct the templates for our OWL entities.

Params::Util

Scalar::List::Utils (also known as Scalar::Util)

There may be a problem obtaining the latest version of this module on windows. The most recent available version (on PPM) for windows is suffice to get this working.

Class::Inspector

Unicode::String

IO::String

RDF::Core

This module is used to serialize the OWL entities as RDF/XML.

LS

HTTP::Request

LWP

PLUTO

This groundbreaking module is used to parse OWL documents.

URI

Scripts

owl2perl-install.pl

The install script is installed at module install time and is available from any command prompt. You should run this script the very first time you install this module on your system and you can run it anytime later. The files that are already created will not be overwritten - unless you want them to be!

A typical outcome of running this script is shown below:

C:\Users\Eddie\Documents>owl2perl-install
Welcome! Preparing stage for OWL2Perl ...
------------------------------------------------------
OK. Module Carp is installed.
OK. Module File::Spec is installed.
OK. Module Config::Simple is installed.
OK. Module File::HomeDir is installed.
OK. Module File::ShareDir is installed.
OK. Module Log::Log4perl is installed.
OK. Module HTTP::Date is installed.
OK. Module Template is installed.
OK. Module Params::Util is installed.
OK. Module Class::Inspector is installed.
OK. Module Unicode::String is installed.
OK. Module IO::String is installed.
OK. Module RDF::Core is installed.
OK. Module Term::ReadLine is installed.

Installing in C:\Users\Eddie\Perl-OWL2Perl 

Created install directory 'C:\Users\Eddie\Perl-OWL2Perl'.

Logging property file created: 'C:/Users/Eddie/Perl-OWL2Perl/log4perl.properties'.

Created generated 'C:/Users/Eddie/Perl-OWL2Perl/generated'.

Configuration file created: 'C:\Users\Eddie\Perl-OWL2Perl\owl2perl-config.cfg'.

Done.

C:\Users\Eddie\Documents>

On windows, the script is available on your PATH as owl2perl-install with no .pl extension.

owl2perl-generate-modules.pl

This script is a simple way for you to generate Perl modules representing your OWL entities.

Running the script without parameters provides you with details on how to use this particular script:

C:\Users\Eddie\Documents>owl2perl-generate-modules
Subroutine XML::Namespace::rdf redefined at C:/Perl/site/lib/XML/Namespace.pm line 54.
Generate perl modules from OWL files.
Usage: [-vdsib] [-o outdir] owl-class-file
       [-vdsi] [-o outdir] -u owl-class-url

    -u ... owl is from url
    -s ... show generated code on STDOUT
           (no file is created, disabled when no data type name given)

    -b ... option to specify the base uri for the owl document (you will be prompted)

    -i ... follow owl import statements

    -v ... verbose
    -d ... debug
    -h ... help

Note: This script requires that the PERL module ODO, from IBM Semantic Layered
      Research Platform be installed on your workstation! ODO is available on CPAN
      as PLUTO.


C:\Users\Eddie\Documents>

As you can see, this helper script helps you generate the Perl modules from OWL documents.

An obvious question to ask at this point, is 'Where are these modules generated'?

You can always determine this after generation by looking into your LOG file; the generator has verbose output using the INFO level which means that it is almost always logged. But if you want to know in advance, here are the rules:

generators.outdir

This parameter in the configuration file, if defined, is the location of the directory where the Perl modules are created.

'generated' directory

If there is no generators.outdir defined in the configuration file, then the generator tries to locate an existing directory named 'generated' anywhere in the @INC (a set of directories used by Perl to locate its modules).

When all else fails

the generator creates a new directory 'generated' in the 'current' directory.

Usage:

owl2perl-generate-modules.pl [-vdsib] [-o outdir] owl-class-file

owl2perl-generate-modules.pl [-vdsib] [-o outdir] -u owl-class-url

There are many command line switches available to those of you running this script:

-u

owl is from url

-s

show generated code on STDOUT (no file is created)

-b

specify the base uri for the owl document (you will be prompted for it)

-i

follow owl import statements

-v

verbose

-d

debug

-h

show help

Getting Started

The very first thing that you need to do upon initial installation of this module is to run the script owl2perl-install.pl that comes bundled with this module. This script is available on your PATH upon installation of this module.

You will only need to run this script once (unless we tell you otherwise). This script ensures that the correct dependencies are available on your machine. As well, the script sets up a directory in your home directory under the name Perl-OWL2Perl/ and places some configuration files in it. These configuration files help you specify the XML parser that should be used, places to save generated files, and much more.

To generate Perl modules representing OWL classes from your ontology, you can do 1 of 2 things! Use the

owl2perl-generate-modules.pl script

This script is included with this distribution and placed on your PATH upon installation of this module, or

OWL2Perl

Use this module and programmatically do what owl2perl-generate-modules.pl does.

Regardless of the method that you choose, the outcome is the (hopefully) same; create a set of modules that can be integrated into your perl project that represent OWL entities in your ontology!

For a quick overview of what the owl2perl-generate-modules.pl script can do, please take a look at the html document that can be found at doc/working_with_datatypes.html. This file contains a quick overview that can get you started quite quickly.

Subroutines

new()

Instantiate an OWL2Perl object.

Inputs:

outdir (optional)

The output directory for our generated Perl modules. This parameter over-rides the one in the OWL2Perl configuration file (generated when you ran owl2perl-install.pl after installing the module).

force (optional)

Boolean, 0 or 1 to determine whether or not we should over-write pre-existing generated files of the same name. The default is 0.

follow_imports (optional)

Boolean, 0 or 1 to determine whether or not owl:import statements should be followed during the process_owl. The default is 0, e.g. not to follow.

process_owl($url_array_ref, $baseuri_array_ref)

The subroutine, generate_datatypes, consumes an ODO::Ontology::OWL::Lite object and can be hard to set up by yourself. The subroutine process_owl is here to help you out.

Inputs:

$url_array_ref

an array reference of URLs or absolute file locations for the ontology to be parsed.

$baseuri_array_ref

an array reference of base URIs for your ontology (optional). If a URL is specified, then the current base URI is that URL unless you specify one yourself. Please not that if your ontology specifies a base URI, then this parameter is ignored.

Outputs:

an ODO::Ontology::OWL::Lite object created by parsing the input URL.

generate_datatypes($ontology, $scalar_ref)

This subroutine produces the Perl modules representing OWL entities parsed by PLUTO. The generated modules will either be saved to disk or represented by $scalar_ref, depending on whether you setup an output directory and if you passed in a scalar_ref.

Inputs:

$ontology

an ODO::Ontology::OWL::Lite object created from your ontology.

$scalar_ref

an optional reference to a scalar to hold the generated code.

Outputs: Nothing... well, like I said earlier, either the modules are written to disk or the passed in scalar reference will contain the modules as a string.

COPYRIGHT

Copyright (c) 2010, Edward Kawas All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, 
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.
* Neither the name of the University of British Columbia nor the names of 
  its contributors may be used to endorse or promote products derived from 
  this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cpanm OWL2Perl

perl -MCPAN -e shell
install OWL2Perl