NME.h File Reference

Detailed Description

Nyctergatis Markup Engine (simple text markup formatting based on Creole).

Author:: Yves Piguet. Copyright 2007-2008, Yves Piguet

See also:: NME Usage

Definition in file NME.h.


Data Structures
struct	NMEPlugin
	Structure for plugins. More...
struct	NMEAutoconvert
	Structure for autoconvert. More...
struct	NMEInterwiki
	Structure for interwiki. More...
struct	NMEOutputFormat
	Structure of output format fragments used by NMEProcess. More...
struct	NMEEncodeCharDict
	Structure for elements of table used by NMEEncodeCharFunDict. More...
Defines
#define	NULL 0
	null pointer
#define	FALSE 0
	false boolean value
#define	TRUE 1
	true boolean value
#define	NMEPluginTableEnd {NULL, kNMEPluginOptDefault, NULL, NULL}
	End-of-table marker for table of plugins.
#define	NMEAutoconvertTableEnd {NULL, NULL}
	End-of-table marker for table of interwikis.
#define	NMEInterwikiTableEnd {NULL, NULL}
	End-of-table marker for table of interwikis.
Typedefs
typedef char	NMEChar
	Character (8-bit; processing possible with compatible charsets like UTF-8 or Shift-JIS).
typedef NMEChar *	NMEText
	Text.
typedef NMEChar const *	NMEConstText
	Constant text.
typedef int	NMEInt
	Integer.
typedef int	NMEBoolean
	Boolean.
typedef struct NMEContextStruct	NMEContext
	Opaque structure for NMEAddString and functions which call it.
typedef NMEErr(*	NMEEncodeCharFun )(NMEConstText src, NMEInt srcLen, NMEInt srcIx, NMEContext context, void *data)
	Callback to encode a single character (typically UTF-8).
typedef NMEWordwrapPermission(*	NMEWordwrapCheckFun )(NMEConstText txt, NMEInt len, NMEInt i, void *data)
	Callback to check valid wordwrap point.
