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:

Id utilities

Word counting

Miscellaneous 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 the DOMNode 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 the DOMDocumentType 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 Perl time 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 the generate_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.

cpanm XML::XMetaL

perl -MCPAN -e shell
install XML::XMetaL