perlSGML -- SGML::Entman

## Name

SGML::EntMan - SGML entity manager

## Synopsis

        use SGML::EntMan;
        $entman = new SGML::EntMan
        $entman->read_catalog($file);
        $entman->read_catalog_handle(\*FILEHANDLE);

## Description

SGML::EntMan is a simple SGML entity manager. It is used resolve external entities into Perl filehandles.

In order to resolve entities, SGML Open Catalogs (as defined by SGML Open Technical Resolution 9401:1995 and extensions defined in SP) must be loaded by SGML::EntMan. When the SGML::EntMan module is first loaded, it reads all catalogs specified by the SGML_CATALOG_FILES environent variable. The envariable is a list of file pathnames of catalogs. Each pathname is separated by a '`:`' (or '`;`' under Windows/MSDOS).

All mappings read from the SGML_CATALOG_FILES envariable are are effective across all SGML::EntMan object instances. However, mappings loaded through the read_catalog and read_catalog_handle methods override mappings defined through the SGML_CATALOG_FILES envariable.

## Class Methods

- new

### new

`new SGML::EntMan`

  new instantiates a new SGML::EntMan object.

## Object Methods

- read_catalog
- read_catalog_handle
- open_entity
- open_doctype
- open_public_id
- open_system_id

### read_catalog

`$entman->read_catalog($file)`

  Read the catalog file specified by $file. A 1 is returned on success, and a 0 on failure.

### read_catalog_handle

`$entman->read_catalog_handle(\*FILEHANDLE)`

  Read the catalog specified by FILEHANDLE. A 1 is returned on success, and a 0 on failure.

### open_entity

`$fh = $entman->open_entity($name, $pubid, $sysid)`

  Open a filehandle to the entity specified entity name $name, public identifier $pubid, and/or system identifier $sysid. `undef` is returned if entity could not be resolved, and a warning message is printed to STDERR.

  If $name contains a '`%`' character, it is treated a parameter entity name.

### open_doctype

`$fh = $entman->open_doctype($name, $pubid, $sysid)`

  Open a filehandle to the doctype specified entity name $name, public identifier $pubid, and/or system identifier $sysid. `undef` is returned if doctype could not be resolved, and a warning message is printed to STDERR.

### open_public_id

`$fh = $entman->open_public_id($pubid)`

  Open a filehandle to the entity denoted by the public identifier $pubid. `undef` is returned if public identifier could not be resolved, and a warning message is printed to STDERR.

### open_system_id

`$entman->open_system_id($sysid)`

  Open a filehandle to the entity denoted by the system identifier $sysid. `undef` is returned if system identifier could not be resolved, and a warning message is printed to STDERR.

## Environment Variables

`SGML_CATALOG_FILES`
  List of default catalogs.

## See Also

SGML::DTD, SGML::FSI

perl(1)

## Availability

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

## Author