This is a base class for the parsing of markup texts contained in text layers. More...

#include <markupparser.h>

Inheritance diagram for Mezzanine::UI::MarkupParser:

Collaboration diagram for Mezzanine::UI::MarkupParser:

Public Types
typedef std::list< Character * >	CharacterContainer
	Basic container type for the storage of Character instances used during processing by this class.

typedef CharacterContainer::iterator	CharacterIterator
	Iterator type for Character instances being processed by this class.

typedef CharacterContainer::const_iterator	ConstCharacterIterator
	Const Iterator type for Character instances being processed by this class.

typedef TagContainer::const_iterator	ConstTagIterator
	Const Iterator type for MarkupTag instances stored by this class.

typedef TagVector::const_iterator	ConstTagVecIterator
	Const Iterator type for TokenTagPair instances being processed by this class.

typedef TokenContainer::const_iterator	ConstTokenIterator
	Const Iterator type for TextToken instances being processed by this class.

typedef std::map< String, MarkupTag * >	TagContainer
	Basic container type for the storage of MarkupTag instances by this class.

typedef TagContainer::iterator	TagIterator
	Iterator type for MarkupTag instances stored by this class.

typedef TagVector::iterator	TagVecIterator
	Iterator type for TokenTagPair instances being processed by this class.

typedef std::vector< TokenTagPair >	TagVector
	Basic container type for the storage of TokenTagPair instances used during processing by this class.

typedef std::vector< TextToken * >	TokenContainer
	Basic container type for the storage of TextToken instances used during processing by this class.

typedef TokenContainer::iterator	TokenIterator
	Iterator type for TextToken instances being processed by this class.

typedef std::pair< TagToken , MarkupTag >	TokenTagPair
	An std::pair type used to map a TagToken to the MarkupTag implementation it is calling.

Public Member Functions
	MarkupParser ()
	Class constructor.

virtual	~MarkupParser ()
	Class destructor.

virtual Char8	GetMarkupTagEnd () const =0
	Gets the ID for the character that marks the end of a markup section. More...

virtual Char8	GetMarkupTagStart () const =0
	Gets the ID for the character that marks the start of a markup section. More...

virtual String	GetName () const =0
	Gets the name of this parser implementation. More...

virtual TokenString *	Lex (const String &Source) const
	Converts a string into a series of tokens that can be parsed more readily. More...

virtual CharacterContainer	Parse (const String &Source, const CharacterTraits &InitialTraits, TextLayer *CallingLayer) const
	Processes a string encoded in UTF8 into a list of renderable characters. More...

virtual CharacterContainer	ParseTextTokens (TokenString Tokens, const CharacterTraits &InitialTraits, TextLayer CallingLayer) const
	Processes a collection of text tokens into a list of renderable characters. More...

Protected Member Functions
virtual TextToken *	CreateTagToken (const String &Text) const
	Helper method for creating tag tokens. More...

virtual TextToken *	CreateTextToken (const String &Text) const
	Helper method for creating text tokens. More...

virtual void	GenerateCharactersFromToken (const TextToken Token, TextLayer Layer, const CharacterTraits &Traits, CharacterContainer &Characters) const
	Helper method for converting text tokens into characters. More...

virtual void	Initialize ()=0
	Populates the tag map with the tags recognized by this parser.

virtual void	RegenerateTraits (CharacterTraits &Traits, const TagVector &ActiveTags, TextLayer *Layer) const
	Helper method for regenerating current traits after a tag is disabled. More...

Protected Attributes
TagContainer	Tags
	Map of tags recognized by this parser.

Detailed Description

This is a base class for the parsing of markup texts contained in text layers.

This class implements every aspect of the markup language except for the tags and their functionality. It is expected that tags can be broken down into one of two processes, either they will generate a character, or they will alter the styling used to render an existing range of characters.

The styling and syntax of the markup language is similar (but not identical) to BBCode. Developers can set which glyphs are to be used to mark the start and end of a markup tag. Tags can be start tags, end tags, and individual tags. Individual tags are the character generators. They make the character and are done with influencing any other characters. Start tags and end tags together define a range of characters they are to influence. Use of the forward slash '/' is prohibited unless you are noting an end tag, in which case the slash is to be followed by the tag name (this is case sensitive) and nothing else, within the markup start and end glyphs. An end tag cannot have parameters defined in it, and if any are included they will be parsed as a part of the tag name. A start tag cannot have a forward slash '/'. Instead it must start with the tag name, then a space, and then list the parameter names and values linked by an equals sign '=', and separated by spaces. Spaces between the markup tag start and end glyphs and tag names should be avoided.

Relevant parameters and their possibile values are based on the tag being used, and you should check the markup implemenation for that information. Depending on the number of parameters needed for the tag this markup system supports both short notation, and long notation. Short notation is only supported when there is one parameter, and is implemented as "{tagname}{equals}{value}". For example a sprite could be implemented as "[Sprite=Awesome]" where everything after the equals to the end tag is treated as the value to set, in this case the name of the sprite to be set. In situations like this the value is always given the name "Value" in the NameValuePairMap of parameters that is passed around during parsing. Long notation involves being explicit with the names of values, and is necessary for tags that require multiple parameters. In long notation there should be minimal spaces, used only to separate the tag name and each parameter from each other.

