Makestyle(3pm)

NAME
RefDB::Makestyle - methods used by refdb-ms (RefDB style generator)

SUMMARY
Makestyle.pm - a module used by refdb-ms (RefDB MakeStyle) -- a utility that generates RefDB bibliography styles.

Provides "Element" and "Attribute" classes for use in generating RefDB styles.

DEPENDENCIES
The following perl modules are required by this library:

•   Scalar::Util

    Provides a method of querying an object to determine its base class.

•   Term::Clui

    Provides user interface.

    For input it provides mechanisms for selection from menus, direct input and for yes/no question-answer prompts.

    For output it provides for console output or display in the default editor.

    This module, by default, records user choices in a hidden database. This behaviour is turned off.

    Term::Clui::edit uses a console editor for display. It uses the editor specified by the EDITOR variable. If this variable is not set it falls back to the 'vi' editor.

•   Text::Wrap

    Provides word-wrap for console display.

•   File::Temp

    Provides useful methods for filename generation.

    The OO methods are not used because, at the time of writing, the version shipped with some *nix-like OSes does not yet include the OO interface.

UNIVERSAL METHODS
These methods are supplied by a hidden base class.

•   get_classname

    Returns classname of object.

•   _is_valid_value

    Default method for determining validity of simple (scalar) user input. Checks that value is defined and not an empty string and not filled with whitespace.

    Is overridden by derived classes with more stringent input requirements.

•   _input_choice

    User selects from a menu.

    Returns user's selection.

    Parameters: (0 = class), 1 = prompt, 2... = options.

    Common usage:

            my $value = undef;
            while ( 1 ) {
                    $value = $self->_input_choice( "Select value:" , <@list> );
                    if ( $value ) { last; }
                    print "Invalid choice.  Sorry, please try again.\n";
            }

•   _input_ask

    User enters a value.

    Returns user's input.

    Parameters: (0 = class), 1 = prompt, 2 = default.

    Common usage:

            my $value = undef;
            while ( 1 ) {
                    $value = $self->_input_ask( "Enter value:" , <$default> );
                    if ( $self->_is_valid_value( $value ) ) { last; }
            }

•   _input_confirm

    User is asked a question to which s/he answers y/n.

    Returns boolean.

    Parameters: (0 = class), 1 = question.

    Note: If multi-line question, then after answer only the first line is left on screen. The first line should be a short question with subsequent lines holding further information.

    Common usage:

            if (_input_confirm( "Short question?\n\nMore\nmulti-line\ntext." ) ) {
                    # do stuff
            }

•   _display

    Displays screen text with word wrapping.

    Parameters: (0 = class), 1 = display string.

    Common usage:

            _display( <$scalar> );

•   _view

    Displays large volume of text in default editor and then returns viewer to original screen.

    Parameters: (0 = class), 1 = title , 2 = help text.

    Common usage:

            _view( <$title> , <$help_text> );

•   _entitize

    Takes string and replaces '&', '<' and '>' with xml entity equivalents.

ATTRIBUTE CLASSES
These classes model the XML attributes found in the Refdb "citestylex" DTD.

  Attributes: Public Interface
Attributes: Data Members

        %self = (

                name          =>  "ATTRIBUTE" ,

                enumeration   =>  [ "value_0" , "value_1" , ... ] ,

                default       =>  "value_x" ,

                prompt        =>  "This is the purpose and/or use of the attribute." ,

                value         =>  "User selected/entered value>" ,

                summary       =>  0 | 1 ,

        )

•   name

    Attribute name as per the Refdb "citestylex" DTD. Always uppercase.

•   enumeration

    List of possible values for attribute. If empty then attribute takes user-entered value, eg. DISPLAYAUTHOR, which takes a number.

•   default

    The default value. If "enumeration" is present, the default will always be one of the items in it. If no default then leave as "undef" -- this is the 'default' value after object construction.

•   prompt

    The text string that is used by client methods to prompt users when entering data.

•   summary

    Boolean determining whether attribute is included in summary form.

•   value

    The attribute value as selected or input by the user.

Attributes: Constructors

In following method signatures replace ATTRIBUTE with the relevant attribute class name.

