.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SGMLS 3pm"
.TH SGMLS 3pm "2004-02-22" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
SGMLS \- class for postprocessing the output from the \fBsgmls\fR and
\&\fBnsgmls\fR parsers.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use SGMLS;
.Ve
.PP
.Vb 1
\&  my $parse = new SGMLS(STDIN);
.Ve
.PP
.Vb 2
\&  my $event = $parse\->next_event;
\&  while ($event) {
.Ve
.PP
.Vb 1
\&    SWITCH: {
.Ve
.PP
.Vb 5
\&      ($event\->type eq \(aqstart_element\(aq) && do {
\&        my $element = $event\->data;    # An object of class SGMLS_Element
\&        [[your code for the beginning of an element]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 5
\&      ($event\->type eq \(aqend_element\(aq) && do {
\&        my $element = $event\->data;    # An object of class SGMLS_Element
\&        [[your code for the end of an element]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 5
\&      ($event\->type eq \(aqcdata\(aq) && do {
\&        my $cdata = $event\->data;      # A string
\&        [[your code for character data]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 5
\&      ($event\->type eq \(aqsdata\(aq) && do {
\&        my $sdata = $event\->data;      # A string
\&        [[your code for system data]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 4
\&      ($event\->type eq \(aqre\(aq) && do {
\&        [[your code for a record end]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 5
\&      ($event\->type eq \(aqpi\(aq) && do {
\&        my $pi = $event\->data;         # A string
\&        [[your code for a processing instruction]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 5
\&      ($event\->type eq \(aqentity\(aq) && do {
\&        my $entity = $event\->data;     # An object of class SGMLS_Entity
\&        [[your code for an external entity]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 5
\&      ($event\->type eq \(aqstart_subdoc\(aq) && do {
\&        my $entity = $event\->data;     # An object of class SGMLS_Entity
\&        [[your code for the beginning of a subdoc entity]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 5
\&      ($event\->type eq \(aqend_subdoc\(aq) && do {
\&        my $entity = $event\->data;     # An object of class SGMLS_Entity
\&        [[your code for the end of a subdoc entity]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 4
\&      ($event\->type eq \(aqconforming\(aq) && do {
\&        [[your code for a conforming document]]
\&        last SWITCH;
\&      };
.Ve
.PP
.Vb 2
\&      die "Internal error: unknown event type " . $event\->type . "\en";
\&    }
.Ve
.PP
.Vb 2
\&    $event = $parse\->next_event;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\s-1SGMLS\s0\fR package consists of several related classes: see
\&\*(L"\s-1SGMLS\s0\*(R", \*(L"SGMLS_Event\*(R", \*(L"SGMLS_Element\*(R",
\&\*(L"SGMLS_Attribute\*(R", \*(L"SGMLS_Notation\*(R", and \*(L"SGMLS_Entity\*(R".  All
of these classes are available when you specify
.PP
.Vb 1
\&  use SGMLS;
.Ve
.PP
Generally, the only object which you will create explicitly will
belong to the \f(CW\*(C`SGMLS\*(C'\fR 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 \f(CW\*(C`.sgml\*(C'\fR files in the \f(CW\*(C`DOC/\*(C'\fR
directory of the \f(CW\*(C`SGMLS.pm\*(C'\fR distribution.
.ie n .Sh "The ""SGMLS"" class"
.el .Sh "The \f(CWSGMLS\fP class"
.IX Subsection "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 \fBsgmls\fR or \fBnsgmls\fR from a pipe, the file handle will
ordinarily be \f(CW\*(C`STDIN\*(C'\fR):
.PP
.Vb 1
\&  my $parse = new SGMLS(STDIN);
.Ve
.PP
The most important method for this class is \f(CW\*(C`next_event\*(C'\fR, which reads
and returns the next major event from the input stream.  It is
important to note that the \f(CW\*(C`SGMLS\*(C'\fR class deals with most \fB\s-1ESIS\s0\fR
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 \f(CW\*(C`SGMLS\*(C'\fR class:
.RE
.ie n .IP """next_event()""\fR: Return an \f(CW""SGMLS_Event"" object containing the next major event from the \s-1SGML\s0 parse."
.el .IP "\f(CWnext_event()\fR: Return an \f(CWSGMLS_Event\fR object containing the next major event from the \s-1SGML\s0 parse."
.IX Item "next_event(): Return an SGMLS_Event object containing the next major event from the SGML parse."
.RE
.PD 0
.ie n .IP """element()""\fR: Return an \f(CW""SGMLS_Element"" object containing the current element in the document."
.el .IP "\f(CWelement()\fR: Return an \f(CWSGMLS_Element\fR object containing the current element in the document."
.IX Item "element(): Return an SGMLS_Element object containing the current element in the document."
.RE
.ie n .IP """file()""\fR: Return a string containing the name of the current \s-1SGML\s0 source file (this will work only if the \f(CW""\-l""\fR option was given to \fBsgmls\fR or \fBnsgmls)."
.el .IP "\f(CWfile()\fR: Return a string containing the name of the current \s-1SGML\s0 source file (this will work only if the \f(CW\-l\fR option was given to \fBsgmls\fR or \fBnsgmls\fR)."
.IX Item "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)."
.RE
.ie n .IP """line()""\fR: Return a string containing the current line number from the source file (this will work only if the \f(CW""\-l""\fR option was given to \fBsgmls\fR or \fBnsgmls)."
.el .IP "\f(CWline()\fR: Return a string containing the current line number from the source file (this will work only if the \f(CW\-l\fR option was given to \fBsgmls\fR or \fBnsgmls\fR)."
.IX Item "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)."
.RE
.ie n .IP """appinfo()""\fR: Return a string containing the \f(CW""APPINFO"" parameter (if any) from the \s-1SGML\s0 declaration."
.el .IP "\f(CWappinfo()\fR: Return a string containing the \f(CWAPPINFO\fR parameter (if any) from the \s-1SGML\s0 declaration."
.IX Item "appinfo(): Return a string containing the APPINFO parameter (if any) from the SGML declaration."
.RE
.ie n .IP """notation(NNAME)""\fR: Return an \f(CW""SGMLS_Notation""\fR object representing the notation named \f(CW""NNAME""\fR.  With newer versions of \fBnsgmls, all notations are available; otherwise, only the notations which are actually used will be available."
.el .IP "\f(CWnotation(NNAME)\fR: Return an \f(CWSGMLS_Notation\fR object representing the notation named \f(CWNNAME\fR.  With newer versions of \fBnsgmls\fR, all notations are available; otherwise, only the notations which are actually used will be available."
.IX Item "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."
.RE
.ie n .IP """entity(ENAME)""\fR: Return an \f(CW""SGMLS_Entity""\fR object representing the entity named \f(CW""ENAME""\fR.  With newer versions of \fBnsgmls, all entities are available; otherwise, only external data entities and internal entities used as attribute values will be available."
.el .IP "\f(CWentity(ENAME)\fR: Return an \f(CWSGMLS_Entity\fR object representing the entity named \f(CWENAME\fR.  With newer versions of \fBnsgmls\fR, all entities are available; otherwise, only external data entities and internal entities used as attribute values will be available."
.IX Item "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."
.RE
.ie n .IP """ext()"": Return a reference to an associative array for user-defined extensions."
.el .IP "\f(CWext()\fR: Return a reference to an associative array for user-defined extensions."
.IX Item "ext(): Return a reference to an associative array for user-defined extensions."
.PD
.ie n .Sh "The ""SGMLS_Event"" class"
.el .Sh "The \f(CWSGMLS_Event\fP class"
.IX Subsection "The SGMLS_Event class"
This class holds a single major event, as generated by the
\&\f(CW\*(C`next_event\*(C'\fR method in the \f(CW\*(C`SGMLS\*(C'\fR class.  It uses the following
methods:
.RE
.ie n .IP """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 ""\s-1SYNOPSIS\s0"", above, for the values associated with each of these."
.el .IP "\f(CWtype()\fR: Return a string describing the type of event: ``start_element'', ``end_element'', ``cdata'', ``sdata'', ``re'', ``pi'', ``entity'', ``start_subdoc'', ``end_subdoc'', and ``conforming''.  See ``\s-1SYNOPSIS\s0'', above, for the values associated with each of these."
.IX Item "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."
.RE
.PD 0
.ie n .IP """data()""\fR: Return the data associated with the current event (if any).  For ""start_element"" and ""end_element"", returns an \f(CW""SGMLS_ELement""\fR object; for ""entity"", ""start_subdoc"", and ""end_subdoc"", returns an \f(CW""SGMLS_Entity"" object; for ""cdata"", ""sdata"", and ""pi"", returns a string; and for ""re"" and ""conforming"", returns the empty string.  See ""\s-1SYNOPSIS\s0"", above, for an example of this method's use."
.el .IP "\f(CWdata()\fR: Return the data associated with the current event (if any).  For ``start_element'' and ``end_element'', returns an \f(CWSGMLS_ELement\fR object; for ``entity'', ``start_subdoc'', and ``end_subdoc'', returns an \f(CWSGMLS_Entity\fR object; for ``cdata'', ``sdata'', and ``pi'', returns a string; and for ``re'' and ``conforming'', returns the empty string.  See ``\s-1SYNOPSIS\s0'', above, for an example of this method's use."
.IX Item "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."
.RE
.ie n .IP """key()""\fR: Return a string key to the event, such as an element or entity name (otherwise, the same as \f(CW""data()"")."
.el .IP "\f(CWkey()\fR: Return a string key to the event, such as an element or entity name (otherwise, the same as \f(CWdata()\fR)."
.IX Item "key(): Return a string key to the event, such as an element or entity name (otherwise, the same as data())."
.RE
.ie n .IP """file()""\fR: Return the current file name, as in the \f(CW""SGMLS"" class."
.el .IP "\f(CWfile()\fR: Return the current file name, as in the \f(CWSGMLS\fR class."
.IX Item "file(): Return the current file name, as in the SGMLS class."
.RE
.ie n .IP """line()""\fR: Return the current line number, as in the \f(CW""SGMLS"" class."
.el .IP "\f(CWline()\fR: Return the current line number, as in the \f(CWSGMLS\fR class."
.IX Item "line(): Return the current line number, as in the SGMLS class."
.RE
.ie n .IP """element()""\fR: Return the current element, as in the \f(CW""SGMLS"" class."
.el .IP "\f(CWelement()\fR: Return the current element, as in the \f(CWSGMLS\fR class."
.IX Item "element(): Return the current element, as in the SGMLS class."
.RE
.ie n .IP """parse()""\fR: Return the \f(CW""SGMLS"" object which generated the event."
.el .IP "\f(CWparse()\fR: Return the \f(CWSGMLS\fR object which generated the event."
.IX Item "parse(): Return the SGMLS object which generated the event."
.RE
.ie n .IP """entity(ENAME)""\fR: Look up an entity, as in the \f(CW""SGMLS"" class."
.el .IP "\f(CWentity(ENAME)\fR: Look up an entity, as in the \f(CWSGMLS\fR class."
.IX Item "entity(ENAME): Look up an entity, as in the SGMLS class."
.RE
.ie n .IP """notation(ENAME)""\fR: Look up a notation, as in the \f(CW""SGMLS"" class."
.el .IP "\f(CWnotation(ENAME)\fR: Look up a notation, as in the \f(CWSGMLS\fR class."
.IX Item "notation(ENAME): Look up a notation, as in the SGMLS class."
.RE
.ie n .IP """ext()"": Return a reference to an associative array for user-defined extensions."
.el .IP "\f(CWext()\fR: Return a reference to an associative array for user-defined extensions."
.IX Item "ext(): Return a reference to an associative array for user-defined extensions."
.PD
.ie n .Sh "The ""SGMLS_Element"" class"
.el .Sh "The \f(CWSGMLS_Element\fP class"
.IX Subsection "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:
.RE
.ie n .IP """name()"": Return a string containing the name, or Generic Identifier, of the element, in upper case."
.el .IP "\f(CWname()\fR: Return a string containing the name, or Generic Identifier, of the element, in upper case."
.IX Item "name(): Return a string containing the name, or Generic Identifier, of the element, in upper case."
.RE
.PD 0
.ie n .IP """parent()""\fR: Return the \f(CW""SGMLS_Element"" object for the element's parent (if any)."
.el .IP "\f(CWparent()\fR: Return the \f(CWSGMLS_Element\fR object for the element's parent (if any)."
.IX Item "parent(): Return the SGMLS_Element object for the element's parent (if any)."
.RE
.ie n .IP """parse()""\fR: Return the \f(CW""SGMLS"" object for the current parse."
.el .IP "\f(CWparse()\fR: Return the \f(CWSGMLS\fR object for the current parse."
.IX Item "parse(): Return the SGMLS object for the current parse."
.RE
.ie n .IP """attributes()""\fR: Return a reference to an associative array of attribute names and \f(CW""SGMLS_Attribute"" structures.  Attribute names will be all in upper case."
.el .IP "\f(CWattributes()\fR: Return a reference to an associative array of attribute names and \f(CWSGMLS_Attribute\fR structures.  Attribute names will be all in upper case."
.IX Item "attributes(): Return a reference to an associative array of attribute names and SGMLS_Attribute structures.  Attribute names will be all in upper case."
.RE
.ie n .IP """attribute_names()"": Return an array of strings containing the names of all attributes defined for the current element, in upper case."
.el .IP "\f(CWattribute_names()\fR: Return an array of strings containing the names of all attributes defined for the current element, in upper case."
.IX Item "attribute_names(): Return an array of strings containing the names of all attributes defined for the current element, in upper case."
.RE
.ie n .IP """attribute(ANAME)""\fR: Return the \f(CW""SGMLS_Attribute""\fR structure for the attribute \f(CW""ANAME""."
.el .IP "\f(CWattribute(ANAME)\fR: Return the \f(CWSGMLS_Attribute\fR structure for the attribute \f(CWANAME\fR."
.IX Item "attribute(ANAME): Return the SGMLS_Attribute structure for the attribute ANAME."
.RE
.ie n .IP """set_attribute(ATTRIB)""\fR: Add the \f(CW""SGMLS_Attribute""\fR object \f(CW""ATTRIB"" to the current element, replacing any other attribute structure with the same name."
.el .IP "\f(CWset_attribute(ATTRIB)\fR: Add the \f(CWSGMLS_Attribute\fR object \f(CWATTRIB\fR to the current element, replacing any other attribute structure with the same name."
.IX Item "set_attribute(ATTRIB): Add the SGMLS_Attribute object ATTRIB to the current element, replacing any other attribute structure with the same name."
.RE
.ie n .IP """in(GI)""\fR: Return \f(CW""true""\fR (ie. 1) if the string \f(CW""GI""\fR is the name of the current element's parent, or \f(CW""false"" (ie. 0) if it is not."
.el .IP "\f(CWin(GI)\fR: Return \f(CWtrue\fR (ie. 1) if the string \f(CWGI\fR is the name of the current element's parent, or \f(CWfalse\fR (ie. 0) if it is not."
.IX Item "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."
.RE
.ie n .IP """within(GI)""\fR: Return \f(CW""true""\fR (ie. 1) if the string \f(CW""GI""\fR is the name of any of the ancestors of the current element, or \f(CW""false"" (ie. 0) if it is not."
.el .IP "\f(CWwithin(GI)\fR: Return \f(CWtrue\fR (ie. 1) if the string \f(CWGI\fR is the name of any of the ancestors of the current element, or \f(CWfalse\fR (ie. 0) if it is not."
.IX Item "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."
.RE
.ie n .IP """ext()"": Return a reference to an associative array for user-defined extensions."
.el .IP "\f(CWext()\fR: Return a reference to an associative array for user-defined extensions."
.IX Item "ext(): Return a reference to an associative array for user-defined extensions."
.PD
.ie n .Sh "The ""SGMLS_Attribute"" class"
.el .Sh "The \f(CWSGMLS_Attribute\fP class"
.IX Subsection "The SGMLS_Attribute class"
Each instance of an attribute for each \f(CW\*(C`SGMLS_Element\*(C'\fR is an object
belonging to this class, which recognises the following methods:
.RE
.ie n .IP """name()"": Return a string containing the name of the current attribute, all in upper case."
.el .IP "\f(CWname()\fR: Return a string containing the name of the current attribute, all in upper case."
.IX Item "name(): Return a string containing the name of the current attribute, all in upper case."
.RE
.PD 0
.ie n .IP """type()"": Return a string containing the type of the current attribute, all in upper case.  Available types are ""\s-1IMPLIED\s0"", ""\s-1CDATA\s0"", ""\s-1NOTATION\s0"", ""\s-1ENTITY\s0"", and ""\s-1TOKEN\s0""."
.el .IP "\f(CWtype()\fR: Return a string containing the type of the current attribute, all in upper case.  Available types are ``\s-1IMPLIED\s0'', ``\s-1CDATA\s0'', ``\s-1NOTATION\s0'', ``\s-1ENTITY\s0'', and ``\s-1TOKEN\s0''."
.IX Item "type(): Return a string containing the type of the current attribute, all in upper case.  Available types are IMPLIED, CDATA, NOTATION, ENTITY, and TOKEN."
.RE
.ie n .IP """value()""\fR: Return the value of the current attribute, if any. This will be an empty string if the type is ""\s-1IMPLIED\s0"", a string of some sort if the type is ""\s-1CDATA\s0"" or ""\s-1TOKEN\s0"" (if it is ""\s-1TOKEN\s0"", you may want to split the string into a series of separate tokens), an \f(CW""SGMLS_Notation""\fR object if the type is ""\s-1NOTATION\s0"", or an \f(CW""SGMLS_Entity""\fR object if the type is ""\s-1ENTITY\s0"".  Note that if the value is ""\s-1CDATA\s0"", it will \fInot have escape sequences for 8\-bit characters, record ends, or \s-1SDATA\s0 processed \*(-- that will be your responsibility."
.el .IP "\f(CWvalue()\fR: Return the value of the current attribute, if any. This will be an empty string if the type is ``\s-1IMPLIED\s0'', a string of some sort if the type is ``\s-1CDATA\s0'' or ``\s-1TOKEN\s0'' (if it is ``\s-1TOKEN\s0'', you may want to split the string into a series of separate tokens), an \f(CWSGMLS_Notation\fR object if the type is ``\s-1NOTATION\s0'', or an \f(CWSGMLS_Entity\fR object if the type is ``\s-1ENTITY\s0''.  Note that if the value is ``\s-1CDATA\s0'', it will \fInot\fR have escape sequences for 8\-bit characters, record ends, or \s-1SDATA\s0 processed \*(-- that will be your responsibility."
.IX Item "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."
.RE
.ie n .IP """is_implied()""\fR: Return \f(CW""true""\fR (ie. 1) if the value of the attribute is implied, or \f(CW""false"" (ie. 0) if it is specified in the document."
.el .IP "\f(CWis_implied()\fR: Return \f(CWtrue\fR (ie. 1) if the value of the attribute is implied, or \f(CWfalse\fR (ie. 0) if it is specified in the document."
.IX Item "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."
.RE
.ie n .IP """set_type(TYPE)""\fR: Change the type of the attribute to the string \f(CW""TYPE"" (which should be all in upper case).  Available types are ""\s-1IMPLIED\s0"", ""\s-1CDATA\s0"", ""\s-1NOTATION\s0"", ""\s-1ENTITY\s0"", and ""\s-1TOKEN\s0""."
.el .IP "\f(CWset_type(TYPE)\fR: Change the type of the attribute to the string \f(CWTYPE\fR (which should be all in upper case).  Available types are ``\s-1IMPLIED\s0'', ``\s-1CDATA\s0'', ``\s-1NOTATION\s0'', ``\s-1ENTITY\s0'', and ``\s-1TOKEN\s0''."
.IX Item "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."
.RE
.ie n .IP """set_value(VALUE)""\fR: Change the value of the attribute to \f(CW""VALUE""\fR, which may be a string, an \f(CW""SGMLS_Entity""\fR object, or an \f(CW""SGMLS_Notation"" subject, depending on the attribute's type."
.el .IP "\f(CWset_value(VALUE)\fR: Change the value of the attribute to \f(CWVALUE\fR, which may be a string, an \f(CWSGMLS_Entity\fR object, or an \f(CWSGMLS_Notation\fR subject, depending on the attribute's type."
.IX Item "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."
.RE
.ie n .IP """ext()"": Return a reference to an associative array available for user-defined extensions."
.el .IP "\f(CWext()\fR: Return a reference to an associative array available for user-defined extensions."
.IX Item "ext(): Return a reference to an associative array available for user-defined extensions."
.PD
.ie n .Sh "The ""SGMLS_Notation"" class"
.el .Sh "The \f(CWSGMLS_Notation\fP class"
.IX Subsection "The SGMLS_Notation class"
All declared notations appear as objects belonging to this class,
which recognises the following methods:
.RE
.ie n .IP """name()"": Return a string containing the name of the notation."
.el .IP "\f(CWname()\fR: Return a string containing the name of the notation."
.IX Item "name(): Return a string containing the name of the notation."
.RE
.PD 0
.ie n .IP """sysid()"": Return a string containing the system identifier of the notation, if any."
.el .IP "\f(CWsysid()\fR: Return a string containing the system identifier of the notation, if any."
.IX Item "sysid(): Return a string containing the system identifier of the notation, if any."
.RE
.ie n .IP """pubid()"": Return a string containing the public identifier of the notation, if any."
.el .IP "\f(CWpubid()\fR: Return a string containing the public identifier of the notation, if any."
.IX Item "pubid(): Return a string containing the public identifier of the notation, if any."
.RE
.ie n .IP """ext()"": Return a reference to an associative array available for user-defined extensions."
.el .IP "\f(CWext()\fR: Return a reference to an associative array available for user-defined extensions."
.IX Item "ext(): Return a reference to an associative array available for user-defined extensions."
.PD
.ie n .Sh "The ""SGMLS_Entity"" class"
.el .Sh "The \f(CWSGMLS_Entity\fP class"
.IX Subsection "The SGMLS_Entity class"
All declared entities appear as objects belonging to this class, which
recognises the following methods:
.RE
.ie n .IP """name()"": Return a string containing the name of the entity, in mixed case."
.el .IP "\f(CWname()\fR: Return a string containing the name of the entity, in mixed case."
.IX Item "name(): Return a string containing the name of the entity, in mixed case."
.RE
.PD 0
.ie n .IP """type()""\fR: Return a string containing the type of the entity, in upper case.  Available types are ""\s-1CDATA\s0"", ""\s-1SDATA\s0"", ""\s-1NDATA\s0"" (external entities only), ""\s-1SUBDOC\s0"", ""\s-1PI\s0"" (newer versions of \fBnsgmls\fR only), or ""\s-1TEXT\s0"" (newer versions of \fBnsgmls only)."
.el .IP "\f(CWtype()\fR: Return a string containing the type of the entity, in upper case.  Available types are ``\s-1CDATA\s0'', ``\s-1SDATA\s0'', ``\s-1NDATA\s0'' (external entities only), ``\s-1SUBDOC\s0'', ``\s-1PI\s0'' (newer versions of \fBnsgmls\fR only), or ``\s-1TEXT\s0'' (newer versions of \fBnsgmls\fR only)."
.IX Item "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)."
.RE
.ie n .IP """value()"": Return a string containing the value of the entity, if it is internal."
.el .IP "\f(CWvalue()\fR: Return a string containing the value of the entity, if it is internal."
.IX Item "value(): Return a string containing the value of the entity, if it is internal."
.RE
.ie n .IP """sysid()"": Return a string containing the system identifier of the entity (if any), if it is external."
.el .IP "\f(CWsysid()\fR: Return a string containing the system identifier of the entity (if any), if it is external."
.IX Item "sysid(): Return a string containing the system identifier of the entity (if any), if it is external."
.RE
.ie n .IP """pubid()"": Return a string containing the public identifier of the entity (if any), if it is external."
.el .IP "\f(CWpubid()\fR: Return a string containing the public identifier of the entity (if any), if it is external."
.IX Item "pubid(): Return a string containing the public identifier of the entity (if any), if it is external."
.RE
.ie n .IP """filenames()"": Return an array of strings containing any file names generated from the identifiers, if the entity is external."
.el .IP "\f(CWfilenames()\fR: Return an array of strings containing any file names generated from the identifiers, if the entity is external."
.IX Item "filenames(): Return an array of strings containing any file names generated from the identifiers, if the entity is external."
.RE
.ie n .IP """notation()""\fR: Return the \f(CW""SGMLS_Notation"" object associated with the entity, if it is external."
.el .IP "\f(CWnotation()\fR: Return the \f(CWSGMLS_Notation\fR object associated with the entity, if it is external."
.IX Item "notation(): Return the SGMLS_Notation object associated with the entity, if it is external."
.RE
.ie n .IP """data_attributes()""\fR: Return a reference to an associative array of data attribute names (in upper case) and the associated \f(CW""SGMLS_Attribute"" objects for the current entity."
.el .IP "\f(CWdata_attributes()\fR: Return a reference to an associative array of data attribute names (in upper case) and the associated \f(CWSGMLS_Attribute\fR objects for the current entity."
.IX Item "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."
.RE
.ie n .IP """data_attribute_names()"": Return an array of data attribute names (in upper case) for the current entity."
.el .IP "\f(CWdata_attribute_names()\fR: Return an array of data attribute names (in upper case) for the current entity."
.IX Item "data_attribute_names(): Return an array of data attribute names (in upper case) for the current entity."
.RE
.ie n .IP """data_attribute(ANAME)""\fR: Return the \f(CW""SGMLS_Attribute""\fR object for the data attribute named \f(CW""ANAME"" for the current entity."
.el .IP "\f(CWdata_attribute(ANAME)\fR: Return the \f(CWSGMLS_Attribute\fR object for the data attribute named \f(CWANAME\fR for the current entity."
.IX Item "data_attribute(ANAME): Return the SGMLS_Attribute object for the data attribute named ANAME for the current entity."
.RE
.ie n .IP """set_data_attribute(ATTRIB)""\fR: Add the \f(CW""SGMLS_Attribute""\fR object \f(CW""ATTRIB"" to the current entity, replacing any other data attribute with the same name."
.el .IP "\f(CWset_data_attribute(ATTRIB)\fR: Add the \f(CWSGMLS_Attribute\fR object \f(CWATTRIB\fR to the current entity, replacing any other data attribute with the same name."
.IX Item "set_data_attribute(ATTRIB): Add the SGMLS_Attribute object ATTRIB to the current entity, replacing any other data attribute with the same name."
.RE
.ie n .IP """ext()"": Return a reference to an associative array for user-defined extensions."
.el .IP "\f(CWext()\fR: Return a reference to an associative array for user-defined extensions."
.IX Item "ext(): Return a reference to an associative array for user-defined extensions."
.PD
.SH "AUTHOR AND COPYRIGHT"
.IX Header "AUTHOR AND COPYRIGHT"
Copyright 1994 and 1995 by David Megginson,
\&\f(CW\*(C`dmeggins@aix1.uottawa.ca\*(C'\fR.  Distributed under the terms of the Gnu
General Public License (version 2, 1991) \*(-- see the file \f(CW\*(C`COPYING\*(C'\fR
which is included in the \fB\s-1SGMLS\s0.pm\fR distribution.
.SH "SEE ALSO:"
.IX Header "SEE ALSO:"
SGMLS::Output and SGMLS::Refs.