DlfSchema(3)

NAME
Lire::DlfSchema - Interface to Lire DLF Schema XML specifications

SYNOPSIS
In DLF converters:

    use Lire::DlfSchema;
    my $schema = Lire::DlfSchema::load_schema( "email" );
    my $dlf_maker = $schema->make_hashref2asciidlf_func( qw/time msgid
              from_user from_domain from_relay_host from_relay_ip
              size delay to_user to_domain to_relay_host to_relay_ip
              stat / );

DESCRIPTION
This module is the interface to the Lire DLF Schemas defined in XML files. A schema defines the order of the fields along with their names, descriptions, types and default values.

This module also includes one function which is mandatory to use for DLF converters: make_hashref2asciidlf_func().

  ACCESSING A SCHEMA OBJECT
The way to access a schema for a superservice is through the load_schema() module function. You use it like this:

    my $schema = Lire::DlfSchema::load_schema( $superservice);
This function will return a schema object which can then be used to query information about the schema. This function will die() on error.

SCHEMA OBJECT METHODS

  id()
    my $id = $schema->id();
This method will return the id of the schema. This will be the superservice's name for superservice's main schema. (There are other types of schema, derived and extended schemas, for which the id will be different than the superservice's name.

  superservice()
    my $super = $schema->superservice();
This method will return the superservice's name of the schema.

  title()
This method will return the human readable title of the schema. (This is the content of the title element in the XML specification.)

  description()
This method will return the description of the schema. (This is the content of the description element in the XML specification.) Be aware that this will most likely contains DocBook markup.

  field_by_pos()
    my $field = $schema->field_by_pos( 0 );
This method takes an integer as parameter and return the field at that position in the schema. Fields are indexed starting at 0. This method will die() if an invalid position is passed as parameter.

The method returns a Lire::Field(3pm) object.

  has_field()
    if ( $schema->has_field( 'test ) ) {
        print "schema has field 'test'\n";
    }
This method takes a string as parameter and returns a boolean value. That value will be true if there is a field in the schema with that name, it will be false otherwise.

  field()
    my $field = $schema->field( 'from_email' );
This method takes a field's name as parameter and returns the Lire::Field(3pm) object describing that field in the schema. The method will die() if there is no field with that name in the schema.

  fields()
    my $fields = $schema->fields;
    my @fields = $schema->fields;
In array context, this method will return an array containing all the fields (as Lire::Field(3pm) objects) in the schema. The order of the fields in the array is the order of the fields in the schema.

In scalar context, it will return an array reference. This method is more efficient then creating an array. DO NOT MODIFY THE RETURNED ARRAY.

  field_count()
    my $number_of_field = $schema->field_count;
This method return the number of fields in the schema.

  timestamp_field()
    my $time_field = $schema->timestamp_field;
This method will return the Lire::Field(3pm) object representing the timestamp field in the schema. The timestamp field is the one that defines the sort order of the DLF records.

  is_schema_compatible()
    if ( $schema->is_schema_compatible( $other_schema ) ) {
    }
This method takes a Lire::DlfSchema(3pm) as parameter and returns a boolean value. That value will be true if the schema passed as parameter is compatible with the other, it will be false otherwise.

For a superservice's schema, the only compatible schema is an object representing the same superservice's schema.

  make_hashref2asciidlf_func()
See the SYNOPSIS section for an example.

This method is part of the DLF converter API.

It takes as parameters a list of field's names that are available in the DLF output by the converter. (Not all services in a given superservice will support the whole or the same subset of the superservice's fields. Unsupported fields should contain the value "LIRE_NOTAVAIL" in the output DLF.)

This method will return an anonymous subroutine that should be used by the DLF converter to create the DLF records. The generated subroutine takes as parameter an hash reference representing the DLF record to create. It returns an array reference representing the DLF record's fields. It will make sure that the field's values are in the correct order, that the unavailable fields are marked correctly, that missing fields are defaulted and that the field's values are escaped appropriately.

The hash's keys should be the DLF record's field names with the value of the field associated to the key. All the fields that are available (as specified when the method is called) which are undefined or that aren't present in the hash will be set in the output DLF record to the field's default value specified in the schema. Extra keys in the hash will be ignored. Fields that aren't supported (as specified when the subroutine was created by the make_hashref2asciidlf_func() method) will contains the "LIRE_NOTAVAIL" value.

You can write an ASCII DLF by printing the returned array reference using a space as the join delimiter:

    my $dlf = $dlf_maker->( $hash_dlf );
    print join( " ", @$dlf ), "\n";

SEE ALSO
Lire::Program(3pm), Lire::Field(3pm)

VERSION
$Id: DlfSchema.pm,v 1.24 2002/07/12 22:51:30 flacoste Exp $

COPYRIGHT
Copyright (C) 2001 Stichting LogReport Foundation LogReport@LogReport.org

This file is part of Lire.

Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html or write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.

AUTHOR
Francis J. Lacoste <flacoste@logreport.org>