Some attributes have a maximum number of instances that can exist within a given PubType (see method select_value below). When a class is asked to create an object in excess of the designed maximum for that class the constructor returns a scalar holding an error message. This enables a simple test (using "ref" function) to determine whether the constructor returned an object/blessed variable or scalar.

        my $at = ATTRIBUTE->new();

Attributes: Setters

        $at->set_name        ( "<name>"    );
        $at->set_default     ( "<default>" );
        $at->set_prompt      ( "<prompt>"  );
        $at->add_enumeration ( LIST        );
        $at->set_summary     ( 0 | 1       );

Attributes: Getters

        $at->get_name();
        $at->get_default();
        $at->get_prompt();
        $at->get_enumeration();  # returns list with default value first
        $at->get_enum_string();  # returns single text string
        $at->get_summary();
        $at->get_value();

Attributes: Other methods

•   $at->select_value();

    If enumeration exists then user selects from list. The default is always the first option in the list.

    If there is no enumeration the user enters the value directly. The default value is given and can be selected by simply pressing "Enter".

    Some attributes are set automatically depending on how many objects of this class have been created. In those classes this method has no effect. This applies to the Role_AuthorList, Role_PubDate, Role_Title, Role_UserDef, Role_Link and Role_Misc classes.

    The "citestylex" DTD design envisages a maximum number of objects of these classes being constructed -- the number varying between 3 and 5 depending on the class. See "Attributes: Constructors" for what happens when the class is asked to create an object in excess of the designed maximum.

•   $at->get_xml_fragment();

    Returns minimal xml fragment indicating the attribute name and value:

            ATTRIBUTE="VALUE"

  Attributes: List of Classes
To see a list of attribute classes use the "document-dtd-entities" utility that shipped with this program. It extracts attribute and element properties from this script, assembles and formats them into a single html document.

ELEMENT CLASSES
These classes model the XML elements found in the Refdb "citestylex" DTD.

  Elements: Public Interface