typedef NMEErr(*	NMEEncodeURLFun )(NMEConstText link, NMEInt linkLen, NMEContext context, void data)
	Callback to encode link to a URL (removing or encoding spaces etc.
typedef NMEErr(*	NMECharHookFun )(NMEInt srcIndex, NMEContext context, void data)
	Hook called when a character is added to output; can be used to match text fragments in input and output or add data to output stream.
typedef NMEErr(*	NMEProcessHookFun )(NMEInt level, NMEInt item, NMEBoolean enter, NMEConstText markup, NMEInt srcIndex, NMEContext context, void data)
	Hook called when a construct is entered or exited; can be used to collect information or add data to output stream.
typedef NMEErr(*	NMEPluginFun )(NMEConstText name, NMEInt nameLen, NMEConstText data, NMEInt dataLen, NMEContext context, void userData)
	Callback for plugins.
typedef NMEBoolean(*	NMEAutoconvertFun )(NMEConstText src, NMEInt srcLen, NMEInt i, NMEContext context, void *userData)
	Callback for autoconvert.
typedef NMEInt(*	NMEGetVarFun )(NMEChar name, void *userData)
	Callback for application-specific variables with uppercase name.
Enumerations
enum	NMEErr { kNMEErrOk = 0, kNMEErrNotEnoughMemory, kNMEErrBadMarkup, kNMEErrInternal, kNMEErr1stNMEOpt, kNMEErr1stUser = 10000 }
	Error codes. More...
enum	{ kNMEProcessOptDefault = 0, kNMEProcessOptNoPreAndPost = 0x1, kNMEProcessOptNoH1 = 0x4, kNMEProcessOptH1Num = 0x8, kNMEProcessOptH2Num = 0x10, kNMEProcessOptNoDL = 0x20, kNMEProcessOptNoIndentedPar = 0x40, kNMEProcessOptNoMultilinePar = 0x80, kNMEProcessOptNoEscape = 0x100, kNMEProcessOptNoHRule = 0x200, kNMEProcessOptNoLink = 0x400, kNMEProcessOptNoImage = 0x800, kNMEProcessOptNoTable = 0x1000, kNMEProcessOptNoUnderline = 0x2000, kNMEProcessOptNoMonospace = 0x4000, kNMEProcessOptNoSubSuperscript = 0x8000, kNMEProcessOptNoBold = 0x10000, kNMEProcessOptNoItalic = 0x20000, kNMEProcessOptNoPlugin = 0x40000, kNMEProcessOptVerbatimMono = 0x100000, kNMEProcessOptXRef = 0x200000 }
	Options for NMEProcess (change the way input is parsed). More...
enum	NMEWordwrapPermission { kNMEWordwrapNo = 0, kNMEWordwrapReplaceChar, kNMEWordwrapInsert }
	Wordwrap permission. More...
enum	{ kNMEHookLevelPar = 0, kNMEHookLevelSpan = -1 }
	Special values for argument level of NMEProcessHookFun.
enum	{ kNMEPluginOptDefault = 0, kNMEPluginOptPartialName = 0x1, kNMEPluginOptReparseOutput = 0x2, kNMEPluginOptBetweenPar = 0x4, kNMEPluginOptTripleAngleBrackets = 0x8 }
	Options for NMEPlugin. More...
Functions
NMEErr	NMEEncodeCharFunDict (NMEConstText src, NMEInt srcLen, NMEInt srcIx, NMEContext context, void *data)
	NMEEncodeCharFun function which replaces characters listed in a table with strings.
NMEErr	NMEProcess (NMEConstText nmeText, NMEInt nmeTextLen, NMEText buf, NMEInt bufSize, NMEInt options, NMEConstText eol, NMEOutputFormat const outputFormat, NMEInt fontSize, NMEText output, NMEInt outputLen, NMEInt outputUCS16Len)
	Transform text by interpreting markup.
NMEBoolean	NMEAddString (NMEConstText str, NMEInt strLen, NMEChar ctrlChar, NMEContext *context)
	Add a string to output, converting eol and embedded expressions.
NMEErr	NMECopySource (NMEInt length, NMEBoolean copy, NMEBoolean encodeChar, NMEContext *context)
	Copy or skip source to output.
void	NMEGetTempMemory (NMEContext const context, NMEText addr, NMEInt *len)
	Get temporary memory which can be used in plugin, autolink and hook functions.
void	NMEGetFormat (NMEContext const context, NMEOutputFormat const outputFormat, NMEInt options, NMEInt *fontSize)
	Get current output format and options.
NMEInt	NMECurrentOutputIndex (NMEContext const *context)
	Accessor for output index.
NMEInt	NMECurrentOutputIndexUCS16 (NMEContext const *context)
	Accessor for output index in unicode characters, assuming UTF-8 input.
void	NMECurrentLink (NMEContext const context, NMEInt linkOffset, NMEInt *linkLength)
	Accessor for current link or image (can be called from hook "[[" or "{{"), before any processing by NMEEncodeURLFun.
void	NMECurrentOutput (NMEContext const context, NMEConstText output, NMEInt *outputLength)
	Accessor for output produced until now (provides context which can be used by to decide if a character should be escaped).
NMEConstText	NMECurrentListNesting (NMEContext const *context)
	Accessor for current list nesting as a string of NME markup characters.
Variables
NMEOutputFormat const	NMEOutputFormatText
	Format strings for plain text output.
NMEOutputFormat const	NMEOutputFormatTextCompact
	Format strings for plain text output with fewer blank lines.
NMEOutputFormat const	NMEOutputFormatNull
	Format strings for no output.
NMEOutputFormat const	NMEOutputFormatNME
	Format strings for NME text output.
NMEOutputFormat const	NMEOutputFormatHTML
	Format strings for HTML output.
NMEOutputFormat const	NMEOutputFormatRTF
	Format strings for RTF output.
NMEOutputFormat const	NMEOutputFormatLaTeX
	Format strings for LaTeX output.
NMEOutputFormat const	NMEOutputFormatMan
	Format strings for man page output.

Typedef Documentation

typedef NMEBoolean(* NMEAutoconvertFun)(NMEConstText src, NMEInt srcLen, NMEInt *i, NMEContext *context, void *userData)

Callback for autoconvert.

Parameters:

`[in]`	src	source text with markup
`[in]`	srcLen	source text length
`[in,out]`	i	index in src (token to parse on input, next token on output)
`[in]`	eol	null-terminated string used for end-of-line
`[out]`	dest	result (formatted text)
`[in]`	destSize	maximum size of dest
`[in,out]`	destLen	formatted text length
`[in]`	userData	pointer passed from the parser, as specified in NMEAutoconvert

Returns:: TRUE for conversion, else FALSE

Definition at line 357 of file NME.h.

typedef NMEErr(* NMECharHookFun)(NMEInt srcIndex, NMEContext *context, void *data)

Hook called when a character is added to output; can be used to match text fragments in input and output or add data to output stream.

Parameters:

`[in]`	srcIndex	current index in source code
`[in,out]`	context	current context
`[in,out]`	data	value specific to the callback

Returns:: error code (kNMEErrOk for success)

Definition at line 278 of file NME.h.

typedef NMEErr(* NMEEncodeCharFun)(NMEConstText src, NMEInt srcLen, NMEInt *srcIx, NMEContext *context, void *data)

Callback to encode a single character (typically UTF-8).

Parameters:

`[in]`	src	input characters
`[in]`	srcLen	size of src in bytes
`[in,out]`	srcIx	index in src (should be updated by one character)
`[in]`	dest	address of encoded text
`[in]`	destSize	size of dest
`[in,out]`	destIx	index in dest (should be updated by encoded character length)
`[in,out]`	data	value specific to the callback

Returns:: error code (kNMEErrOk for success)

Definition at line 227 of file NME.h.

typedef NMEErr(* NMEEncodeURLFun)(NMEConstText link, NMEInt linkLen, NMEContext *context, void *data)

Callback to encode link to a URL (removing or encoding spaces etc.

)

Parameters:

`[in]`	link	input characters
`[in]`	linkLen	length of link
`[in]`	dest	address of encoded text
`[in]`	destSize	size of dest
`[in,out]`	destIx	index in dest (should be updated by encoded character length)
`[in,out]`	data	value specific to the callback

Returns:: error code (kNMEErrOk for success)

Definition at line 260 of file NME.h.

typedef NMEInt(* NMEGetVarFun)(NMEChar name, void *userData)

Callback for application-specific variables with uppercase name.

Parameters:

`[in]`	name	variable name ('A'-'Z')
`[in]`	userData	pointer passed to the function, field getVarData in NMEOutputFormat

Returns:: value (default value 0 for undefined variables)

Definition at line 375 of file NME.h.

typedef NMEErr(* NMEPluginFun)(NMEConstText name, NMEInt nameLen, NMEConstText data, NMEInt dataLen, NMEContext *context, void *userData)

Callback for plugins.

Parameters:

`[in]`	name	plugin identifier, such as "calendar"
`[in]`	nameLen	length of name
`[in]`	data	data text
`[in]`	dataLen	length of data
`[in]`	eol	null-terminated string used for end-of-line
`[out]`	dest	result (formatted text)
`[in]`	destSize	maximum size of dest
`[out]`	destLen	formatted text length
`[in]`	userData	pointer passed from the parser, as specified in NMEPlugin
`[in,out]`	data	value specific to the callback

Returns:: error code (kNMEErrOk for success)

Definition at line 316 of file NME.h.

typedef NMEErr(* NMEProcessHookFun)(NMEInt level, NMEInt item, NMEBoolean enter, NMEConstText markup, NMEInt srcIndex, NMEContext *context, void *data)

Hook called when a construct is entered or exited; can be used to collect information or add data to output stream.

Parameters:

`[in]`	level	heading or list level (1 = topmost, par=kNMEHookLevelPar, span=kNMEHookLevelSpan)
`[in]`	item	list item or heading counter
`[in]`	enter	TRUE when entering construct, FALSE when exiting
`[in]`	markup	null-terminated string for initial markup ("p" for par, "*" for unnumbered list of any level, "//" for italic, "{{{" for preformatted)
`[in]`	srcIndex	current index in source code
`[in,out]`	context	current context
`[in,out]`	data	value specific to the callback

Returns:: error code (kNMEErrOk for success)

Definition at line 295 of file NME.h.

typedef NMEWordwrapPermission(* NMEWordwrapCheckFun)(NMEConstText txt, NMEInt len, NMEInt i, void *data)

Callback to check valid wordwrap point.

Parameters:

`[in]`	txt	output text
`[in]`	len	length of output text in bytes
`[in]`	i	line break to check (space to be removed or before char to push to next line)
`[in,out]`	data	value specific to the callback

Returns:: wordwrap kind (kNMEWordwrapNo if not permitted here)

Definition at line 247 of file NME.h.

Enumeration Type Documentation

anonymous enum

Options for NMEProcess (change the way input is parsed).

Enumerator:

kNMEProcessOptDefault	default options
kNMEProcessOptNoPreAndPost	no doc header and trailer
kNMEProcessOptNoH1	no heading level 1 (replaced by level 2)
kNMEProcessOptH1Num	numbering of heading level 1
kNMEProcessOptH2Num	numbering of heading level 2
kNMEProcessOptNoDL	no definition list
kNMEProcessOptNoIndentedPar	no indented paragraph
kNMEProcessOptNoMultilinePar	line breaks are paragraph separators
kNMEProcessOptNoEscape	no escape character
kNMEProcessOptNoHRule	no horizontal rule
kNMEProcessOptNoLink	no hypertext link
kNMEProcessOptNoImage	no image
kNMEProcessOptNoTable	no table
kNMEProcessOptNoUnderline	no underline
kNMEProcessOptNoMonospace	no monospace
kNMEProcessOptNoSubSuperscript	no subscript or superscript
kNMEProcessOptNoBold	no bold
kNMEProcessOptNoItalic	no italic
kNMEProcessOptNoPlugin	no plugin
kNMEProcessOptVerbatimMono	inline verbatim is rendered in monospace
kNMEProcessOptXRef	headings have hyperlink target labels

Definition at line 188 of file NME.h.

anonymous enum

Options for NMEPlugin.

Enumerator:

kNMEPluginOptPartialName	if set, name must match the beginning of what's found in NME input; if FALSE, name must match the whole word following "<<"
kNMEPluginOptReparseOutput	if set, output should be parsed again
kNMEPluginOptBetweenPar	if set, forced outside paragraphs or lists
kNMEPluginOptTripleAngleBrackets	if set, used with triple angle brackets (placeholders)

Definition at line 322 of file NME.h.

enum NMEErr

Error codes.

Enumerator:

kNMEErrOk	no error
kNMEErrNotEnoughMemory	not enough memory
kNMEErrBadMarkup	bad markup (can be considered as OK)
kNMEErrInternal	internal error (should never occur)
kNMEErr1stNMEOpt	first error code used by NME options (plugins etc.)
kNMEErr1stUser	first error code reserved to user for plugins etc.

Definition at line 175 of file NME.h.

enum NMEWordwrapPermission

Wordwrap permission.

Enumerator:

kNMEWordwrapNo	wordwrap not permitted here
kNMEWordwrapReplaceChar	linebreak should replace character (typically a space)
kNMEWordwrapInsert	linebreak should be inserted

Definition at line 232 of file NME.h.

Function Documentation

NMEBoolean NMEAddString	(	NMEConstText	str,
		NMEInt	strLen,
		NMEChar	ctrlChar,
		NMEContext *	context
	)

Add a string to output, converting eol and embedded expressions.

Parameters:

`[in]`	str	null-terminated string to append
`[in]`	strLen	length of str, or -1 for null-terminated string
`[in]`	ctrlChar	control character for embedded expressions
`[in,out]`	context	current context

Returns:: TRUE for success, FALSE for failure (not enough space)

Definition at line 345 of file NME.c.

NMEErr NMECopySource	(	NMEInt	length,
		NMEBoolean	copy,
		NMEBoolean	encodeChar,
		NMEContext *	context
	)

Copy or skip source to output.

Parameters:

`[in]`	length	number of bytes of source to consume
`[in]`	copy	TRUE to copy source, FALSE to skip
`[in]`	encodeChar	TRUE to use encodeCharFun, FALSE for plain copy
`[in,out]`	context	current context

Returns:: TRUE for success, FALSE for failure (not enough space)

Definition at line 488 of file NME.c.

void NMECurrentLink	(	NMEContext const *	context,
		NMEInt *	linkOffset,
		NMEInt *	linkLength
	)

Accessor for current link or image (can be called from hook "[[" or "{{"), before any processing by NMEEncodeURLFun.

Parameters:

`[in]`	context	current context
`[out]`	linkOffset	offset of link in NME source text
`[out]`	linkLength	length of link

Definition at line 3771 of file NME.c.

NMEConstText NMECurrentListNesting ( NMEContext const * context )

Accessor for current list nesting as a string of NME markup characters.

Parameters:

[in] context current context

Returns:: string (constant, valid until next call)

Definition at line 3787 of file NME.c.

void NMECurrentOutput	(	NMEContext const *	context,
		NMEConstText *	output,
		NMEInt *	outputLength
	)

Accessor for output produced until now (provides context which can be used by to decide if a character should be escaped).

Parameters:

`[in]`	context	current context
`[out]`	output	address of output (not provided if NULL)
`[out]`	outputLength	current length of output in bytes (not provided if NULL)

Definition at line 3778 of file NME.c.

NMEInt NMECurrentOutputIndex ( NMEContext const * context )

Accessor for output index.

Parameters:

[in] context current context

Returns:: current output index

Definition at line 3761 of file NME.c.

NMEInt NMECurrentOutputIndexUCS16 ( NMEContext const * context )

Accessor for output index in unicode characters, assuming UTF-8 input.

Parameters:

[in] context current context

Returns:: current output index

Definition at line 3766 of file NME.c.

NMEErr NMEEncodeCharFunDict	(	NMEConstText	src,
		NMEInt	srcLen,
		NMEInt *	srcIx,
		NMEContext *	context,
		void *	data
	)

NMEEncodeCharFun function which replaces characters listed in a table with strings.

Characters not in the table are copied unmodified. Its address should be stored in the encodeCharFun field of NMEOutputFormat, while the adresse of a table of type NMEEncodeCharDict[] ending with {0,NULL} should be stored in the encodeCharData field.

Parameters:

`[in]`	src	input characters
`[in]`	srcLen	size of src in bytes
`[in,out]`	srcIx	index in src (updated by one character)
`[in,out]`	context	context for embedded expressions
`[in,out]`	data	address of substitution table, of type NMEEncodeCharDict[]

Returns:: error code (kNMEErrOk for success)

See also:: NMEOutputFormat

Definition at line 635 of file NME.c.

void NMEGetFormat	(	NMEContext const *	context,
		NMEOutputFormat const **	outputFormat,
		NMEInt *	options,
		NMEInt *	fontSize
	)

Get current output format and options.

Parameters:

`[in]`	context	current context
`[out]`	outputFormat	output format (not set if pointer is null)
`[out]`	options	kNMEProcessOptDefault or sum of options
`[out]`	fontSize	font size (not set if pointer is null)

Definition at line 3748 of file NME.c.

void NMEGetTempMemory	(	NMEContext const *	context,
		NMEText *	addr,
		NMEInt *	len
	)

Get temporary memory which can be used in plugin, autolink and hook functions.

Parameters:

`[in]`	context	current context
`[out]`	addr	memory address
`[out]`	len	number of bytes

Definition at line 3740 of file NME.c.

NMEErr NMEProcess	(	NMEConstText	nmeText,
		NMEInt	nmeTextLen,
		NMEText	buf,
		NMEInt	bufSize,
		NMEInt	options,
		NMEConstText	eol,
		NMEOutputFormat const *	outputFormat,
		NMEInt	fontSize,
		NMEText *	output,
		NMEInt *	outputLen,
		NMEInt *	outputUCS16Len
	)

Transform text by interpreting markup.

This is the main and only required extern function of the parser.

Parameters:

`[in]`	nmeText	source text with markup
`[in]`	nmeTextLen	source text length
`[out]`	buf	buffer used during conversion
`[in]`	bufSize	size of buf
`[in]`	options	kNMEProcessOptDefault or sum of options
`[in]`	eol	null-terminated string used for end-of-line
`[in]`	outputFormat	format strings, or NULL for default (NMEOutputFormatText)
`[in]`	fontSize	font size of plain text in points (nonpositive -> default)
`[out]`	output	formatted text (in buf), followed by null byte
`[out]`	outputLen	formatted text length, excluding final null byte
`[out]`	outputUCS16Len	formatted text length in 16-bit unicode characters assuming input is in UTF-8, excluding final null byte (may be NULL)

Returns:: error code (kNMEErrOk for success)

Bug:: Links are copied verbatim, without processing the escape character (this means that pipes and double-closing-brackets cannot be included in a link).

Definition at line 2604 of file NME.c.

Variable Documentation

NMEOutputFormat const NMEOutputFormatMan

Format strings for man page output.

Bug:: NMEOutputFormatMan needs more work or it will be discarded from the main code

Definition at line 1292 of file NME.c.

NME.h File Reference

Detailed Description

Data Structures

Defines

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation