--- name: "SGMLS" section: "3pm" platform: "linux" package: "perl-sgmls" version: "1:1.1-14" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/SGMLS" --- # SGMLS(3pm) class for postprocessing the output from the sgmls and nsgmls parsers. ## NAME SGMLS - class for postprocessing the output from the sgmls and nsgmls parsers. ## SYNOPSIS ``` use SGMLS; my $parse = new SGMLS(STDIN); my $event = $parse->next_event; while ($event) { SWITCH: { ($event->type eq 'start_element') && do { my $element = $event->data; # An object of class SGMLS_Element [[your code for the beginning of an element]] last SWITCH; }; ($event->type eq 'end_element') && do { my $element = $event->data; # An object of class SGMLS_Element [[your code for the end of an element]] last SWITCH; }; ($event->type eq 'cdata') && do { my $cdata = $event->data; # A string [[your code for character data]] last SWITCH; }; ($event->type eq 'sdata') && do { my $sdata = $event->data; # A string [[your code for system data]] last SWITCH; }; ($event->type eq 're') && do { [[your code for a record end]] last SWITCH; }; ($event->type eq 'pi') && do { my $pi = $event->data; # A string [[your code for a processing instruction]] last SWITCH; }; ($event->type eq 'entity') && do { my $entity = $event->data; # An object of class SGMLS_Entity [[your code for an external entity]] last SWITCH; }; ($event->type eq 'start_subdoc') && do { my $entity = $event->data; # An object of class SGMLS_Entity [[your code for the beginning of a subdoc entity]] last SWITCH; }; ($event->type eq 'end_subdoc') && do { my $entity = $event->data; # An object of class SGMLS_Entity [[your code for the end of a subdoc entity]] last SWITCH; }; ($event->type eq 'conforming') && do { [[your code for a conforming document]] last SWITCH; }; die "Internal error: unknown event type " . $event->type . "\n"; } $event = $parse->next_event; } ``` ## DESCRIPTION The **SGMLS** package consists of several related classes: see "SGMLS", "SGMLS\_Event", "SGMLS\_Element", "SGMLS\_Attribute", "SGMLS\_Notation", and "SGMLS\_Entity". All of these classes are available when you specify ``` use SGMLS; ``` Generally, the only object which you will create explicitly will belong to the `"SGMLS"` class; all of the others will then be created automatically for you over the course of the parse. Much fuller documentation is available in the `".sgml"` files in the `"DOC/"` directory of the `"SGMLS.pm"` distribution. ### The "SGMLS" class This class holds a single parse. When you create an instance of it, you specify a file handle as an argument (if you are reading the output of **sgmls** or **nsgmls** from a pipe, the file handle will ordinarily be `"STDIN"`): ``` my $parse = new SGMLS(STDIN); ``` The most important method for this class is `"next_event"`, which reads and returns the next major event from the input stream. It is important to note that the `"SGMLS"` class deals with most **ESIS** events itself: attributes and entity definitions, for example, are collected and stored automatically and invisibly to the user. The following list contains all of the methods for the `"SGMLS"` class: - next\_event(): Return an "SGMLS\_Event" object containing the next major event from the SGML parse. - element(): Return an "SGMLS\_Element" object containing the current element in the document. - file(): Return a string containing the name of the current SGML source file (this will work only if the "-l" option was given to **sgmls** or **nsgmls**). - line(): Return a string containing the current line number from the source file (this will work only if the "-l" option was given to **sgmls** or **nsgmls**). - appinfo(): Return a string containing the "APPINFO" parameter (if any) from the SGML declaration. - notation(NNAME): Return an "SGMLS\_Notation" object representing the notation named "NNAME". With newer versions of **nsgmls**, all notations are available; otherwise, only the notations which are actually used will be available. - entity(ENAME): Return an "SGMLS\_Entity" object representing the entity named "ENAME". With newer versions of **nsgmls**, all entities are available; otherwise, only external data entities and internal entities used as attribute values will be available. - ext(): Return a reference to an associative array for user-defined extensions. ### The "SGMLS\_Event" class This class holds a single major event, as generated by the `"next_event"` method in the `"SGMLS"` class. It uses the following methods: - type(): Return a string describing the type of event: "start\_element", "end\_element", "cdata", "sdata", "re", "pi", "entity", "start\_subdoc", "end\_subdoc", and "conforming". See "SYNOPSIS", above, for the values associated with each of these. - data(): Return the data associated with the current event (if any). For "start\_element" and "end\_element", returns an "SGMLS\_ELement" object; for "entity", "start\_subdoc", and "end\_subdoc", returns an "SGMLS\_Entity" object; for "cdata", "sdata", and "pi", returns a string; and for "re" and "conforming", returns the empty string. See "SYNOPSIS", above, for an example of this method's use. - key(): Return a string key to the event, such as an element or entity name (otherwise, the same as data()). - file(): Return the current file name, as in the "SGMLS" class. - line(): Return the current line number, as in the "SGMLS" class. - element(): Return the current element, as in the "SGMLS" class. - parse(): Return the "SGMLS" object which generated the event. - entity(ENAME): Look up an entity, as in the "SGMLS" class. - notation(ENAME): Look up a notation, as in the "SGMLS" class. - ext(): Return a reference to an associative array for user-defined extensions. ### The "SGMLS\_Element" class This class is used for elements, and contains all associated information (such as the element's attributes). It recognises the following methods: - name(): Return a string containing the name, or Generic Identifier, of the element, in upper case. - parent(): Return the "SGMLS\_Element" object for the element's parent (if any). - parse(): Return the "SGMLS" object for the current parse. - attributes(): Return a reference to an associative array of attribute names and "SGMLS\_Attribute" structures. Attribute names will be all in upper case. - attribute\_names(): Return an array of strings containing the names of all attributes defined for the current element, in upper case. - attribute(ANAME): Return the "SGMLS\_Attribute" structure for the attribute "ANAME". - set\_attribute(ATTRIB): Add the "SGMLS\_Attribute" object "ATTRIB" to the current element, replacing any other attribute structure with the same name. - in(GI): Return "true" (ie. 1) if the string "GI" is the name of the current element's parent, or "false" (ie. 0) if it is not. - within(GI): Return "true" (ie. 1) if the string "GI" is the name of any of the ancestors of the current element, or "false" (ie. 0) if it is not. - ext(): Return a reference to an associative array for user-defined extensions. ### The "SGMLS\_Attribute" class Each instance of an attribute for each `"SGMLS_Element"` is an object belonging to this class, which recognises the following methods: - name(): Return a string containing the name of the current attribute, all in upper case. - type(): Return a string containing the type of the current attribute, all in upper case. Available types are "IMPLIED", "CDATA", "NOTATION", "ENTITY", and "TOKEN". - value(): Return the value of the current attribute, if any. This will be an empty string if the type is "IMPLIED", a string of some sort if the type is "CDATA" or "TOKEN" (if it is "TOKEN", you may want to split the string into a series of separate tokens), an "SGMLS\_Notation" object if the type is "NOTATION", or an "SGMLS\_Entity" object if the type is "ENTITY". Note that if the value is "CDATA", it will *not* have escape sequences for 8-bit characters, record ends, or SDATA processed -- that will be your responsibility. - is\_implied(): Return "true" (ie. 1) if the value of the attribute is implied, or "false" (ie. 0) if it is specified in the document. - set\_type(TYPE): Change the type of the attribute to the string "TYPE" (which should be all in upper case). Available types are "IMPLIED", "CDATA", "NOTATION", "ENTITY", and "TOKEN". - set\_value(VALUE): Change the value of the attribute to "VALUE", which may be a string, an "SGMLS\_Entity" object, or an "SGMLS\_Notation" subject, depending on the attribute's type. - ext(): Return a reference to an associative array available for user-defined extensions. ### The "SGMLS\_Notation" class All declared notations appear as objects belonging to this class, which recognises the following methods: - name(): Return a string containing the name of the notation. - sysid(): Return a string containing the system identifier of the notation, if any. - pubid(): Return a string containing the public identifier of the notation, if any. - ext(): Return a reference to an associative array available for user-defined extensions. ### The "SGMLS\_Entity" class All declared entities appear as objects belonging to this class, which recognises the following methods: - name(): Return a string containing the name of the entity, in mixed case. - type(): Return a string containing the type of the entity, in upper case. Available types are "CDATA", "SDATA", "NDATA" (external entities only), "SUBDOC", "PI" (newer versions of **nsgmls** only), or "TEXT" (newer versions of **nsgmls** only). - value(): Return a string containing the value of the entity, if it is internal. - sysid(): Return a string containing the system identifier of the entity (if any), if it is external. - pubid(): Return a string containing the public identifier of the entity (if any), if it is external. - filenames(): Return an array of strings containing any file names generated from the identifiers, if the entity is external. - notation(): Return the "SGMLS\_Notation" object associated with the entity, if it is external. - data\_attributes(): Return a reference to an associative array of data attribute names (in upper case) and the associated "SGMLS\_Attribute" objects for the current entity. - data\_attribute\_names(): Return an array of data attribute names (in upper case) for the current entity. - data\_attribute(ANAME): Return the "SGMLS\_Attribute" object for the data attribute named "ANAME" for the current entity. - set\_data\_attribute(ATTRIB): Add the "SGMLS\_Attribute" object "ATTRIB" to the current entity, replacing any other data attribute with the same name. - ext(): Return a reference to an associative array for user-defined extensions. ## AUTHOR AND COPYRIGHT Copyright 1994 and 1995 by David Megginson, `"dmeggins@aix1.uottawa.ca"`. Distributed under the terms of the Gnu General Public License (version 2, 1991) -- see the file `"COPYING"` which is included in the **SGMLS.pm** distribution. ## SEE ALSO: SGMLS::Output and SGMLS::Refs. ## POD ERRORS Hey! **The above document had some coding errors, which are explained below:** - Around line 117: '=item' outside of any '=over' - Around line 148: You forgot a '=back' before '=head2' - Around line 154: '=item' outside of any '=over' - Around line 191: You forgot a '=back' before '=head2' - Around line 197: '=item' outside of any '=over' - Around line 232: You forgot a '=back' before '=head2' - Around line 237: '=item' outside of any '=over' - Around line 270: You forgot a '=back' before '=head2' - Around line 275: '=item' outside of any '=over' - Around line 287: You forgot a '=back' before '=head2' - Around line 292: '=item' outside of any '=over' - Around line 333: You forgot a '=back' before '=head1'