NAME

NexTrieve::Docseq - handling a NexTrieve Document Sequence

SYNOPSIS

 use NexTrieve;
 $ntv = NexTrieve->new( | {method => value} );
 $docseq = $ntv->Docseq( | file | xml | {method => value} );

 # non-streaming mode, XML built in memory
 $docseq->add( data );
 $docseq->add( moredata );
 $docseq->add( stillmoredata );
 $docseq->write_file( filename );

 #streaming-mode, XML sent to stream immediately
 $docseq->stream( handle | filename );
 $docseq->add( data );
 $docseq->add( moredata );
 $docseq->add( stillmoredata );
 $docseq->done; # or let $docseq go out of scope

DESCRIPTION

The Docseq object of the Perl support for NexTrieve. Do not create directly, but through the Docseq method of the NexTrieve object.

METHODS

The following methods are available to the NexTrieve::Docseq object.

add

 $docseq->add( $data | \$data | [$data] | {container => $data} | $document );

The "add" method allows you to add data to a document sequence. Each input parameter can be one of the following:

- scalar value containing XML in UTF-8

 $docseq->add( "<document><attributes><id>1</id></attributes></document>" );

- reference to a scalar value containing XML in UTF-8

 $docseq->add( \"<document><attributes><id>1</id></attributes></document>" );

- reference to a list of values containing XML in UTF-8

 $docseq->add( ["<document><attributes><id>1</id></attributes></document>"] );

- NexTrieve::Document object

 my $document = $ntv->Document( {attribute => [qw(id 1)]} );
 $docseq->add( $document ); # calls "xml" method on object

- reference to hash, containing any of above, key = name of container, value = string encoded in UTF-8

 $docseq->add( {document => {attributes => {id => 1}}} );

All of the above are equivalent ways of doing the same thing.

All forms of expressions can be mixed: everything will be expanded until it is a scalar value which can be added to the XML of the document sequence.

Please note that you usually do not call the "add" method directly, but that this rather happens by customized versions of the "Docseq" method in various other modules.

bare

 $ntvobject->bare( true | false );
 $bare = $ntvobject->bare;

The XML generated by the NexTrieve family, consists of an outer container indicating the version of NTVML the XML conforms to. In some cases (e.g. when creating document sequences to be merged together later) it may be desirable to have the outer container to be absent, i.e. to have the XML be created "bare". You can achieve this by calling the "bare" method with a true value before the XML is generated.

done

 $docseq->done; # not really needed, DESTROY on object does same

The "done" method is only needed when the NexTrieve::Docseq is in streaming mode. It stops the streaming by closing the <ntv:docseq> container and closing the handle that was used for writing to the stream.

Calling the "done" method is not strictly necessary. As soon as the object goes out of scope, a call to "done" is done autmatically.

files

 $docseq->files( <files.xml> );
 $docseq->files( \&processor,<files.anydata> );

The "files" method allows you to add one or more external files containing data to be added to a document sequence. These could be pre-made XML files, or files containing any other type of data that need to be processed first before being added to the document sequence.

The first (optional) input parameter specifies a reference to a processor routine that will take the contents of the file as its input parameter. It should return zero or more XML-containers, one for each document to be added to the document sequence.

The other input parameters specify the names of the files that should be read and passed into the document sequence.

The Docseq object itself is returned by this method, which makes it handy for one-liners.

stream

 open( $handle,">filename" );
 $docseq->stream( $handle );

 $docseq->stream( filename1,filename2 );

The "stream" method can be called to cause the document sequence to be streamed to a file or an external process (such as the NexTrieve indexer).

Each input parameter can either be a filename or an already opened handle. If it is a filename, the file is opened for writing as a new file, losing any contents that were stored there previously.

Please note that NexTrieve::Index module allows you to create a NexTrieve::Docseq object that automatically streams to the NexTrieve indexer. See the NexTrieve::Index module for more information.

xml

 $docseq->xml( $xml );
 $xml = $docseq->xml;

The "xml" method can only be used if the NexTrieve::Docseq object is not in streaming mode. You can either use it to set the complete XML of the document sequence or have it returned to you. Only the latter seems to be a sensible thing to do.

AUTHOR

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Please report bugs to <perlbugs@dijkmat.nl>.

SUPPORT

NexTrieve is no longer being supported.

COPYRIGHT

Copyright (c) 1995-2003 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

The NexTrieve.pm and the other NexTrieve::xxx modules.

cpanm NexTrieve

perl -MCPAN -e shell
install NexTrieve