Elements: Data members

        %self = (

                name          =>  "ELEMENT" ,

                prompt        =>  "This is the purpose of this element." ,

                help          =>  "This is help on how to use this element." ,

                display       =>  undef | "name" | "content" ,

                summary       =>  undef | "name" | "left" | "right" | "content" ,

                attributes    =>  {

                        mandatory     =>  [ "Attribute_Class_0" , "Attribute_Class_1" , ... ] ,

                        optional      =>  [ "Attribute_Class_0" , "Attribute_Class_1" , ... ] ,

                        selected      =>  [ "Attribute_0" , "Attribute_1" , ... ] ,

                        man_complete  =>  undef | 1 ,

                        opt_complete  =>  undef | 1 ,

                } ,

                copyable      =>  1 | undef ,

                content       =>  {

                        allowed       =>  undef | 1 ,

                        suggestion    =>  "Possible value" ,

                        value         =>  "User input" ,

                        complete      =>  undef | 1 ,

                } ,

                model_order   =>  [

                        [ Element_Class_0 , "? | + | 1" ] ,

                        [ Element_Class_1 , "? | + | 1" ] ,

                        ... ,

                ] ,

                model_noorder =>  {

                        element_list =>  [ Element_Class_0 , Element_Class_1 , ... ] ,

                        separator    =>  "Separator" ,

                } ,

                children      =>  {

                        elements     =>  [ Element_0 , Element_1 , ... ] ,

                        complete     =>  boolean ,

        )

•   name

    Element name as given in the Refdb "citestylex" DTD. Unique.

•   prompt

    Brief statement of the element's purpose and/or function.

•   help

    More detailed instructions on how to use this element.

•   display

    Determines whether, and how, to display the element in brief form (used for the "progress report". If defined, the element is displayed. If set to "name" the element name is displayed. If set to "content" the element contents are displayed.

•   summary

    Determines whether, and how, to display the element in summary form. If defined, the element is displayed. If set to "name" the element name is displayed. If set to "content" the element contents are displayed.

•   attributes

    Attributes of this element. First two lists are of 'legal' attributes: mandatory and optional. Third list is of added attribute objects -- initially empty. Fourth and fifth hash values are flags indicating whether attributes have been added.

•   content

    Some elements hold #PCDATA content. The hash key "allowed" determines whether element accepts input -- false/undef means it does not, true means it does. The hash key "suggested" holds a suggested value the user may use. The hash key "value" holds the actual user input. The hash key "complete" is a flag indicating whether content has been entered.

•   copyable

    Some elements cannot be copied, either because they have mandatory attributes which require user input or because they only occur once per citstyle.

•   model_order

    With model_noorder this data member determines the content model for children elements. All of the 64 elements fall into one of three content models regarding children elements: 1. No children elements, 2. An ordered list and 3. An unordered list.

    This data member is "undef" in cases (1) and (3).

    It holds the content model for the thirty elements which have content model (2) -- an ordered list:

            ( e[?|+|1] , e[?|+|1] , ... )

    where 'e' is the element and the symbols indicate 0-1, 1 or more, and exactly 1 occurrence, respectively.

    This data member holds an array of arrays. Each secondary array has two items: the element class and the number of objects that can be children.

•   model_noorder

    With model_order this data member determines the content model for children elements. All of the 64 elements fall into one of three content models regarding children elements: 1. No children elements, 2. An ordered list and 3. An unordered list.

    This data member is "undef" in cases (1) and (2).

    It holds the content model for the four elements (AUTHORONLY, INTEXTDEF, PUBTYPE and YEARONLY) which have content model (3) -- an unordered list:

            ( ( e | e | ... ) , e? )+

    where 'e' is an element, '?' is 0 or 1 occurrence and '+' is 1 or more occurrances.

    This data member holds a hash where the first key points to an array holding the list of alterate elements in the content model inner brackets. The second key points to the element represented in the content model as 'e+' (in every case it is SEPARATOR).

•   children

    This data member holds a hash. The first hash key ("elements") points to an array holding the children elements added by the user. The second hash key ("complete") is a boolean indicating whether all children have been added.

Elements: Constructors

In following method signatures replace ELEMENT with the relevant element class name.

        my $el = ELEMENT->new();

Elements: Setters

        $el->set_name( "<name>" );
        $el->set_prompt( "<prompt>" );
        $el->set_help( "<help>" );
        $el->set_display( undef | "name" | "content" );
        $el->set_summary( undef | "name" | "left" | "right" | "content" );
        $el->set_attributes( %hash );
        $el->set_mandatory_attributes_complete( "1" | undef );
        $el->set_optional_attributes_complete( "1" | undef );
        $el->set_content( %hash );
        $el->set_content_complete( "1" | undef );
        $el->set_order( @ArrayOfArrays );
        $el->set_noorder( %hash );
        $el->set_complete( "1" | "0" | undef );
        $el->_set_value( "<value>" );

Elements: Getters

        $el->get_name();
        $el->get_prompt();
        $el->get_help();
        $el->get_display();
        $el->get_summary();
        $el->get_attr_mandatory();  # list:   $self->{attributes}->{mandatory}
        $el->get_attr_optional();   # list:   $self->{attributes}->{optional}
        $el->get_attr_selected();   # list:   $self->{attributes}->{selected}
        $el->get_suggestion();      # scalar: $self->{content}->{suggestion}
        $el->get_value();           # scalar: $self->{content}->{value}
        $el->get_order();           # AoA:    $self->{model_order}
        $el->get_noorder_list();    # list:   $self->{model_noorder}->{element_list}
        $el->get_noorder_separator; # scalar: $self->{model_noorder}->{separator}
        $el->get_children();        # list:   $self->{children}->{element}
        $el->get_last_child();      # object: $self->{children}->{element}[<last>]

Elements: Other methods

•   $el->content_is_complete();

    Returns boolean indicating whether element content has been entered.

    Indicated by a data member which is set after "enter_value()" method called.

•   $el->enter_value();

    User enters element value if element can legally hold one. User may be presented with a suggested value.

    If the element cannot accept a value nothing happens -- no error message/value is generated.

•   $el->is_content_allowed();

    Returns boolean indicating whether the element can hold content.

•   $el->children_are_complete();

    Returns boolean indicating whether all children have been added.

    Simply returns $self->{children}->{complete} and relies on other subroutines having set it appropriately.

•   $el->max_attribute_index();

    Returns maximum index value of selected attributes list: -1 if empty list.

•   $el->max_child_index();

    Returns maximum index value of element children list: -1 if empty list.

•   $el->is_last_element();

    Determines whether element index is the last element in the list of children in the ordered child model: $self->{model_order}.

    Parameters: [ 0 = class ] , 1 = array index.

•   $el->is_last_child();

    Determines whether child index is the last element in the list of children: $self->{children}->{elements}.

    Parameters: [ 0 = class ] , 1 = array index.

•   $el->is_creatable();

    Returns a boolean indicating whether this element class can legally create another object.

    Intended to be called as a class method.

•   $el->list_selectable_attributes();

    Returns a list of all optional attributes available for selection. List consists of all attributes listed in 'optional' list minus all attributes already selected.

•   $el->_build_attribute_help();

    Helper method for method "add_attributes_optional". Takes as parameter a list of attributes for which help screen is being built. Includes "name" and "prompt" for each attribute.

•   $el->has_mandatory_attributes();

    Returns boolean indicating whether element has mandatory attributes.

•   $el->_is_closed_tag();

    Returns boolean indicating whether element can be represented by closed tag. Requires no possible child elements and no current content.

•   $el->get_xml_brief_tag();

    Returns opening xml tag for element.

    Shows only mandatory attributes.

•   $el->get_xml_open_tag();

    Returns opening xml tag for element.

    Parameters: [ 0 = class ] , 1 = show attributes (bool) , 2 = show content (bool).

    Designed to be used in conjunction with "get_xml_close_tag" method. If element has no potential child elements and no content, then will return closed tag, eg. <ELEMENT/>.

•   $el->get_xml_close_tag();

    Returns closing xml tag for element.

    Designed to be used in conjunction with "get_xml_open_tag" method. If element has no potential child elements and no content, then will return no closing tag since "get_xml_open_tag" will have returned a closed tag, eg. <ELEMENT/>.

•   $el->generate_full_xml();

    Generates full xml for element.

    Displays all attributes and element content. If no possible child elements and no current element content, will display closed tag, eg. <ELEMENT/>.

    Method is recursive.

    Parameters (receives): [ 0 = class ] , 1 = element count , 2 = indent/tab count and 3 = output.

    Returns: 0 = element count and 1 = output.

•   $el->get_a_child();

    Returns a single child element matching supplied array index. Returns "undef" if index out of bounds.

    Parameter: [ 0 = class ] , 1 = index.

•   $el->show_progress();

    Generates abbreviated xml for element and element children. Designed to show user's "progress" to date.

    Displays only opening tags. Child elements are displayed only where element is not set to "complete".

    Only mandatory attributes are displayed.

    Method is recursive.

    Parameters (receives): [ 0 = class ] , 1 = output , 2 = stop flag.

    Returns: 0 = output.

    Algorithm (recursive):

            if self is a stop element
                    set stop flag = true
            endif
            add self to output
            if stop flag == true  and  children are complete
                    return 'output'
            else
                    repeat for all children
                            recurse (returns 'output')
                    endrepeat
                    return 'output'
            endif

            if matching element
                    set stop flag = true
            endif
            add to output
            if stop flag true
                    if is complete
                            if has children
                                    recurse
                            else
                                    add fragment to output
                            endif
                    else  # not complete

            if has children
                    repeat for all children
                            recurse (returns 'retval')
                            set output = 'retval'
                    endrepeat
            endif
            return output

•   $el->generate_brief_xml();

    Generates abbreviated xml for element. Designed to show user's "progress" to date.

    Displays only opening tags. Child elements are displayed only where element is not set to "complete".

    Only mandatory attributes are displayed.

    Method is recursive.

    Parameters (receives): [ 0 = class ] and 1 = output.

    Returns: 0 = output.

•   $el->get_full_tag();

    Returns opening +/- closing xml tag for element.

    Displays all attributes and element content. If no possible child elements and no current content, will display single closed tag, eg. <ELEMENT/>.

•   $el->_test_attributes_mandatory();

    Intended as helper method for "is_creatable". Tests that mandatory attributes can be created.

    Note: The attributes are not actually added to the element.

    Returns boolean. False value indicates failure adding mandatory attributes and the associated element should be detroyed.

•   $el->add_attributes_mandatory();

    Mandatory attributes are immediately added (note: mandatory attributes should have been added during element construction).

    Returns boolean. False value indicates failure adding mandatory attributes and the associated element should be detroyed.

    Can be run in 'silent' mode with no output from method. There are no guarantees about the 'silence' of attributes' "select_value" method, but all such methods should not generate output.

    Parameters: [ 0 = class ] , [ 1 = <text> | 1 ]

•   $el->add_attributes_optional();

    The user selects optional attributes to add. Help is available. Element feedback is presented as the user proceeds.

•   $el->mandatory_attributes_complete();

    Returns boolean indicating whether mandatory attributes have been added.

    Indicated by a data member which is set after "add_attributes()" method called.

•   $el->optional_attributes_complete();

    Returns boolean indicating whether optional attributes have been added.

    Indicated by a data member which is set after "add_attributes()" method called.

•   $el->add_attributes();

    First adds the mandatory attributes and then gives user chance to add optional attributes.

    Returns boolean indicating whether attributes added successfully. Only mechanism of failure occurs when element requires mandatory attribute such as ROLE which cannot be added because maximum number of ROLE attributes already exist for this PUBTYPE.

•   $el->add_child();

    Adds a child to the current element.

    Parameters: [ 0 = class ] , 1 = child element (object).

•   $el->_select_next_child_order();

    Helper method for method "select_next_child". Used when element has a modal content model. Help is provided where appropriate.

    Returns two element list: 0 = message indicating whether selection was forced by the content model or chosen by user , 1 = element class name.

    Note: If user makes no selection, and content model forces none, an "undef" element class name is returned along with an informative message.

    When content model is exhausted the content flag -- $self->{children}->{complete} -- is set to true.

    The algorithm for this subroutine is the nastiest in the program. I include it here in full for future occasions when I may have to debug.

            if no current child elements
                    set OUT_OF_CHILDREN = true
            else
                    set OUT_OF_CHILDREN = false
            endif

            begin loop
                    if OUT_OF_CHILDREN == true
                            switch require
                                    case +
                                            if PREV != element
                                                    EXIT: mandatory element
                                            else  # ( PREV_CHILD == element )
                                                    ASK: repeat element
                                                    if yes
                                                            EXIT: chosen element
                                                    else  # ( no )
                                                            if last element
                                                                    set children_full flag = true
                                                                    EXIT: END
                                                            else  # ( not last element )
                                                                    advance element
                                                            endif
                                                    endif
                                            endif
                                    endcase
                                    case 1
                                            if last element
                                                    set children_full flag = true
                                            endif
                                            EXIT: mandatory element
                                    endcase
                                    case ?
                                            ASK: add element
                                            if yes
                                                    EXIT: chosen element
                                            else  # ( no repeat )
                                                    if last element
                                                            set children_full flag = true
                                                            EXIT: END
                                                    else  # ( not last element )
                                                            advance element
                                                    endif
                                            endif
                                    endcase
                            endswitch
                    else  # ( OUT_OF_CHILDREN == false )
                            if child == element
                                    switch require
                                            case ? | 1
                                                    if last child
                                                            if last element
                                                                    set children_full flag = true
                                                                    EXIT: END
                                                            else  # ( not last element )
                                                                    advance element
                                                                    set OUT_OF_CHILDREN = true
                                                            endif
                                                    else  # ( not last child )
                                                            if last element
                                                                    ERROR: exhausted content model but got $child
                                                            else  # ( not last element )
                                                                    advance element
                                                                    set PREV_CHILD = null
                                                                    advance child
                                                            endif
                                                    endif
                                            endcase
                                            case +
                                                    if last child
                                                            ASK: repeat element
                                                            if yes
                                                                    EXIT: optional element
                                                            else  # ( no repeat )
                                                                    if last element
                                                                            set children_full flag = true
                                                                            EXIT: END
                                                                    else  # ( not last element )
                                                                            advance element
                                                                            set OUT_OF_CHILDREN = true
                                                                    endif
                                                            endif
                                                    else  # ( not last child )
                                                            set PREV_CHILD = child
                                                            advance child
                                                    endif
                                            endcase
                                    endswitch
                            else  # ( child != element )
                                    switch require
                                            case +
                                                    if last element
                                                            ERROR: expecting $element, got $child
                                                    else  # ( not last element )
                                                            if PREV_CHILD == element
                                                                    set PREV_CHILD = null
                                                                    advance element
                                                            else  # ( PREV_CHILD != element )
                                                                    ERROR: expecting $element, got $child
                                                            endif
                                                    endif
                                            endcase
                                            case ?
                                                    if last element
                                                            ERROR: content model exhausted, no match for $child
                                                    else  # ( not last element )
                                                            advance element
                                                    endif
                                            endcase
                                            case 1
                                                    ERROR: expecting $element, got $child
                                            endcase
                                    endswitch
                            endif
                    endif
            end loop

    Warning: In a number of places in this subroutine the program can "die". This occurs when a mismatch between the child element model and the actual child elements is detected. If the mismatch truly exists it is a coding error since the algorithm should force child elements to match the content model. If the mismatch is not real the code has erred in analysing the data. Either way, it is an unrecoverable error and the algorithm/code must be corrected.

•   $el->list_selectable_children_noorder();

    Used when selecting child elements when following the unordered model.

    Returns a list of all optional elements available for selection. List consists of all elements attributes listed in 'optional' list minus all attributes already selected.

•   $el->_build_element_help();

    Helper method for method "_select_next_child_noorder". Takes as parameter a list of elements for which help screen is being built.

•   $el->_select_next_child_noorder();

    The user selects optional child element to add.

    Helper method for 'select_next_child'.

    Returns two element list: 0 = message indicating whether selection was forced by the content model or chosen by user , 1 = element class name.

    Note: If user chooses to finish child element selection, "undef" element class name is returned along with an informative message.

    When child element selection is finished the content flag -- $self->{children}->{complete} -- is set to true.

    Help is available.

    No option to exit until at least one element has been selected.

    Cannot select two "Separator" elements consecutively.

•   $el->select_next_child();

    The user selects a child element to add. Help is available.

    Returns two element list: 0 = text indicating whether mandatory or user choice ,
                            1 = element class name.

    Note: If user makes no selection, and content model forces none, an "undef" element class name is returned along with an informative message.

    The algorithm for this subroutine is the nastiest in the program. I include it here in full for future occasions when I may have to debug.

•   $el->is_copyable();

    Returns boolean indicating whether element can be copied.

    Based on value of $self->{copyable}.

•   $el->copy();

    Attempts to copy element. Returns either a reference to a copied element or an error message.

    Can test for success using "ref" function.

    Does not copy attributes. Attributes requiring user input during creation are not copyable (this includes Type_PubType, Role_UserDef, Role_Misc and Role_Link).

    Does not copy child elements. For that, use the "duplicate" method.

•   $el->has_attributes();

    Returns boolean indicating whether element has attributes.

•   $el->has_children();

    Returns boolean indicating whether element has children.

•   $el->_push_attribute();

    Adds attribute to element.

    Parameters: [ 0 = class ] , 1 = attribute object.

•   $el->duplicate();

    Returns either a reference to a duplicate element or an error message.

    Copies all attributes, child elements and element content.

•   $el->duplicate();

    Returns either a reference to a duplicate element or an error message.

    Copies all attributes, child elements and element content.

•   $el->is_ordered_child_model();

    Returns boolean indicating nature of child element content model.

•   $el->is_unordered_child_model();

    Returns boolean indicating nature of child element content model.

•   $el->is_childless_model();

    Returns boolean indicating nature of child element content model.

•   $el->get_last_parent();

    Return reference to last parent element.

    Parameters: [ 0 = class ] , 1 = originator flag (true if not originating element)

    Recursive algorithm:

            if child elements
                    recurse last child (returns 'retval')
                    if 'retval' is element
                            return 'retval'
                    else
                            return self
                    endif
            else
                    if recursed element
                            return undef
                    else
                            return self
                    endif
            endif

•   $el->get_last_element();

    Return reference to last element.

    Recursive algorithm:

            if child elements
                    recurse last child (returns 'retval')
                    return 'retval'
            else
                    return self
            endif

•   $el->delete_last_child();

    Delete last child of this element.

    Returns element.

•   $el->delete_last_element();

    Delete last element.

    Return deleted element.

•   $el->has_incomplete_descendent();

    Returns boolean indicating whether any descendent of element is incomplete.

•   $el->get_last_incomplete();

    Return reference to last element in tree that is incomplete.

    Returns "undef" if all elements complete.

    Recursive algorithm:

            if child elements
                    recurse last child (returns 'retval')
                    if 'retval' is element
                            return 'retval'
                    endif
            else
                    if not complete
                            return self
                    else
                            return undef
                    endif
            endif

•   $el->is_named();

    Returns boolean indicating whether element has display data member set to "name".

•   $el->get_last_named();

    Return reference to last element in tree with display data member set to 'name'.

•   $el->get_style_name();

    Finds StyleName element and returns element content.

    If unsuccessful, return "undef".

•   $el->get_most_recent();

    Return reference to last element in tree of supplied element class.

    If no element found, return "undef".

•   $el->reset_all_counters();

    Resets all role level counters

    Called by PubType, AuthorOnly, YearOnly and InTextDef during element creation.

•   $el->named_in_summary();

    Boolean indicating whether to include element in summary.

•   $el->content_in_summary();

    Boolean indicating whether to include raw element content in summary. Currently only applies to SEPARATOR.

•   $el->has_bracketing_child();

    Boolean indicating whether element has any child elements whose content will "bracket" this element's content in output. Currently only applies to PRECEEDING and FOLLOWING.

•   $el->generate_summary();

    Generates substantial portion of style summary. Called by UI method 'write_summary'.

    Parameters: [ 0 = class ] , 1 = previous output.

    Returns: 0 = current output.

    Since this method is only called on a complete style, we can make assumptions based on the style following the DTD.

    Recursive algorithm.

            switch <element class>
                    case 'StyleName'
                            add to output: style name
                    endcase
                    case 'RefStyle'
                            add to output: header = "Bibliography Style"
                    endcase
                    case 'PubStyle'
                            add to output: header giving publication type
                    endcase
                    case 'CitStyle'
                            add to output: header = "Citation Style"
                    endcase
                    case 'InTextDef'
                            add to output: header = Author and Year
                    endcase
                    case 'AuthorOnly'
                            add to output: header = Author
                    endcase
                    case 'YearOnly'
                            add to output: header = Year
                    endcase
            endswitch
            if summary flag == name
                    if bracketing child element(s)
                            set bracket flag = true
                    endif
                    if bracket flag == true
                            add to output: opening brackets
                    endif
                    if bracket flag == true
                            if left bracketing element present
                                    print left bracketing element contents
                            endif
                    endif
                    add to output: left marker
                    add to output: element name
                    repeat for all attributes
                            if attribute summary flag == true
                                    add to output: attribute value (italicised)
                            endif
                    endrepeat
                    add to output: right marker
            endif
            if have children
                    repeat for all children
                            ** recurse (send output, receive output as 'retval')
                    endrepeat
            endif
            return output

  Elements: List of Classes
To see a list of attribute classes use the "document-dtd-entities" utility that shipped with this program. It extracts attribute and element properties from this script, assembles and formats them into a single html document.

All elements descend from one of three ancestor classes depending on their content model:

•   _Model_Childless

    Elements descended from this class have a content model specifying no children elements.

•   _Model_Order

    Elements descended from this class have a content model of the general form:

            ( element_A[?|+] , element_B[?|+] , ... )

•   _Model_Noorder

    Elements descended from this class have a content model of the general form:

            ( element_A | element_B , ... ) , element_X? )+

USER-INTERFACE CLASS
This class holds the user-built bibliography style.

  UI: Public Interface
UI: Data members

        %self = (

                help  =>  {

                        <help topic>       =>  <help text> ,

                        ...

                } ,

                cache  =>  {

                        "element_class_A"  =>  element_A ,

                        "element_class_B"  =>  element_B ,

                        ...

                } ,

                root  =>  "undef" | element ,

                filename  =>  undef | <filename>,

        )

•   help

    Introductory help system.

    Is a hash consisting of <"help topic" : "help text"> pairs.

•   cache

    Cache for frequently used elements.

    First hash key ("cachable") points to list of cachable elements.

    Second has key points to subsidiary hash which holds key:value pairs of element class names and the corresponding element.

•   root

    Location of style's root element.

•   style_file

    Name of style file. Set after successful output.

•   summary_file

    Name of summary file. Set after successful output.

UI: Constructors

        my $ui = UI->new();

UI: Setters

        $ui->set_root( <element> );
        $ui->set_style_file( "<filename>" );
        $ui->set_summary_file( "<filename>" );

UI: Getters

        $ui->get_help_topics();          # list:   keys   ( $self->{help} )
        $ui->get_help( "<topic>" );      # scalar: value  ( $self->{help}->{<topic>} )
                                         #         takes parameter: help topic
        $ui->get_cachable();             # list:   $self->{cache}->{cachable}
        $ui->get_cached();               # list:   defined( $self->{cache}->{elements} )
        $ui->get_cached_element( "<class>" );
                                         # object: cached element
        $ui->get_root();                 # object: root element
        $ui->get_style_file();           # scalar: style file filename
        $ui->get_summary_file();         # scalar: summary file filename

UI: Other methods

•   $ui->help_system();

    Runs help system -- a menu allowing the selection of a series of

•   $ui->get_last_parent();

    Returns reference to last parent element.

•   $ui->can_copy_recent();

    Returns booelan indicating whether element can copy recent version of itself.

    Parameters: [ 0 = class ] , 1 = element class | object

•   $el->delete_selected_element();

    Gives the user the option of deleting element(s).

    Depending on the state of the element tree, the user can delete the last element or the last major ("named") element. A "named" element has its 'display' data member set to 'name' -- in general they are the elements corresponding to ris fields.

    A "complete" element has had all children added and its 'children->complete' data member is set to true ("1").

    Algorithm is:

            get last named element
            if element is complete
                    repeat until last named element is deleted
                            delete last element
                    endrepeat
            else
                    delete last element only
            endif

•   $ui->create_element();

    Creates element. If element of class already exists, user can duplicate most recent.

•   $ui->startup_checks();

    Currently checks for: write access to current directory.

•   $ui->get_output_filename();

    Returns filename for output file. Uses File::Temp module.

    If filename does not exist in current directory, simply return default.

    If it does, then user must select new filename. File::Temp is used to provide a suggestion based on the default filename.

    Requires the following parameters: [ 0 = class ] , 1 = default filename , 2 = filename template pattern , 3 = filename template suffix , 4 = prompt.

    Parameters 2 and 3 are in the format required by File::Temp. Parameter 2 must end in at leat 4 'X's -- these will be replaced with random digits. The suffix is the part of the filename following the part specified by parameter 2. It is not restricted to a DOS-style three letter extension.

    Example: Default filename (parameter 1) = 'experimental-style.xml'. Filename template pattern (parameter 2) = 'experimental-XXXX'. Filename template suffix (parameter 3) = '-style.xml'. Prompt (parameter 4) = 'Enter name for style file:'.

•   $ui->write_style();

    Writes style to file. Checks filename doesn't already exist. If so, proposes alternative.

•   $ui->write_summary();

    Writes style summary to file. Checks filename doesn't already exist. If so, proposes alternative.

•   $ui->get_command_base();

    Gets base for refdba commands. Involves checking for access to refdba. Also determines whether username and password required.

    If succeeds, returns base command of the form:

            refdba [-u <username> -w <password>] -C

    If fails, returns "undef".

•   $ui->upload_style();

    Uploads style to refdb. If style of same name already exists, attempt to save it to disk.

AUTHOR
David Nebauer, david <at> nebauer <dot> org

COPYRIGHT AND LICENSE
Copyright (C) 2004 by David Nebauer

This library is distributed under the same license and conditions as the "RefDB" project <<http://refdb.sourceforge.net/>>.