Treex::PML::Document - Treex::PML class representing a document consisting of a set of trees.
This class implements a document consisting of a set of trees. The document may be associated with a FS format and a PML schema and can contain additional meta data, application data, and user data (implemented as name/value paris).
For backward compatibility, a the document may also contain data related with the FS format, e.g. a patterns and tail.
NOTE: Don't call this method as a constructor directly, use Treex::PML::Factory->createDocumentFromFile() instead!
Load a Treex::PML::Document object from a given file. If called as a class
method, a new instance is created, otherwise the current instance is
reinitialized and reused. The method returns the instance or dies
(using Carp::croak) if loading fails (unless option recover
is set,
see below).
Loading options can be passed as a HASH reference in the second argument. The following keys are supported:
An ARRAY reference of IO backend names (previously imported using
ImportBackends
). These backends are tried additionally to
Treex::PML::Backend::FS. If not given, the backends previously selected using
UseBackends
or AddBackends
are used instead.
A name of character set (encoding) to be used by text-based I/O backends such as Treex::PML::Backend::FS.
If true, the method returns normally in case of loading failure, but
sets the global variable $Treex::PML::FSError
to the value return value
of readFile
, indicating the error.
Creates and returns a new FS file object based on the given values
(optional). For use with arguments, it is more convenient to use the
method create()
instead.
NOTE: Don't call this constructor directly, use Treex::PML::Factory->createDocument() instead!
or
NOTE: Don't call this constructor directly, use Treex::PML::Factory->createDocument() instead!
Creates and returns a new empty Treex::PML::Document object based on the given parameters. This method accepts argument => value pairs as arguments. The following arguments are available:
name, format, FS, hint, patterns, tail, trees, save_status, backend
See initialize
for more details.
Create a new Treex::PML::Document object with the same file name, file format, FSFormat, backend, encoding, patterns, hint and tail as the current Treex::PML::Document. If $clone_trees is true, populate the new Treex::PML::Document object with clones of all trees from the current Treex::PML::Document.
Initialize a FS file object. Argument description:
File name
File format identifier (user-defined string). TrEd, for example, uses
FS format
, gzipped FS format
and any non-specific format
strings as identifiers.
FSFormat object associated with the file
hint pattern definition (used by TrEd)
embedded stylesheet patterns (used by TrEd)
The rest of the file, which is not parsed by Treex::PML, i.e. Graph's embedded macros
List of FSNode objects representing root nodes of all trees in the Treex::PML::Document.
File save status indicator, 0=file is saved, 1=file is not saved (TrEd uses this field).
IO Backend used to open/save the file.
IO character encoding for perl 5.8 I/O filters
Reserved for the user. Content of this slot is not persistent.
Meta data (usually used by IO Backends to store additional information about the file - i.e. other than encoding, trees, patterns, etc).
Non-persistent application specific data associated with the file (by default this is an empty hash reference). Applications may store temporary data associated with the file into this hash.
NOTE: Don't call this constructor directly, use Treex::PML::Factory->createDocumentFromFile() instead!
Read a document from a given file. The first argument
must be a file-name. The second argument may be a list reference
consisting of names of I/O backends. If no backends are given, only
the Treex::PML::Backend::FS is used. For each I/O backend, readFile
tries to
execute the test
function from the appropriate class in the order
in which the backends were specified, passing it the filename as an
argument. The first I/O backend whose test()
function returns 1 is
then used to read the file.
Note: this function sets noSaved to zero.
Return values: 0 - succes 1 - no suitable backend -1 - backend failed
Save Treex::PML::Document object to a given file using the corresponding I/O backend (see $fsfile->changeBackend) and set noSaved to zero.
This is just an alias for $fsfile->save($filename).
Write FS declaration, trees and unparsed tail to a given file (file handle open for reading must be passed as a GLOB reference). Sets noSaved to zero.
Return the FS file's file name. If the actual file name is a file:// URL, convert it to system path and return it. If it is a different type of URL, return the corresponding URI object.
Return the FS file's URL as URI object.
Change the FS file's file name.
Like changeFilename, but does not attempt to absoultize the filename. The argument must be an absolute URL (preferably URI object).
Return file format identifier (user-defined string). TrEd, for
example, uses FS format
, gzipped FS format
and any
non-specific format
strings as identifiers.
Change file format identifier.
Return IO backend module name. The default backend is Treex::PML::Backend::FS, used to save files in the FS format.
Change file backend.
Return file character encoding (used by Perl 5.8 input/output filters).
Change file character encoding (used by Perl 5.8 input/output filters).
Return user data associated with the file (by default this is an empty hash reference). User data are not supposed to be persistent and IO backends should ignore it.
Change user data associated with the file. User data are not supposed to be persistent and IO backends should ignore it.
Return meta data stored into the object usually by IO backends. Meta data are supposed to be persistent, i.e. they are saved together with the file (at least by some IO backends).
Change meta information (usually used by IO backends). Meta data are supposed to be persistent, i.e. they are saved together with the file (at least by some IO backends).
In array context, return the list of metaData keys. In scalar context return the hash reference where metaData are stored.
Return application specific information associated with the file. Application data are not persistent, i.e. they are not saved together with the file by IO backends.
Change application specific information associated with the file. Application data are not persistent, i.e. they are not saved together with the file by IO backends.
In array context, return the list of appData keys. In scalar context return the hash reference where appData are stored.
Return a reference to the associated FSFormat object.
Associate FS file with a new FSFormat object.
Return the Tred's hint pattern declared in the Treex::PML::Document.
Change the Tred's hint pattern associated with this Treex::PML::Document.
Return the number of display attribute patterns associated with this Treex::PML::Document.
Return n'th the display pattern associated with this Treex::PML::Document.
Return a list of display attribute patterns associated with this Treex::PML::Document.
Change the list of display attribute patterns associated with this Treex::PML::Document.
Return the unparsed tail of the FS file (i.e. Graph's embedded macros).
Modify the unparsed tail of the FS file (i.e. Graph's embedded macros).
Return a list of all trees (i.e. their roots represented by FSNode objects).
Assign a new list of trees.
Return a reference to the internal array of all trees (e.g. their roots represented by FSNode objects).
Return a reference to the tree number n.
Return number of associated trees minus one.
Return/assign file saving status (this is completely user-driven).
Return/assign index of current tree (this is completely user-driven).
Return/assign current node (this is completely user-driven).
Get list of nodes for given tree. Returns two value list ($nodes,$current), where $nodes is a reference to a list of nodes for the tree and current is either root of the tree or the same node as prev_current if prev_current belongs to the tree. The list is sorted according to the ordering attribute (obtained from FS->order) and inclusion of hidden nodes (in the sense of FSFormat's hiding attribute FS->hide) depends on the boolean value of include_hidden.
Return a sentence string for the given tree. Sentence string is a string of chained value attributes (FS->value) ordered according to the FS->sentord or FS->order if FS->sentord attribute is not defined.
Unless no_tree_numbers is non-zero, prepend the resulting string with a "tree number/tree count: " prefix.
Return a list of value (FS->value) attributes for the given tree ordered according to the FS->sentord or FS->order if FS->sentord attribute is not defined.
Insert new tree at given position.
Set tree at given position.
Append tree at given position.
Create a new tree at given position and return pointer to its root.
Delete the tree at given position and return pointer to its root.
Delete the tree on a given position and destroy its content (the root and all its descendant nodes).
Swap the trees on given positions in the tree list. The positions must be between 0 and lastTreeNo inclusive.
Move the tree on position1 in the tree list so that its position after the move is position2. The positions must be between 0 and lastTreeNo inclusive.
This method can be used before a insert_tree
or a similar operation
to test if the root node provided as an argument is of a type valid
for this Treex::PML::Document. More specifically, return 1 if the current file is
not associated with a PML schema or if the tree list represented by
PML list or sequence with the role #TREES permits members of the type
of root
. Otherwise return 0.
A type-declaration object can be passed directly instead of
root_type
.
If the node passed already has a PML type, the type is returned.
Otherwise this method tries to determine and set the PML type of the current node based on the type of its parent and possibly the node's '#name' attribute.
If the node type cannot be determined, the method dies.
If more than one type is possible for the node, the method first tries to run a callback routine passed in the choose_command option (if available) passing it three arguments: the $fsfile, $node and an ARRAY reference of possible types. If the callback returns back one of the types, it is assigned to the node. Otherwise no type is assigned and the method returns a list of possible node types.
Copyright (C) 2006-2010 by Petr Pajas
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.