SGML

API Reference

Locator

Class wrapping a stack of entity reference names and related external system identifiers (file names currently processed, if applicable).

Used to

  • hold the current context line number for error output
  • avoid recursively-referencing entities by checking against a maximum allowed entity nesting level
  • enable cleanup operations on opened files/streams on fatal errors.

Pushing a system identifier establishes a new resolution context for system identifiers.

The stack of entity reference names and system identifiers is applicable to parsed, unparsed, and parameter entities. During prolog parsing, only external parameter entities are pushed, and during content parsing, only general entities (parsed or unparsed) are pushed. In particular, during content parsing, system identifiers are not pushed but only entity names are pushed.

Note unparsed entities can only ever be at the top of the stack.

Also acts as implementation of SAX Locator interface. (used to locate the source location of the most recent SAX event).

Also acts as carrier for the name of the file currently processed (used for file names in error messages and for resolving relative system identifiers).

Constructor

new Locator()

Name Description
clear_open_entities Removes all entity references from the stack of open entities.
get_adjusted_line_number Returns the line number of the most recent document event received via a content, lexical, or declaration handler, compensated for the value of toplevel_line_number_adjust if at top level.
get_line_number Returns the line number of the most recent document event received via a content, lexical, or declaration handler.
get_line_number_at_context Returns the line number at the specified context.
get_number_of_open_entities Returns the number of entries on the entity stack.
get_public_id Returns the public identifier of the source stream of the document being parsed in the current context, if any.
get_set_system_id Returns the system identifier of the source of the document being parsed in the current context, if any (irrespective of whether it is an FSI and refers to a virtual resource).
get_system_id Returns the system identifier of the top-most non-FSI system identifier of the document being parsed in the current context, if any.
is_open_entity_reference Returns whether the given entity reference appears on the stack of open entities.
pop_context Pops the top-most context of the entity reference, system identifier and line number stacks.
pop_entity_reference Pops one entry from the stack of open entities.
push_context Pushes a context with entity reference name *and* system identifier.
push_entity_reference Pushes the supplied entity reference onto the stack of open entities.
reset Resets internal state.
set_line_number (Re-)sets the current-level line number, staying in current context.
set_line_number_adjust Sets line number adjustment to apply to values set via set_line_number().
set_line_number_at_context Sets the line number at the specified context, staying in current context.
set_system_id (Re-)sets the top-level system identifier, unrolling other stacked context info.

Member Details

clear_open_entities()

Removes all entity references from the stack of open entities.

get_adjusted_line_number(): number

Returns the line number of the most recent document event received via a content, lexical, or declaration handler, compensated for the value of toplevel_line_number_adjust if at top level.

Returns

number
get_line_number(): number

Returns the line number of the most recent document event received via a content, lexical, or declaration handler.

Returns

number
get_line_number_at_context(contextno): number

Returns the line number at the specified context.

Parameters

Name Type Description
contextno number

the 1-based stacked context number (with 1 being the bottom-most/main context)

Returns

number

the line number at the specified context number

get_number_of_open_entities(): number

Returns the number of entries on the entity stack.

Returns

number
get_public_id(): string

Returns the public identifier of the source stream of the document being parsed in the current context, if any.

NOT IMPLEMENTED

Returns

string
get_set_system_id(): string

Returns the system identifier of the source of the document being parsed in the current context, if any (irrespective of whether it is an FSI and refers to a virtual resource).

Returns

string
get_system_id(): string

Returns the system identifier of the top-most non-FSI system identifier of the document being parsed in the current context, if any.

Returns

string
is_open_entity_reference(): boolean

Returns whether the given entity reference appears on the stack of open entities.

Returns

boolean
pop_context()

Pops the top-most context of the entity reference, system identifier and line number stacks.

pop_entity_reference()

Pops one entry from the stack of open entities.

push_context(ref, system_id)

Pushes a context with entity reference name and system identifier. Resets line number of new context to 0.

Parameters

Name Type Description
ref string

entity reference name
system_id string

system identifier
push_entity_reference(ref)

Pushes the supplied entity reference onto the stack of open entities.

Parameters

Name Type Description
ref string

entity reference name
reset()

Resets internal state.

set_line_number(lineno)

(Re-)sets the current-level line number, staying in current context.

Parameters

Name Type Description
lineno number
set_line_number_adjust()

Sets line number adjustment to apply to values set via set_line_number(). Does nothing when invoked in a state where more than a single entry is on a context stack.

set_line_number_at_context(contextno, lineno)

Sets the line number at the specified context, staying in current context.

Parameters

Name Type Description
contextno number

the 1-based stacked context number (with 1 being the bottom-most/main context)
lineno number

the line number to set
set_system_id(sysid)

(Re-)sets the top-level system identifier, unrolling other stacked context info.

Parameters

Name Type Description
sysid string