NAME
XML::XMetaL::Utilities - Utility functions
SYNOPSIS
# Use the module
use XML::XMetaL::Utilities;
# Use the module and import constants
use XML::XMetaL::Utilities qw(:dom_node_types :attribute_types);
# Use the module and import all constants
use XML::XMetaL::Utilities qw(:all);
# The constructor
my $utilities = XML::XMetaL::Utilities->new(-application => $xmetal);
# Utility Methods
my $id_attribute_name = $utilities->get_id_attribute_name('Para');
my $id = $utilities->generate_id();
$utilities->populate_element_with_id($element_node);
$utilities->populate_id_attributes('Article');
my $inserted_node = $utilities->insert_element_with_id('VariableList');
my $word_count = $utilities->word_count($string);
my $word_count = $utilities->word_count($element_node);
# Miscellaneous Methods
my $xmetal_application = $utilities->get_application();
my $active_document = $utilities->get_active_document();
my $selection = $utilities->get_selection();
DESCRIPTION
The XML::XMetaL::Utilities
class contains utility methods:
EXPORT
On request, the XML::XMetaL::Utilities
package can export a number of constants used by XMetaL. The following export tags are available:
:dom_node_types
-
The
:dom_node_types
tag exports constants representing the DOM node types used by XMetaL. The following constants are exported:DOMELEMENT DOMATTR DOMTEXT DOMCDATASECTION DOMENTITYREFERENCE DOMENTITY DOMPROCESSINGINSTRUCTION DOMCOMMENT DOMDOCUMENT DOMDOCUMENTTYPE DOMDOCUMENTFRAGMENT DOMNOTATION DOMCHARACTERREFERENCE
The integer values represented by these constants are the same as those returned by the
nodeType
property of theDOMNode
class in the XMetaL API. :attribute_types
-
The
:attribute_types
tag exports constants representing attribute node types used by XMetaL. The following constants are exported:UNKNOWN CDATA ID IDREF IDREFS ENTITY ENTITIES NMTOKEN NMTOKENS NOTATION NAMETOKENGROUP
The integer values represented by these constants are the same as those returned by the
attributeType
property of theDOMDocumentType
class in the XMetaL API. :all
-
The
:all
tag exports all of the constants listed above.
Constructor and initialization
use XML::XMetaL::Utilities qw(:all);
my $utilities = XML::XMetaL::Utilities->new(-application => $xmetal_application);
The use
statement takes optional export tags as arguments as described in the EXPORT section.
The constructor requires one named parameter: an XMetaL application object.
Class Methods
None.
Public Methods
get_id_attribute_name
-
my $id_attribute_name = $utilities->get_id_attribute_name('Para');
The
get_id_attribute_name
method takes the name of an element (a generic identifier) as an argument, and returns the name of the ID type attribute of that element, if there is an ID type attribute declared.If there is no ID attribute declared for the element,
undef
will be returned. generate_id
-
my $id = $utilities->generate_id();
The
generate_id
method generates an id value of the following format:<user_name><time_stamp><count>
user_name
-
The
user_name
is the user name of the XMetaL user time_stamp
-
The
time_stamp
is obtained using the Perltime
function when the utilities object is created. Thus, in most cases, the time stamp will remain constant for an entire XMetaL session. count
-
The
count
is incremented by one each time thegenerate_id
method is called.
The id generated by
generate_id
will always be unique within the scope of a particular XMetaL session.It is conceivable that two users on different networks, with the same user name, could start XMetaL at the exact same second, and thus generate identical ids. However, this risk is so small as to be deemed negligible.
populate_element_with_id
-
$utilities->populate_element_with_id($element_node);
The
populate_element_with_id
method takes an element node as an argument and adds an ID attribute with an id value to it.If the element does not have an ID attribute, or if the ID attribute already has a value, nothing happens. Existing id values are not changed.
populate_id_attributes
-
$utilities->populate_id_attributes('Article');
The
populate_id_attributes
method takes an element name as an argument and populates all element nodes with the same name with ID attributes.Existing ID attribute values are not changed.
insert_element_with_id
-
my $inserted_node = $utilities->insert_element_with_id('VariableList');
The
insert_element_with_id
method inserts an element, with a populated ID attribute, at the insertion point of the currently active document.If successful, the method returns the inserted element node.
If the element could not be inserted, the method returns
undef
. word_count
-
my $word_count = $utilities->word_count($string); my $word_count = $utilities->word_count($element_node);
The word count takes either a text string or an element node as an argument. It returns a word count.
If the argument is a string, markup in the string will be counted as words.
If the argument is an element node, only words in text nodes and CDATA sections will be counted.
get_application
-
my $xmetal_application = $utilities->get_application();
This accessor method returns the XMetaL application object.
get_active_document
-
my $active_document = $utilities->get_active_document();
This accessor method returns the currently active document.
get_selection
-
my $selection = $utilities->get_selection();
This accessor method returns a selection object representing the current selection in the active document.
ENVIRONMENT
The Corel XMetaL XML editor must be installed.
BUGS
The generate_id
method will generate illegal id values if the user name contains characters that are illegal in an id, or if the user name begins with a character that is not a letter.
This problem will be fixed in a future version.
There are almost certainly plenty of other bugs too.
Please send bug reports to <henrik.martensson@bostream.nu>.
SEE ALSO
See XML::XMetaL.
AUTHOR
Henrik Martensson, <henrik.martensson@bostream.nu>
COPYRIGHT AND LICENSE
Copyright 2003 by Henrik Martensson
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.