Outputhandler - API Reference

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)

Property Index

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", "text", or "none".
saxeventmanager	Used for pausing/resuming top-level SAX events during serialization of transcluded template instances.
strict_markdown_pl_compat	Whether strict markdown.

Method Index

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:

comment(text)

Parameters

Name	Type	Description
text	string	the character data comprising the comment

See:

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:

endDocument()

Parameters

Type	Description

See:

endDTD()

Parameters

Type	Description

See:

endElement(elmt)

Parameters

Name	Type	Description
elmt

See:

endEntity(name)

Parameters

Name	Type	Description
name	string	name of the data or subdoc entity

See:

endIGNORE()

Parameters

Type	Description

See:

endINCLUDE()

Parameters

Type	Description

See:

endRCDATA()

Parameters

Type	Description

See:

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:

ostream :WritableTextStream

Output stream to serialize markup events to.

output_format :string

Output format to generate; either "html" (the default), "sgml", "xml", "text", 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
text will suppress all markup declarations and delimiters
none will suppress output

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:

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:

startDocument()

Parameters

Type	Description

See:

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:

startElement(elmt, attrs_array, attrs): string|undefined

Parameters

Name	Type	Description
elmt
attrs_array
attrs	string	string serialization of atts

See:

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:

startIGNORE(text)

Parameters

Name	Type	Description
text	string	the characters comprising the IGNORE marked section

See:

startINCLUDE(text)

Parameters

Name	Type	Description
text	string	the characters comprising the INCLUDE marked section

See:

startRCDATA(text)

Parameters

Name	Type	Description
text	string	the characters comprising the RCDATA marked section

See:

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: