NAME
NexTrieve::Document - create XML for indexing a single document
SYNOPSIS
use NexTrieve;
$ntv = new NexTrieve( | {method => value} );
$index = $ntv->Index( | filename | xml | $resource );
$docseq = $index->Docseq( | encoding );
$document = $ntv->Document( | {method => value} );
$docseq->add( $document );DESCRIPTION
The Document object of the Perl support for NexTrieve. Do not create directly, but through the Document method of the NexTrieve object.
$document = $ntv->Document( | {method => value} );Please note that many of the other modules have NexTrieve::Document object creation routines of their own, usually called "Document". So only if you would like to get your hands dirty, creating NexTrieve::Document objects of your own design, is when you actually use methods of this module directly.
METHODS
The following methods apply to the adding of attributes and text.
attribute
$document->attribute( name,@value );The "attribute" method adds one or more attributes with the same name to the NexTrieve::Document object. When the XML of the document object is serialized, then each attribute container will be a descendant of the <attributes> container of the document XML.
The strings that are stored as the values of the attribute, should already be encoded in the same manner as the encoding of the document indicates.
The first input parameter specifies the name of the attribute.
The other input parameter specify values for which an attribute container with the given name should be added. Please note that if you specify more than one value, the attribute must be known in the NexTrieve resource-file with a multiplicity of "*".
For example:
$document->attribute( 'title','This is the title' );will cause the following XML to be generated (if it was the only call):
<attributes>
<title>This is the title</title>
</attributes>Another example:
$document->attribute( 'category',1,2,3,4 );will cause the following XML to be generated (if it was the only call):
<attributes>
<category>1</category>
<category>2</category>
<category>3</category>
<category>4</category>
</attributes>See the attributes method for specifying all attributes of a document at the same time.
attributes
$document->attributes( [name1,@value1], [name2,@value2] ... [nameN,@valueN] )The "attributes" method adds all attributes of a document at the same time. The input parameters each should be a reference to a list. Each of these lists have the same input parameter sequence as a single call to method attribute: the first element specifies the name of the attribute, the other elements specify values for which to create containers with the given name.
Please note that calling method "attributes" will throw away any other attributes that have been previously specified with either a call to method attribute or "attributes". So you typically only call method "attributes" only once during the lifetime of an object.
text
$document->text( text | name,@text );The "text" method allows you to either add a basic text (to be placed in the <text> container without container) or one or more named texttypes.
The strings that are stored as the values of the texttypes, should already be encoded in the same manner as the encoding of the document indicates.
If only one input parameter is specified, it is assumed to be a text that is to be added without container.
If more than one input parameter is specified, then the first input parameter is the name of the texttype to serialize the text in. In that case, all the other input parameters indicate the values to be serialized in those containers.
For example:
$document->text( 'This is the text' );will cause the following XML to be generated (if it was the only call):
<text>
This is the text
</attributes>Another example:
$document->text( 'p',qw(one two three four) );will cause the following XML to be generated (if it was the only call):
<text>
<p>one</p>
<p>two</p>
<p>three</p>
<p>four</p>
</text>See the texts method for specifying all text of a document at the same time.
texts
$document->texts( [text], [name1,@value1], ... [nameN,@valueN] );The "texts" method adds all text of a document at the same time. The input parameters each should be a reference to a list. Each of these lists have the same input parameter sequence as a single call to method text: if there is only one element, it is a text without container, else the first element specifies the name of the texttype, the other elements specify values for which to create containers with the given name.
Please note that calling method "texts" will throw away any other texts that have been previously specified with either a call to method text or "texts". So you typically only call method "texts" only once during the lifetime of an object.
xml
$xml = $document->xml;
$document->xml( $xml );The "xml" method can be called on the NexTrieve::Document object, but is different from all the other "xml" methods that can be called on other objects.
The XML returned by the NexTrieve::Document object never contains an XML processor instruction. This is because the Nextrieve::Document object is supposed to become part of a document sequence, in which the XML processor instruction would cause problems.
This also means that, although you can save the NexTrieve::Document object in a file, it is not wise to do so if the encoding of the object is different from "UTF-8" (the default encoding assumed if there is no XML processor instruction in an XML stream).
AUTHOR
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
COPYRIGHT
Copyright (c) 1995-2002 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
http://www.nextrieve.com, the NexTrieve.pm and the other NexTrieve::xxx modules.