perlSGML -- SGML::Parser

## Name

SGML::Parser - SGML instance parser

## Synopsis

      package MyParser;
      use SGML::Parser;
      @ISA = qw( SGML::Parser );

      sub cdata { ... }
      sub char_ref { ... }
      sub comment_decl { ... }
      sub end_tag { ... }
      sub entity_ref { ... }
      sub ignored_data { ... }
      sub marked_sect_close { ... }
      sub marked_sect_open { ... }
      sub parm_entity_ref { ... }
      sub processing_inst { ... }
      sub start_tag { ... }
      sub error { ... }

      $myparser = new MyParser;
      $myparser->parse_data(\*FILEHANDLE);

## Description

SGML::Parser is a simple SGML instance parser; it cannot parse document type declarations. To use the class, you create a derived class of SGML::Parser and redefine the various methods invoked when certain events occur during parsing.

## Class_Methods

The following class methods are defined:

- new

### new

Instantiate a new parser object. The way SGML::Parser is defined, an SGML::Parser object will probably never be directed instantiated, but a derived class will be. The new method is implemented to be reused by derived classes, so redefinition of the method is not required (unless derived class must perform custom initialization beyond what SGML::Parser performs).

## Object Methods

The following lists the methods defined by SGML::Parser that should not be overriden:

- parse_data
- get_line_no
- get_input_label

### parse_data

        $parser->parse_data(
    		$fh,
    		$label,
    		$init_buf,
    		$line_no);

#### Arguments:

$fh (required)
  Reference to the filehandle of the SGML instance to parse.
$label (optional)
  Label for the filehandle being parsed, usually a filename. The name is used for error messages.
$init_buf (optional)
  Initial data to prepend to instance to include in the parse.
$line_no (optional)
  The starting line number. If not defined, numbering starts at 0.

#### Return:

The return value of the method should be `undef`. However, if any data was in the current buffer and parsing was aborted, the return value is the buffer's contents.

#### Description:

parse_data parses an SGML instance. When parsing, the various callback methods are called when the various lexical contructs are encountered.

### get_line_no

        $parser->get_line_no();

#### Arguments:

N/A

#### Return:

The current line number.

#### Description:

Get the current line number. Method useful in callback methods.

### get_input_label

        $parser->get_input_label()

#### Arguments:

N/A

#### Return:

Label string.

#### Description:

Retrieves the label given to the input being parsed. Label is defined when the parse_data method is called. Method useful in callback methods.

## Callback Methods

The following methods are intended to be redefined by a derived class to handle the processing events generated by the parse_data method.

- cdata
- char_ref
- comment_decl
- end_tag
- entity_ref
- error
- ignored_data
- marked_sect_close
- marked_sect_open
- parm_entity_ref
- processing_inst
- start_tag

### cdata

        $parser->cdata($data);

#### Arguments:

$data
  Character data.

#### Return:

N/A

#### Description:

cdata is invoked when character data is encountered. The character data is passed into the method. Multiple lines of character data may generate multiple cdata calls.

### char_ref

        $parser->char_ref($value);

#### Arguments:

$value
  The character number or function name.

#### Return:

N/A

#### Description:

char_ref is invoked when a character reference is encountered. The number/name of the character reference is passed in as an argument.

### comment_decl

        $parser->comment_decl(\@comments);

#### Arguments:

\@comments
  Reference to an array of strings. Each string is the content of each comment block in the declaration.

#### Return:

N/A

#### Description:

comment_decl is called when a comment declaration is parsed. The passed in argument is a reference to an array containing the comment blocks defined in the declaration.

### end_tag

        $parser->end_tag($gi);

#### Arguments:

$gi
  Generic identifier.

#### Return:

N/A

#### Description:

end_tag is called when an end tag is encountered. The generic identifier of the end tag is passed in as an argument. The value may be the empty string if the end tag is a null end tag.

### entity_ref

        $parser->entity_ref($name);

#### Arguments:

$name
  Name of the entity

#### Return:

Any text that should be furthered parse.

#### Description:

entity_ref is called for entity references. The name of the entity is passed in as an argument. If any data is returned by this method, the data will be prepended to the parse buffer and parsed.

### error

        $parser->error(@msg);

#### Arguments:

@msg
  List of strings containing error message

#### Return:

N/A

#### Description:

error is called when any error occurs in parsing. The default implementation is to print the error message (which can be a list of strings) prepending by the class name, input label, and line number the method was called.

### ignored_data

        $parser->ignored_data($data);

#### Arguments:

$data
  Ignored data.

#### Return:

N/A

#### Description:

ignored_data is called for data that is in an IGNORE marked section.

### marked_sect_close

        $parser->marked_sect_close();

#### Arguments:

N/A

#### Return:

N/A

#### Description:

marked_sect_close is called when a marked section close is encountered.

### marked_sect_open

        $parser->marked_sect_open(
    		    $status_keyword,
    		    $status_spec);

#### Arguments:

$status_keyword
  The status keyword.
$status_spec
  Original status specification text.

#### Return:

N/A

#### Description:

marked_sect_open is called when a marked section open is encountered. The $status_keyword argument is the status keyword for the marked section (eg. INCLUDE, IGNORE). The $status_spec argument is the original status specification text. This may be equal to $status_keyword, or contain an parameter entity reference. If a parameter entity reference, the parm_entity_ref method was called to determine the value of the $status_keyword argument.

### parm_entity_ref

        $parser->parm_entity_ref($name);

#### Arguments:

$name
  Name of the parameter entity.

#### Return:

Replacement text.

#### Description:

parm_entity_ref is called to resolve parameter entity references. Currently, it is only invoked if a parameter entity reference is encountered in a marked section open. The return value should contain the value of the parameter entity reference.

### processing_inst

        $parser->processing_inst($data);

#### Arguments:

$data
  Character data within the processing instruction.

#### Return:

N/A

#### Description:

processing_inst is called for processing instructions. $data is the content of the processing instruction.

### start_tag

        $parser->start_tag($gi, $attr_spec);

#### Arguments:

$gi
  Generic identifier
$attr_spec
  Attribute specification list

#### Return:

N/A

#### Description:

start_tag is called for start tags. $gi is the generic indentifier of the start tag. $attr_spec is the attribute specification list string. The SGMLparse_attr_spec function defined in SGML::Util can be used to parse the string into name/value pairs.

## Parser Modes

SGML::Parser has parser modes for properly determining how to analyze the input data. Mode switching is automatic for most cases. However, since SGML parsing rules can changed depending on the content model of elements, callback methods can force a mode change. This mode change will normally be done when encountering a start tag (which invokes the start_tag method) and the element represented by the start tag should parsed like it has CDATA or RCDATA content. The following code example shows how you can change parsing modes:

        sub start_tag {
    	my $this      = shift;
    	my $gi        = uc shift;
    	my $attr_spec = shift;

    	if ($gi eq 'LITERAL-TEXT') {
    	    $this->{'mode'} = $SGML::Parser::ModeCData;
    	} elsif ($gi eq 'EX') {
    	    $this->{'mode'} = $SGML::Parser::ModeRCData;
    	}

    	# ...
        }

The element names are arbitrary, but it shows how you can switch parsing modes via a callback method. SGML::Parser will change the mode when an end tag is encountered.

## See Also

SGML::Util

perl(1)

## Availability

This software is part of the perlSGML package; see (http://www.oac.uci.edu/indiv/ehood/perlSGML.html)

## Author