hoglet uses tags to markup certain sections of a document. A tag, in a similar way to XML and HTML, is just a text name with leading and trailing delimiters. Examples of tags are:

• java
• javadoc
• section

The start and end tags in hoglet are the same, that is to markup a section you use the same tag, for example:
It is possible to also use the close prefix delimiter to explicitly indicate a close tag, i.e. [/java]. The end tag is optional and should only be used when you want to indicate that the tag has some content. For example: [link /index.html /]. Since the start and end tags can potentially be the same, it means that direct nesting of a tag within itself can not be performed, for example: [java][java][java][java] would not lead to nesting.

Each fully formed tag found will be converted to an instance of: org.hoglet.data.Tag. Any nested tags within a tag will be added as child Tag instances to the tag, the parent will also be set (if there is one).

For example:
Will be converted to a Tag with name a, it will have a child b which will have a child c. In essence a tree of tags is created.

Any text that is outside of a tag will be also be converted to a Tag instance and the getContent() method will return the associated text. Content tags are also known as default tags and the getName() method will return null for those tags. So from the above, the a tag will actually contain three child Tags, the first will be a default tag that contains the whitespace to the start of the b tag, the second will be b tag and the third will be another default tag that contains the text after the closing b tag.

The delimiters used are configurable in hoglet. Each delimiter is a single character, there is also an escape character that can be used when a delimiter should be included.

hoglet has the following delimiters:

• Open tag - for example [.
• Close tag - for example ]
• Close prefix - for example /
• Tag/Options separator - for example a whitespace character.
• Option separator - for example ,
• Option Name/Value separator - for example =
• Escape - for example \

These delimiters are represented and stored in class org.hoglet.ParserCharset. hoglet also has a set of standard delimiters which are:

• Open tag - [.
• Close tag - ]
• Tag/Options separator - a whitespace character.
• Option separator - ,
• Option Name/Value separator - =
• Escape - \

See also: XML Configured Processor, Tag Handlers

Each tag can have a number of options defined. These are name/value pairs that are passed to the handler and can provide either extra information about how the tag should be processed, or can be the information that should be processed. The decision is up to the handler implementation. If only a single value is given for an option then this is taken as the value and the name is defaulted to an integer, the integers start at 1 and are given to each option that does not have an explicit name provided.

The options are separated from the tag name by the Tag/Options separator. The options are separated by the Option separator and the name/value pairs by the Option Name/Value separator.

Using the standard delimiters a typical tag (using the standard delimiters) with it's options would be:
In this case the javadoc tag is passed three options:

• hoglet - because it has no name associated with it, the name will be defaulted to 1.
• org.hoglet.Processor - no name, so name will be defaulted to 2.
• y - with a name lastid.

Note: option names are trimmed of whitespace but values are not!

Tag processing is performed by the org.hoglet.Processor class. Method: process(java.io.Reader, org.hoglet.ParserCharset) is used to tag a stream of characters and process them.

The Processor class is initially configured with a map of Handlers that is a set of name (string) to TagHandler mappings. That is each tag found by hoglet should have an associated mapping to a tag handler instance. When hoglet encounters a tag it will create a org.hoglet.data.Tag instance and pass it to the convert(org.hoglet.data.Tag, java.lang.String) method for processing. The handler should then work on the tag and return a string that hoglet will then replace in the output for the tag.

For example, a common mapping would be:

If some text within hoglet does not have an explicit tag around it then a default tag is created to hold the text. Similarly any plain text within a tag is placed into a default tag. A default tag is a Tag instance where the name is null. When hoglet processes this tag it will look for a tag handler that maps to tag: _default, if one is found then the tag handler is used to process the text, in this way you can customize how chunks of text are handled.

If there is no tag handler that maps to the _default tag then hoglet will perform it's default processing on the text, which is:

• If the text starts with a new line then the new line is trimmed from the front, unless the character after that is also a new line (i.e. a blank line is present at the front).
• Replace new line characters with <br />.