Search
Categories
Documents
NexTrieve - Perl interface to NexTrieve search engine software (Displayed)
README
|
NexTrieve - Perl interface to NexTrieve search engine software
NexTrieve - Perl interface to NexTrieve search engine software
use NexTrieve;
$ntv = new NexTrieve( | {method => value} );
# doing everything in Perl
$search = $ntv->Search( host:port | port | resourcefile | $resource );
$hitlist = $search->Hitlist( $query | queryfile | xml | {method => value} );
foreach $hit ($hitlist->Hits) {
# display result here
}
# if you want to process your own XML
$hitlistxml = $ntv->ask_server_port( server:port | port,$queryxml );
*****************************************************************************
* Please note that NexTrieve is no longer being supported. This is most *
* likely the last update to NexTrieve.pm to allow usage with Perl 5.8.1. *
*****************************************************************************
Provide a Perl interface to the complete functionality of the NexTrieve search
engine sofware as found on http://www.nextrieve.com .
See the NexTrieve::Overview documentation for a introduction of the NexTrieve
search engine software and an overview of how the Perl modules interact
with that software. Although that documentation is not required reading
before looking at any of the other documentation, it is highly recommended
that you do.
The following modules are part of the distribution:
NexTrieve base module
NexTrieve::Collection logical collection object
NexTrieve::Collection::Index logical index object within a collection
NexTrieve::Daemon logical daemon object
NexTrieve::DBI convert DBI statement to document sequence
NexTrieve::Docseq logical document sequence for indexing
NexTrieve::Document logical document object
NexTrieve::Hitlist result of query from search engine
NexTrieve::Hitlist::Hit a single hit of the result
NexTrieve::HTML convert HTML-file(s) to logical document(s)
NexTrieve::Index create an index out of a docseq
NexTrieve::Mbox convert Unix mailbox to document sequence
NexTrieve::Message convert Mail::Message object(s) to document(s)
NexTrieve::MIME MIME-type conversions for documents
NexTrieve::Overview an overview of NexTrieve and its Perl support
NexTrieve::PDF convert PDF-files(s) to logical document(s)
NexTrieve::Query create/adapt query
NexTrieve::Querylog turn query log into Query objects
NexTrieve::Replay turn Querylog into Hitlist for a Search
NexTrieve::Resource create/adapt resource-file
NexTrieve::RFC822 convert message(s) to logical document(s)
NexTrieve::Search logical search engine object
NexTrieve::Targz maintain a Targz message archive
NexTrieve::UTF8 change encoding to UTF-8
The following scripts are part of the distribution:
docseq create a document sequence out of ready-made XML-files
dbi2ntvml convert SQL statement to a document sequence using DBI
html2ntvml convert one or more HTML-files to a document sequence
mailbox2ntvml convert one or more Unix mailboxes to a document sequence
pdf2ntvml convert one or more PDF-files to a document sequence
targz_collect collect new messages into Targz archive(s)
targz_count count number of messages in Targz archive(s)
Not all of the NexTrieve submodules may be needed in a particular situation.
In order to save CPU and memory, you can easily load only the necessary
submodules, by specifying their names in the -use- statement with which
you load this module. E.g.,
use NexTrieve; or use NexTrieve qw(:all);
will load all submodules of NexTrieve (which may become more over the course
of time). If you would only like to use the NexTrieve::Query and the
NexTrieve::Hitlist submodules, you can specify this as:
use NexTrieve qw(Query Hitlist);
This can e.g. be handy if you only want to use the Query and Hitlist features.
The following methods are available for setting up the NexTrieve object itself.
$ntv = NexTrieve->new( {method => value} );
The creation of the NexTrieve object itself is done by calling the class method
``new'' on the NexTrieve package. The ``new'' class method accepts one input
parameter: a reference to a hash or list of method-value pairs as handled by
the Set method.
The following methods are available for those cases where you want to access
the results a NexTrieve query from a running NexTrieve server directly.
$hitlistxml = $ntv->ask_server_port( server:port | port,$queryxml );
Perform a NexTrieve query on a NexTrieve Daemon running on the specified
server and port. Defaults to querying ``localhost'' if no server is specified.
The Query XML has to be in the format as described on:
http://www.nextrieve.com/usermanual/2.0.0/ntvqueryxml.stm . Returns XML in
the format as described on:
http://www.nextrieve.com/usermanual/2.0.0/ntvhitlistxml.stm .
$ntv->ask_server_port_fh( server:port | port,$queryxml,$handle );
Same function as the ask_server_port manpage, but instead of returning the Hitlist XML,
writes the Hitlist XML to the handle specified by the third input parameter.
$ntv->ask_server_port_file( server:port | port,$queryxml,$filename );
Same function as the ask_server_port manpage, but instead of returning the Hitlist XML,
writes the Hitlist XML to the file specified by the third input parameter.
The following methods are inherited from the NexTrieve object whenever any of
the sub-objects are made. This means that any setting in the NexTrieve object
of these methods, will automatically be activated in the sub-objects, that are
created after calling any of these methods, in the same manner.
$encoding = $ntvobject->DefaultInputEncoding;
$ntvobject->DefaultInputEncoding( $encoding );
Many sources of information that are converted to XML, more precisely to
NTVML, by this set of Perl modules, do not contain information about the type
of encoding the characters of that source are in. In a lot of cases,
especially email, a character encoding of ``us-ascii'' is indicated, even if
``extended ASCII characters'' are present. Conversion modules, such as the
NexTrieve::RFC822 and NexTrieve::HTML modules, need to make assumptions on
the character encoding if no encoding information is present.
By calling the ``DefaultInputEncoding'' method with a specific encoding name on
an object of the NexTrieve family of modules, you indicate the encoding that
should be assumed if no encoding information is present.
If you never call this method, a default input encoding of ``ISO-8859-1'' is
assumed. In practice, this is the set that consists of ``us-ascii'' and
``extended ASCII characters'', which is most commonly found in email and HTML.
$NexTrievePath = $ntv->NexTrievePath;
$ntv->NexTrievePath( '/usr/local/nextrieve/bin' ); # checks NTV_PATH=
Sometimes you want to try out something when the NexTrieve package itself is
not installed in the standard location. You can do this by specifying the
NTV_PATH= environment variable externally. Or you can do this by calling the
``NexTrievePath'' method and specifying the directory in which the NexTrieve
executables are located.
The default for the NexTrievePath is ``/usr/local/nextrieve/bin''. If that
doesn't exist, the highest numbered executable directory from
``/usr/local/nextrieve'' will be used, e.g. ``/usr/local/nextrieve/2.0.0''.
$NexTrieveVersion = $ntv->NexTrieveVersion;
$ntv->NexTrieveVersion( '2.0.0' ); # short for /usr/local/nextrieve/2.0.0
When several versions of the NexTrieve executables are installed on your
system, it can be handy to differentiate between them by just specifying the
version number. This is what the ``NexTrieveVersion'' method allows you to do:
if all versions of NexTrieve executables are installed from
``/usr/local/nextrieve'', then you can indicate which version you would like to
use by just specifying the version number, e.g. ``2.0.0''.
$PrintError = $ntvobject->PrintError;
$ntvobject->PrintError( true | false | 'cluck' );
Sometimes you want your program to let you immediately know when there is an
error. You can do this by calling the ``PrintError'' method with a
true value. Each time an error occurs, a warning will be printed to STDERR
informing you of the error that occurred. Check out the RaiseError method
for letting your program stop with execution immediately when an error has
occurred. Check out the Errors method when you want to examine errors
completely under program control.
As a special debugging feature, it is also possible to specify the keyword
'cluck'. If specified, it attempts to load the standard Perl module ``Carp''.
If that is successful, then it sets the $SIG{__WARN__} handler to call the
``Carp::cluck'' subroutine. This causes a stack-trace to be shown to the
developer when a warning occurs, either from an internal error or because
anything else executes a -warn- statement.
$RaiseError = $ntvobject->RaiseError;
$ntvobject->RaiseError( true | false | 'confess' );
Sometimes you want to have a program stop as soon as something goes wrong.
By calling the ``RaiseError'' method with a true value, you are telling the
module to immediately stop the program with an error message as soon as
anything goes wrong. Check out PrintError to have each error
output a warning on STDERR instead. Check out Errors if you want to
examine for errors completely under your control.
As a special debugging feature, it is also possible to specify the keyword
'confess'. If specified, it attempts to load the standard Perl module ``Carp''.
If that is successful, then it sets the $SIG{__DIE__} handler to call the
``Carp::confess'' subroutine. This causes a stack-trace to be shown to the
developer when an error occurs, either from an internal error or because
anything else executes a -die- statement.
$Tmp = $ntv->Tmp;
$ntv->Tmp( '/tmp' ); # checks TMP=
Sometimes the NexTrieve family of modules need to create an external file for
its operation. By default it checks the value of the TMP= environment
variable. If that environment variable doesn't exist, the ``/tmp'' directory
is assumed. Or you can call the ``Tmp'' method to indicate which directory
should be used to create temporary files.
The modules of the NexTrieve family do not contain ``new'' methods that can
be called directly. Instead, if you want to create e.g. an NexTrieve::HTML
object, you call the (instance) method ``HTML'' on an instantiated NexTrieve
object, e.g. ``$html = $ntv->HTML;''.
Here only the parameters for the object creation are documented. Any
additional methods are documented in the documentation of the module itself.
$collection = $ntv->Collection( path, | create );
Create a ``NexTrieve::Collection'' object for a collection such as defined by
the NexTrieve executables. The first input parameter specifies the path to
the directory of the collection. The second input parameter specifies a
flag indicating whether the path should be created if it doesn't exist
already.
$daemon = $ntv->Daemon( file | xml | $resource, | server:port | port, | {method => value} );
Create a ``NexTrieve::Daemon'' object for performing NexTrieve queries with
NexTrieve running as a server.
The first input parameter specifies the resources that should be used by this
daemon process: it can either be the name of a file containing the resource XML
specication, or the resource XML specification as a value, or an instantiated
NexTrieve::Resource object.
The second (optional) input parameter specifies the host and port on which this
daemon process should run. It can be either specified as a ``server:port''
combination, or just a port number. In the latter case, the ``localhost'' will
be assumed to be the server specification.
The third (optional) input parameter can be a reference to a hash or
list of method-value pairs as handled by the Set method.
$converter = $ntv->DBI( {method => value} );
Create a ``NexTrieve::DBI'' object for performing a conversion from DBI statement
handles to NexTrieve::Document objects as part of a document sequence as
described in ``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
This object is extensively used by the ``dbi2ntvml'' script. It is also
capable of creating Docseq and Resource objects.
$docseq = $ntv->Docseq( {method => value} );
Create a ``NexTrieve::Docseq'' object for creating a document sequence as
described in ``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
Please note that the DBI, HTML, Mbox, Message, PDF and
RFC822 objects are also capable of creating NexTrieve::Docseq objects.
$document = $ntv->Document( {method => value} );
Create a ``NexTrieve::Document'' object for creating a document as part of
document sequence as described in
``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
$hitlist = $ntv->Hitlist( | file | xml );
Create a ``NexTrieve::Hitlist'' object.
The (optional) input parameter either specifies the name of a file containing
XML conforming to the format described on
``http://www.nextrieve.com/usermanual/2.0.0/ntvhitlistxml.stm'', or XML in that
format as a value.
Please note that creating a Hitlist object in this manner is of little use:
a Hitlist object is usually created through the ``Hitlist'' method of the
NexTrieve::Search object.
$converter = $ntv->HTML( {method => value} );
Create a ``NexTrieve::HTML'' object for performing a conversion from HTML-files
to NexTrieve::Document objects as part of a document sequence as described in
``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
This object is extensively used by the ``html2ntvml'' script. It is also
capable of creating Docseq and Resource objects.
$index = $ntv->Index( file | xml | $resource, | {method => value}, | @files );
Create a ``NexTrieve::Index'' object for performing the NexTrieve indexing
process as described on
``http://www.nextrieve.com/usermanual/2.0.0/ntvindex.stm''.
The first input parameter specifies the resources that should be used in the
indexing process: it can either be the name of a file containing the resource
XML specication, or the resource XML specification as a value, or an
instantiated NexTrieve::Resource object.
The second (optional) input parameter can be a reference to a hash or
list of method-value pairs as handled by the Set method.
The other input parameters (if any) are interpreted as names of files that
contain pre-generated document sequences, as created by the NexTrieve::Docseq
object, that should be indexed immediately.
It is also capable of creating a basic Resource object from the information
stored in a NexTrieve index.
$converter = $ntv->Mbox( {method => value} );
Create a ``NexTrieve::Mbox'' object for performing a conversion from messages
as defined by RFC822, stored in a Unix mailbox, to NexTrieve::Document
objects as part of a document sequence as described in
``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method on the RFC822 object.
This object is extensively used by the ``mailbox2ntvml'' script. It is also
capable of creating Docseq objects.
$converter = $ntv->Message( {method => value} );
Create a ``NexTrieve::Message'' object for performing a conversion from
Mail::Message objects to NexTrieve::Document objects as part of a document
sequence as described in
``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
This object is usually used in conjunction with the Mail::Box object, which
is part of the Mail::Box package as available on CPAN. It is also capable of
creating Docseq and Resource objects.
$converter = $ntv->PDF( {method => value} );
Create a ``NexTrieve::PDF'' object for performing a conversion from PDF-files
to NexTrieve::Document objects as part of a document sequence as described in
``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
This object is extensively used by the ``pdf2ntvml'' script. It is also
capable of creating Docseq and Resource objects.
$query = $ntv->Query( | file | xml , | {method => value} );
Create a ``NexTrieve::Query'' object for performing the NexTrieve queries as
as described on ``http://www.nextrieve.com/usermanual/2.0.0/ntvqueryxml.stm''.
The first (optional) input parameter specifies the XML that should be used in
the creation of the object: it can either be the name of a file containing the
query XML specication, or the query XML specification as a value.
The second (optional) input parameter can be a reference to a hash or
list of method-value pairs as handled by the Set method.
Please note that the Querylog object is also capable of creating
NexTrieve::Query objects.
$querylog = $ntv->Querylog( file );
Create a ``NexTrieve::Querylog'' object for inspecting the queries that have
been made to a NexTrieve server running as a Daemon.
The input parameter specifies the name of the query logfile to be used for the
creation of the ``NexTrie::Querylog'' object.
Please note that the Querylog object can create Query objects.
$replay = $ntv->Replay( {method => value} );
Create a ``NexTrieve::Replay'' object for performing a number or queries and
obtaining their results as a number of Hitlist objects.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
$resource = $ntv->Resource( | file | xml , | {method => value} );
Create a ``NexTrieve::Resource'' object for indicating the use of resources
as described on ``http://www.nextrieve.com/usermanual/2.0.0/ntvresourcefile.stm''.
The first (optional) input parameter specifies the XML that should be used in
the creation of the object: it can either be the name of a file containing the
resource XML specication, or the resource XML specification as a value.
The second (optional) input parameter can be a reference to a hash or
list of method-value pairs as handled by the Set method.
Please note that the DBI, HTML, Mbox, Message, PDF and
RFC822 objects are also capable of creating NexTrieve::Resource objects.
$converter = $ntv->RFC822( {method => value} );
Create a ``NexTrieve::RFC822'' object for performing a conversion from messages
in the format as described by RFC 822 to NexTrieve::Document objects as
part of a document sequence as described in
``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
This object is extensively used by the Mbox object.
$search = $ntv->Search( | server:port | port | file | xml | $resource, | {method => value} );
Create a ``NexTrieve::Search'' object for performing queries on a NexTrieve
index. Searches can either be done using an on-demand approach, as described
on ``http://www.nextrieve.com/usermanual/2.0.0/ntvsearch.stm'', or by using a
server process as described on
``http://www.nextrieve.com/usermanual/2.0.0/ntvsearchd.stm''.
The first input parameter either specifies the server and port on which a
server process is running. Or it specifies the resources that should be used
in the on-demand searching process: then it can either be the name of a file
containing the resource XML specication, or the resource XML specification as
a value, or an instantiated NexTrieve::Resource object.
The second (optional) input parameter can be a reference to a hash or
list of method-value pairs as handled by the Set method.
Please note that search results are returned as a Hitlist object.
$targz = $ntv->Targz( {method => value} );
Create a ``NexTrieve::Targz'' object for archiving and performing conversions
on messages as defined by RFC822, either stored as seperate files or in
Unix mailboxes, to NexTrieve::Document objects as part of a document
sequence as described in
``http://www.nextrieve.com/usermanual/2.0.0/ntvindexerxml.stm''.
The (optional) input parameter can be a reference to a hash or list of
method-value pairs as handled by the Set method.
This object is extensively used by the ``targz_collect'' and ``targz_count''
scripts.
The following methods are inheritable from the NexTrieve module. They are
intended to make life easier for the developer, and are specifically intended
to be used within user scripts such as templates.
($encoding,$xml) = $ntvobject->Get( qw(encoding xml) );
$ntvobject->Get( qw(encoding xml) ); # sets global vars $encoding and $xml
Sometimes you want to obtain the values returned by many methods from the
same object. The ``Get'' method allows you to do just that: you specify the
names of the methods to be executed on the object and the values from the
method calls (without parameters) are either returned in the same order, or
they are used to set global variables with the same name as the method.
If you are interested in calling multiple methods with parameters on the same
object, and you are not interested in the return values, then you should
call the Set method.
$handle = $ntvobject->openfile( "filename","mode" );
$handle = $ntvobject->openfile( "command |" ); # pipe to output from command
return unless $handle;
The ``openfile'' method returns a handle for the file or pipe that can be used
to read from or print to. The parameters are the same as the standard Perl
function ``open()''. If an error occurs during opening of the file or pipe,
an error is added to the internal list of Errors and an empty value is
returned.
$ntvobject->Set( {
methodname1 => $value1,
methodname2 => $value2,
methodname2 => [parameter1,parameter2],
} );
It is often a hassle for the developer to call many methods to set parameters
on the same object. To reduce this hassle, the ``Set'' method was developed.
Instead of doing:
$nvobject->methodname1( $value1 );
$nvobject->methodname2( $value2 );
$nvobject->methodname2( $parameter1,$parameter2 );
you can do this in one go as specified above.
The ``Set'' method accepts either a reference to a hash (as specified by { })
or a reference to a list (as specified by [ ]). The reference to hash
method is preferable if the order in which the methods are executed, is not
important. If the order in which the methods are supposed to be excuted is
important, then you should use the reference to a list method, e.g.:
$ntvobject->Set( [
methodname1 => $value1,
methodname2 => [], # no parameters to be passed
methodname2 => [parameter1,parameter2], # more than 1 parameter
] );
Please note that if there is one parameter to the method, you can specify it
directly. If there are more than one parameter to be passed to the method,
then you must specify them as a reference to a list by putting them between
square brackets, i.e. ``['' and ``]''. If no parameters need to be passed to the
method, you can specify this as a reference to an empty list, i.e. ``[]''.
The ``Set'' method disregards any values that were returned by the methods. If
you are interested in the values that are returned by multiple methods, you
can use the Get method.
Please note that the ``Set'' method is used internally in almost all object
creation methods to allow you to immediately specify the options to be activated
for that object.
$contents = $self->slurp( $handle, | true | false );
The ``slurp'' method reads all the data it can from the specified handle (the
first input parameter) and returns that data and closes the handle. If you do
not want the handle to be closed, specify a true value as the second input
parameter. See the the splat manpage method for writing out a complete file.
Silently does not perform any operation if no valid handle is specified: thus
the first input parameter can be a call to the the openfile manpage method without any
problems.
$self->splat( $handle, $contents, | true | false ) || die "did not splat\n";
The ``splat'' method writes the data, specified by the second input parameter,
to the handle, specified by the first input parameter, and closes the handle.
If you do not want the handle to be closed, specify a true value as the third
input parameter. See the the slurp manpage method for reading in a complete file.
Silently does not perform any operation if no valid handle is specified: thus
the first input parameter can be a call to the the openfile manpage method without any
problems.
Returns true upon success.
The following methods have to do with all of the objects that are directly
related to the XML representation used by NexTrieve.
$ntvobject->ampersandize( $value1,$value2...$valueN );
The ``ampersandize'' method processes all of its input parameters in place.
It converts the &, < and > characters to their XML entity version and removes
any characters that may be illegal in XML. The values are assumed to not
have any entities upon input. See the the normalize manpage method for a more elaborate
cleaning up that handles text that can already contain entities (such as HTML).
$encoding = $ntvobject->encoding;
$ntvobject->encoding( $encoding );
Each object in the NexTrieve family that can contain XML, also knows in which
encoding the XML is stored. What that encoding is, can be determined by calling
the ``encoding'' method. If you want the XML of an object to be a specific
(different) encoding, then you can call this method also.
If you want to change the encoding of any XML, check out the the recode manpage
method.
$filename = $ntvobject->filename;
$ntvobject->filename( filename );
Many modules in the NexTrieve family are able to have their objects
initialized from XML stored in a file. This is usually specified at the
time of creation of the object. Or you want the XML of an object to be
stored in a specific file: this is usually specified by a call to the
the write_file manpage method.
Whenever an object is initialized from XML in a file, the name of the file
is remembered in the object so that it can be used as a default when calling
the the write_file manpage method. If you want that default to be different from the
original filename, or there was no filename to begin with, you can call the
``filename'' method to set the filename to be used later.
$md5 = $ntvobject->md5;
The ``md5'' method returns a so-called MD5 signature for the XML in the object.
For this to work, the Digest::MD5 module must be available also, otherwise
an empty string is always returned. See the documentation of the Digest::MD5
module for more information.
$ntvobject->nopi( true | false );
$nopi = $ntvobject->nopi;
XML is normally created with a so-called ``processor instruction'', indicating
the version of XML (so far always ``1.0'') and the encoding in which the XML was
created, e.g. '<?xml version=``1.0'' encoding=``utf-8''?>'. In some situations
you want the XML to be created without this processor instruction (e.g. when
it is to become part of a stream of XML: only one processor instruction at the
very beginning of an XML-stream is allowed). You can achieve this by calling
the ``nopi'' method with a true value before the XML is generated.
$ntvobject->normalize( $value1,$value2...$valueN );
The ``normalize'' method processes all of its input parameters in place.
It converts the &, < and > characters and any entities such as to theiri
correctly (numbered) XML entity version such as   and removes any
characters that may be illegal in XML. The values are assumed to may contain
named entities upon input. See the the ampersandize manpage method for a less elaborate
cleaning up that handles text that does not contain entities.
open( $handle,file );
$ntvobject->read_fh( $handle );
close( $handle );
Set the XML of a NexTrieve object from XML read from an opened handle.
$ntvobject->read_file( | file );
Set the XML of a NexTrieve object from XML stored in a file. Assume the
filename as indicated by calling the the filename manpage method previously if no
filename was specified.
$ntvobject->read_string( xml );
Set the XML of a NexTrieve object from XML stored as a value in memory.
$xml = $ntvobject->recode( $object | to_encoding, | xml, | from_encoding );
Obtain a version of XML that is encoded in a different encoding. The first
input parameter is the encoding ``to'' which should be encoded. This can also
be an object of the NexTrieve family of modules: then the encoding of that
object will be used as the encoding to encode to.
The second input parameter is the XML to be converted: if it is omitted, the
XML of the object itself is assumed.
The third input parameter must be specified if the second input parameter
is specified: it indicates the encoding in which the XML currently is encoded.
If it is not specified, the encoding of the object itself will be assumed.
To just change the encoding of the XML of an object, check out the the encoding manpage
method.
$version = $ntvobject->version;
In order to facilitate (conversions to) expansions of the current XML format
of NTVML, a version number is internally used. There is currently only one
version of NTVML, namely ``1.0''. So that string is always returned by the
``version'' method so far.
open( $handle,">file" );
$ntvobject->write_fh( $handle );
close( $handle );
Write the XML of a NexTrieve object to an opened handle.
$xml = $ntvobject->write_string;
Return the XML of a NexTrieve object. See the the xml manpage method for a more
intuitive way of doing this.
$ntvobject->write_file( | file );
Write the XML of a NexTrieve object to a file. Assume the filename as
indicated by calling the the filename manpage method previously if no filename was
specified and the XML of the object was not previously obtained by a call to
the the read_file manpage method.
$xml = $ntvobject->xml;
$ntvobject->xml( $xml );
$ntvobject->xml; # output XML to STDERR as warning
The ``xml'' method is actually a wrapper around the the read_string manpage and
the write_string manpage methods. It allows easy setting and obtaining the XML of a
NexTrieve object.
In order to facilitate debugging your programs, a special feature has been
added to the ``xml'' method. If the ``xml'' method is called in a void context
without specifying any new XML, the XML of the object is output as a warning
to STDERR.
@info = $ntvobject->Dump;
$ntvobject->Dump; # Data::Dumper->Dump output on object as warning
The ``Dump'' method is a quick-and-dirty interface to the Data::Dumper standard
Perl module. When it is invoked, it will attempt to load the Data::Dumper
module. If that is successful, it will create a dump of the object. If the
method is called in a void context, the dump will be printed as a warning to
STDERR. Else it will be returned by the ``Dump'' method.
No action will be performed if the Data::Dumper module can not be loaded.
if ($ntvobject->Errors) { # does not remove errors in scalar context
@error = $ntvobject->Errors; # returns errors, removes them from object
If an error occurs in the NexTrieve family of modules, they are only reported
``internally'' as information added to the object. To find out whether there are
any errors, you can call the ``Errors'' method in scalar context: it will then
tell you how many errors there are. To find out what the errors exactly are,
you can call the ``Errors'' method in list context: this then also has the
side-effect of removing the error information from the object, effectively
resetting the error history of the object.
If you want your program to stop as soon as an error occurs, call the
RaiseError method beforehand. If you want your program to also output a
warning to STDERR each time an error occurs, call the PrintError
method beforehand.
$ntvobject->xmllint( true | false );
$xmllint = $ntvobject->xmllint;
The ``xmllint'' method is for the really paranoid of mind and for those who are
debugging their programs or additional modules to the NexTrieve family. When
called with a true value, it will check for the availability of the ``xmllint''
program of the ``libxml2'' package (as found on ``http://www.xmlsoft.org''). If
it is found, it will set the ``xmllint'' flag in the object to ``1''. Then,
anytime XML is generated by the object, the ``xmllint'' program will be called
to check the validity of the generated XML. An error will be added to the
object (accessible to the Errors method) with the output of the xmllint
program if any errors were found.
If the ``xmllint'' program is not found, then the flag in the object will remain
false and no additional checks will be performed when XML is generated.
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
NexTrieve is no longer being supported.
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.
The other NexTrieve::xxx modules.
Information
|
This site is currently in testing, it is not yet operating using the full database. Until it is officially launched you may wish to visit Help-Site Computer Manuals. After launch, this site (HelpSpy) will replace Help-Site. Information about the spider which is currently trawling the Internet looking for links to add to this directory can be found here. |
| 