Definition at line 126 of file markupparser.h.

Member Function Documentation

TextToken * Mezzanine::UI::MarkupParser::CreateTagToken ( const String & Text ) const

protectedvirtual

Helper method for creating tag tokens.

Parameters

Text	The text to generate a token for.

Definition at line 71 of file markupparser.cpp.

TextToken * Mezzanine::UI::MarkupParser::CreateTextToken ( const String & Text ) const

protectedvirtual

Helper method for creating text tokens.

Parameters

Text	The text to generate a token for.

Definition at line 65 of file markupparser.cpp.

void Mezzanine::UI::MarkupParser::GenerateCharactersFromToken	(	const TextToken *	Token,
		TextLayer *	Layer,
		const CharacterTraits &	Traits,
		CharacterContainer &	Characters
	)		const

protectedvirtual

Helper method for converting text tokens into characters.

Parameters

Token	The token to be converted into renderable characters.
Layer	A pointer to the layer this is parsing for.
Traits	The character properties to use when generating characters.
Characters	The character container to append any generated characters to.

Todo:: As the CharacterTraits class expands, so does this logic.

Definition at line 144 of file markupparser.cpp.

virtual Char8 Mezzanine::UI::MarkupParser::GetMarkupTagEnd ( ) const

pure virtual

Gets the ID for the character that marks the end of a markup section.

Returns: Returns an Int32 representing the end of a markup section.

Implemented in Mezzanine::UI::DefaultMarkupParser.

virtual Char8 Mezzanine::UI::MarkupParser::GetMarkupTagStart ( ) const

pure virtual

Gets the ID for the character that marks the start of a markup section.

Returns: Returns an Int32 representing the start of a markup section.

Implemented in Mezzanine::UI::DefaultMarkupParser.

virtual String Mezzanine::UI::MarkupParser::GetName ( ) const

pure virtual

Gets the name of this parser implementation.

Returns: Returns a string containing the name of this markup parser implementation.

Implemented in Mezzanine::UI::DefaultMarkupParser.

TokenString * Mezzanine::UI::MarkupParser::Lex ( const String & Source ) const

virtual

Converts a string into a series of tokens that can be parsed more readily.

Warning: This method will naively search each character in the string looking for a match to the character provided by "GetMarkupTagStart()" and/or "GetMarkupTagEnd()". If the provided string is properly formatted UTF-8 this will not cause problems. If the encoding is wrong however, this can lead to detecting tags improperly and rendering the wrong characters. In extreme cases it could try to look for a character that isn't available which will lead to an exception during parsing.

Parameters

Source The source string containing raw text and (maybe) markup tags to convert into tokens.

Returns: Returns a pointer to a TokenString storing all the tokens generated.

Definition at line 315 of file markupparser.cpp.

MarkupParser::CharacterContainer Mezzanine::UI::MarkupParser::Parse	(	const String &	Source,
		const CharacterTraits &	InitialTraits,
		TextLayer *	CallingLayer
	)		const

virtual

Processes a string encoded in UTF8 into a list of renderable characters.

Parameters

Source	The source string containing raw text and (maybe) markup tags to convert into characters.
InitialTraits	The colour, highlight colour, and font characters are to have by default without otherwise being set via markup.
CallingLayer	The TextLayer instance calling this method.

Returns: Returns a list of renderable characters generated by this parser.

Definition at line 186 of file markupparser.cpp.

MarkupParser::CharacterContainer Mezzanine::UI::MarkupParser::ParseTextTokens	(	TokenString *	Tokens,
		const CharacterTraits &	InitialTraits,
		TextLayer *	CallingLayer
	)		const

virtual

Processes a collection of text tokens into a list of renderable characters.

Parameters

Tokens	A TokenString storing all the lex'd text that is to be parsed.
InitialTraits	The colour, highlight colour, and font characters are to have by default without otherwise being set via markup.
CallingLayer	The TextLayer instance calling this method.

Returns: Returns a list of renderable characters generated by this parser.

Definition at line 201 of file markupparser.cpp.

void Mezzanine::UI::MarkupParser::RegenerateTraits	(	CharacterTraits &	Traits,
		const TagVector &	ActiveTags,
		TextLayer *	Layer
	)		const

protectedvirtual

Helper method for regenerating current traits after a tag is disabled.

Parameters

Traits	The character properties to use when generating characters.
ActiveTags	A container of the tags that are to be applied to characters.
Layer	A pointer to the layer this is parsing for.

Definition at line 174 of file markupparser.cpp.

The documentation for this class was generated from the following files:

/home/sqeaky/Code/MezzanineFresh/Mezzanine/src/UI/markupparser.h
/home/sqeaky/Code/MezzanineFresh/Mezzanine/src/UI/markupparser.cpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation