Class serializing received SAX events to an output stream according to a configured output markup language (SGML, HTML, or XML).

Delegates to a registered EntityManager for setup and creation of nested SGML processing contexts for SGML template processing.

Implements DocumentHandler, LexicalHandler, DTDHandler.

Constructor

new Outputhandler(ostream, entitymanager, markupdefinitions)

Parameters

Name Type Description
ostream WritableTextStream

Output stream to serialize markup events to

entitymanager Entitymanager

entitymanager callbacks to use for pausing and resuming received markup events while processing subcontexts/templates, if necessary

markupdefinitions Markupdefinitions

Markupdefinitions used to determine whether to suppress end-element tags (ie. on EMPTY declared content)

Name Description
completioncallback Callback to invoke after serialization completed.
dtd_handling Option causing inclusion, suppression or generation of DTDs and/or XML declarations in output.
entitymanager Entitymanager callbacks to use for pausing and resuming received markup events.
keep_trailing_codeblock_newlines Whether to output trailing newline characters of code blocks as-is.
markupdefinitions Markupdefinitions used to determine whether to suppress end-element tags (ie.
ostream Output stream to serialize markup events to.
output_format Output format to generate; either "html" (the default), "sgml", "xml", or "none".
saxeventmanager Used for pausing/resuming top-level SAX events during serialization of transcluded template instances.
strict_markdown_pl_compat Whether strict markdown.

Name Description
characters
comment
configure Configuration method.
end_temp
endCDATA
endDocument
endDTD
endElement
endEntity
endIGNORE
endINCLUDE
endRCDATA
notationDecl
processingInstruction
reset Resets internal state.
set_output No-op implementation of set_output function to satisfy awkcc's static type checking of simpletemplateprocessor.
start_temp
startCDATA
startDocument
startDTD
startElement
startEntity
startIGNORE
startINCLUDE
startRCDATA
unparsedEntityDecl

Member Details

characters(text)

Parameters

Name Type Description
text string

the character data

See:
DocumentHandler#characters
comment(text)

Parameters

Name Type Description
text string

the character data comprising the comment

See:
LexicalHandler#comment
completioncallback :Completioncallback

Callback to invoke after serialization completed.

Is called on receiving end_document(), after the last I/O operation been emitted.

Per default, a no-op completion callback is set up which should be overwritten for asynchronous operation.

configure(args)

Configuration method.

Parameters

Name Type Description
args Object.<string, string>

Map of configuration settings

dtd_handling :string

Option causing inclusion, suppression or generation of DTDs and/or XML declarations in output.

Used to suppress serialization of DTD and XML declaration output in nested SGML processing contexts. Can also be useful for external software that can't deal well with DTDs having an internal or external subsets.

preserve (default) : copy DTD and XML declaration received via startDTD() as-is to output

omit : don't output declaration sets and/or XML declarations; used for generating fragments either from top-level processing contexts (such as generating HTML from markdown), or from nested processing contexts

force : always output a fixed, preconfigured ยด<!doctype ...>string, ignoring events received viastartDTD()' for output; only used in conjunction with output_format == 'html'

preserve_doctype (deprecated) : for output_format != 'xml': include doctype, but not internal subset, in output, if present in input : for output_format == 'xml': include XML declaration and doctype, but not internal subset, in output, if present in input

generate_doctype (deprecated; don't use) : like preserve_doctype, but generate a doctype from document element if missing in input

  • for output format html and doctype_handling force, the generated doctype will be the fixed string <!doctype html>; the internal subset, when present, won't be copied to the output
  • moreover, output_format==html and dtd_handling==force will make Outputhandler defer serialization of <!doctype html> until the first content event is encountered; this setting will suppress any output until after successfull SGML prolog validation and delivery of the first content event; this feature is aimed at HTTP delivery scenarios where unbounded output buffering of generated response bodies is undesired, yet a response status must be transmitted before content (and can't be changed afterwards): for this use case, when SGML prolog parsing and validation has completed successfully, a HTTP response status in the 2xx range can be transmitted with a sufficient degree of confidence that the response will be generated successfully (typically, actual content generation success depends on prior out-of-band enforcement of contraints expressed in markup declarations, ie. on appropriate DTDs)
  • if XHTML output is desired, use output_format xml and supply (the equivalent of) <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> via startDTD(), potentially including an internal subset where applicable.
end_temp() deprecated
endCDATA()

Parameters

Type Description
See:
LexicalHandler#endCDATA
endDocument()

Parameters

Type Description
See:
DocumentHandler#endDocument
endDTD()

Parameters

Type Description
See:
LexicalHandler#endDTD
endElement(elmt)

Parameters

Name Type Description
elmt
See:
DocumentHandler#endElement
endEntity(name)

Parameters

Name Type Description
name string

name of the data or subdoc entity

See:
LexicalHandler#endEntity
endIGNORE()

Parameters

Type Description
See:
LexicalHandler#endIGNORE
endINCLUDE()

Parameters

Type Description
See:
LexicalHandler#endINCLUDE
endRCDATA()

Parameters

Type Description
See:
LexicalHandler#endRCDATA
entitymanager :Entitymanager

Entitymanager callbacks to use for pausing and resuming received markup events.

keep_trailing_codeblock_newlines :string

Whether to output trailing newline characters of code blocks as-is.

Whether to output trailing newline characters of code blocks as-is rather than collapsing mutliple newline to a single one, or perform markdown.pl compatible processing as of strict_markdown_pl_compat).

markupdefinitions :Markupdefinitions

Markupdefinitions used to determine whether to suppress end-element tags (ie. on EMPTY declared content).

notationDecl(name, pubid, sysid)

Parameters

Name Type Description
name string

the name of the declared notation

pubid string

the declared public identifier, if any

sysid string

the declared system identifier, if any

See:
DTDHandler#notationDecl
ostream :WritableTextStream

Output stream to serialize markup events to.

output_format :string

Output format to generate; either "html" (the default), "sgml", "xml", or "none".

  • xml will serialize all start- and end-element tags as received.
  • html will suppress end-element tags on the meta, link img, hr, and br elements
  • sgml will suppress emitting end-element tags on elements which are declared EMPTY in the supplied markupdefinitions metadata
  • none will suppress output

See also notes on dtd_handling.

processingInstruction(name, data)

Parameters

Name Type Description
name string

part of the processing instruction code text up to (not including) an initial whitespace character (or the complete code text of the processing instruction, if it doesn't contain whitespace)

data string

part of the processing instruction code text following after initial whitespace, if any

See:
DocumentHandler#processingInstruction
reset()

Resets internal state.

saxeventmanager :Saxeventmanager

Used for pausing/resuming top-level SAX events during serialization of transcluded template instances.

Outputhandler calls pause_events() before serializing a nested instance and resume_events() must ultimately called by a "nested" outputhandler handling output of the transcluded instance; the nested outputhandler receives a callback to call via it's completioncallback saxeventmanager is injected by "named property" mechanism (for awk impl) (see chain's recordmanager)

set_output()

No-op implementation of set_output function to satisfy awkcc's static type checking of simpletemplateprocessor.set_output().

start_temp() deprecated
startCDATA(text)

Parameters

Name Type Description
text string

the characters comprising the CDATA marked section including surrounding "" markers; note that in standard SAX this argument isn't delivered (only begin an end of CDATA sections are demarcated) whereas character data in marked sections is delivered both via startCDATA() and with characters() events wrapped by start/endCDATA() calls

See:
LexicalHandler#startCDATA
startDocument()

Parameters

Type Description
See:
DocumentHandler#startDocument
startDTD(name, publicid, systemid, xmltext)

Parameters

Name Type Description
name string

the name of the declaration set

publicid string

the public identifier of the declaration set, if any

systemid string

the system identifier of the declaration set, if any

xmltext
See:
LexicalHandler#startDTD
startElement(elmt, attrs_array, attrs): string|undefined

Parameters

Name Type Description
elmt
attrs_array
attrs string

string serialization of atts

See:
DocumentHandler#startElement

Returns

string | undefined

the return value can be used to pass back custom info to the caller

startEntity(name, elmt)

Parameters

Name Type Description
name string

name of the data or subdoc entity

elmt string

(optional) name of the element on which the entity was specified, if it was due to a linkhandler-expanded #CONREF entity

See:
LexicalHandler#startEntity
startIGNORE(text)

Parameters

Name Type Description
text string

the characters comprising the IGNORE marked section

See:
LexicalHandler#startIGNORE
startINCLUDE(text)

Parameters

Name Type Description
text string

the characters comprising the INCLUDE marked section

See:
LexicalHandler#startINCLUDE
startRCDATA(text)

Parameters

Name Type Description
text string

the characters comprising the RCDATA marked section

See:
LexicalHandler#startRCDATA
strict_markdown_pl_compat

Whether strict markdown.pl compatibility for HTML output serialization is desired. Influences how newlines in code spans and blocks are handled.

unparsedEntityDecl(name, pubid, sysid, notation_name, data_attributes)

Parameters

Name Type Description
name string

the name of the entity being declared

pubid string

the declared public identifier, if any

sysid string

the declared system identifier, if any

notation_name
data_attributes
See:
DTDHandler#unparsedEntityDecl