perlSGML -- SGML::SOCat

## Name

SGML::SOCat - SGML Open Catalog parser

## Synopsis

        use SGML::SOCat;
        $soc = new SGML::SOCat "catalog";
        $soc = new SGML::SOCat \*FILEHANDLE;

or

        use SGML::SOCat;
        $soc = new SGML::SOCat;
        $soc->read_file("catalog");
        $soc->read_handle(\*FILEHADNLE);

## Description

SGML::SOCat is an SGML Open Catalog (as defined by SGML Open Technical Resolution 9401:1995 and extensions defined in SP). SGML::SOCat is designed to be used by an entity manager (like SGML::EntMan) for resolving external entities. I.e. SGML::SOCat handles the lexical parsing of the catalogs. It is up to the users of the class to define the applicational behavior.

## Class Methods

- new

### new

`new SGML::SOCat`

  new instantiates a new SGML::SOCat object.

## Object Methods

Some methods of SGML::SOCat may return the following information: base system identifier in effect and/or override flag. Example:

        ($sysid, $base, $override) = $soc->get_public($pubid);

The base system identifier in effect is the base system identifier to use if the system identifier is relative.

The override flag states that the system identifier defined in the catalog should override the explicit system identifier specified in a document.

The following methods are defined:

- read_file
- read_handle

- get_delegate
- get_doctype
- get_document
- get_dtddecl
- get_gen_ent
- get_linktype
- get_parm_ent
- get_public
- get_sgmldecl
- get_system

### read_file

`$soc->read_file($file)`

  read_file reads the catalog designated by the filename passed in. A 1 is returned on success, and a 0 on failure.

### read_handle

`$soc->read_handle(\*FILEHANDLE, $name)`

  read_handle reads the catalog designated by the filehandle passed in. A 1 is returned on success, and a 0 on failure. A reference to a filehandle should passed in to avoid problems with package scoping.

  The second argument is optional. If specified, it is used as the name of the filehandle for error messages.

### get_public

`$soc->get_public($pubid)`

  get_public retrieves the sysid public identifier. In a scalar context, 1 is returned if public identifier has a mapping to a system identifier, else 0 is returned. For example:

          if ($soc->get_public($pubid)) {
      	...
          }

  In an list context, a list of values are returned: system identifier, base system identifier in effect, and override flag. Example:

          ($sysid, $base, $override) = $soc->get_public($pubid);

### get_gen_ent

`$soc->get_gen_ent($gen_entity_name)`

  get_gen_ent retrieves the sysid for a general entity name. In a scalar context, the method returns 1 if there is a catalog entry for the general entity name, else 0 is returned. In a list context, the following list is returned: system identifier, base system identifier in effect, and override flag. Example:

          ($sysid, $base, $override) = $soc->get_gen_ent($name);

### get_parm_ent

`$soc->get_parm_ent($parm_entity_name)`

  get_parm_ent retrieves the sysid for a parameter entity name. In a scalar context, the method returns 1 if there is a catalog entry for the parameter entity name, else 0 is returned. In a list context, the following list is returned: system identifier, base system identifier in effect, and override flag. Example:

          ($sysid, $base, $override) = $soc->get_parm_ent($name);

### get_doctype

`$soc->get_doctype($doc_type_name)`

  get_doctype retrieves the sysid for the entity denoted by a document type name. In a scalar context, the method returns 1 if there is a catalog entry for the document type name, else 0 is returned. In a list context, the following list is returned: system identifier, base system identifier in effect, and override flag. Example:

          ($sysid, $base, $override) = $soc->get_doctype($name);

### get_linktype

`$soc->get_linktype($link_type_name)`

  get_linktype retrieves the sysid for the entity denoted by a link type name. In a scalar context, the method returns 1 if there is a catalog entry for the link type name, else 0 is returned. In a list context, the following list is returned: system identifier, base system identifier in effect, and override flag. Example:

          ($sysid, $base, $override) = $soc->get_linktype($name);

### get_system

`$soc->get_system($sysid)`

  get_system retrieves the sysid for the entity denoted by a system identifier. In a scalar context, the method returns 1 if there is a catalog entry for the system identifier, else 0 is returned. In a list context, the following list is returned: system identifier, base system identifier in effect, and override flag. Example:

          ($sysid, $base, $override) = $soc->get_system($sysid);

### get_sgmldecl

`$soc->get_sgmldecl()`

  get_sgmldecl retrieves the sysid for the SGML declaration. In a scalar context, the method returns 1 if there is a catalog entry for the SGML declaration, else 0 is returned. In a list context, the following list is returned: system identifier and base system identifier in effect. Example:

          ($sysid, $base) = $soc->get_sgmldecl();

### get_dtddecl

`$soc->get_dtddecl($pubid)`

  get_dtddecl retrieves the sysid for for the SGML declaration associated with a doctype external subset public indentifier. In a scalar context, the method returns 1 if there is a catalog entry for the public indentifier, else 0 is returned. In a list context, the following list is returned: system identifier and base system identifier in effect. Example:

          ($sysid, $base) = $soc->get_dtddecl($pubid);

### get_document

`$soc->get_document()`

  get_document retrieves the sysid for the document entity. In a scalar context, the method returns 1 if there is a catalog entry for the document entity, else 0 is returned. In a list context, the following list is returned: system identifier and base system identifier in effect. Example:

          ($sysid, $base) = $soc->get_document();

### get_delegate

`$soc->get_delegate($pubid)`

  get_delegate checks a public identifier to see if a pubid-prefix has been defined that matches the public identifier. If so, then a system identifier of a catalog is returned. The catalog should be used to resolve pubids that match the prefix.

  In a scalar context, the method returns 1 if there is a delegate entry for the public identifier, else 0 is returned. In a list context, the following list is returned: system identifier and base system identifier in effect. The system identifier is for a catalog that should be used to resolve the public identifier. Example:

          ($sysid, $base) = $soc->get_delegate($pubid);

  Since SGML::SOCat does not automatically open the returned catalog to resolve the public identifier, the caller must perform that function. For example:

          ($catalog, $base) = $soc->get_delegate($pubid);
          ## Ignore $base for this example
          $soc_del = new SGML::SOCat $catalog;
          ($sysid, $base) = $soc_del->get_delegate($pubid);

  See SGML::EntMan for external entity resolution that automatically handles delegations.

## Notes

- The total maximun number of errors allowed while parsing is set by the `$SGML::SOCat::MaxErrs` variable. The default value is 10.

- If an error occurs during the instantiation of an SGML::SOCat object (via the new class method), `undef` is returned.

## See Also

SGML::EntMan

perl(1)

## Availability

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

## Author