Tagup 1.0.0 Specification (Draft)

CC0 1.0 by Garrett Fairburn

Contents

1 Overview


1.1 Definitions
  • The Language - Tagup
  • The Document - this specification
  • Tag - the basic markup element of The Language
  • Argument - a value supplied to a Tag
  • Named Argument - an Argument in the form of a key-value pair
  • Positional Argument - an Argument in the form of a value
  • Identifier - the name of a Tag or Named Argument key

1.2 Tag Syntax

The Language has two "primitive" types: plain text to be literally rendered and embedded Tags. Tags come in two varieties: builtin Tags and user Tags, both of which use the following general syntax:

[<Identifier>\<Argument>\<Argument>\...]
or
[<Identifier> <Argument>\<Argument>\...]

A Tag is uniquely identified by its "Identifier," which must be a 1 to 32 character sequence consisting of lowercase alphabetic characters and dashes. This Identifier must not start or end with a dash.

Note: Identifiers are not limited to the English alphabet.

Following the Identifier, a Tag may optionally have one or more Arguments. These arguments are delimited by a single \ (backslash) character. The Identifier and the first Argument may optionally be delimited by whitespace instead of a backslash character.

There are two types of Arguments: Named and Positional. Tags may be called with any combination of Named and Positional Arguments.

1.2.1 Named Arguments

<Identifier>\\<value>

Named Arguments are key-value pairs delimited by double backslashes. "value" may be an arbitrary mixture of plain text and embedded Tags. Named Arguments are uniquely identified by their "Identifier" (key).

1.2.2 Positional Arguments

Positional Arguments are composed of an arbitrary mixture of plain text and embedded Tags. They are uniquely identified by their one-indexed position.

Note: Named Arguments are not factored into the calculated position of Positional Arguments.

1.3 Whitespace

2 Builtin Tags


Builtin Tags, or just "builtins" for short, are special markup Tags provided by The Language that are used for templating. They are distinguished from user Tags by a \ (backslash) prepended to their Identifiers.

2.1 Escape Sequences
Due to the special meaning of the [ (open bracket), ] (close bracket), and \ (backslash) characters, The Language provides three escape sequence builtins.

2.1.1 Open Escape

[\o]

The open escape sequence renders to a literal [ (open bracket) character.

2.1.2 Close Escape

[\c]

The close escape sequence renders to a literal ] (close bracket) character.

2.1.3 Slash Escape

[\s]

The slash escape sequence renders to a literal \ (backslash) character.

2.2 Argument Substitution
The Language provides special placeholder syntax that Tags may use to substitute in the values of the Arguments they were passed. This builtin has two forms.

2.2.1 Named Substitution

[\\<Identifier>]

Any instance of named substitution renders to the value of the Named Argument whose key is specified by "Identifier."

2.2.2 Positional Substitution

[\\<index>]

Any instance of positional substitution renders to the value of the Positional Argument whose one-indexed position is specified by "index."

2.3 Conditionals
To help make user Tags more versatile, The Language provides two similar builtins called conditionals. These builtin are used to conditionally render blocks of markup based on the presence or absence of Arguments.

2.3.1 Named Conditional

[\if\<Identifier>\<true block>]
or
[\if\<Identifier>\<true block>\<false block>]

The named conditional tests for the presence of a Named Argument whose key is specified by "Identifier." If present, then the contents of "true block" will be rendered.

In the first form, if the Named Argument is not present, then nothing is rendered. In the second form, if the Named Argument is not present, then the contents of "false block" are rendered.

2.3.2 Positional Conditional

[\if\<index>\<true block>]
or
[\if\<index>\<true block>\<false block>]

The positional conditional tests for the presence of a Positional Argument whose one-indexed position is specified by "index." If present, then the contents of "true block" will be rendered.

In the first form, if the Positional Argument is not present, then nothing is rendered. In the second form, if the Positional Argument is not present, then the contents of "false block" are rendered.

Note: This conditional can be thought of as testing the number of Positional Arguments a Tag receives.

2.4 Loops

The final builtin that Then Language provides is the positional loop, which is used to iterate over the Positional Arguments a Tag receives.

[loop\<iteration block>]
or
[loop\<iteration block>\<empty block>]

For each Positional Argument, the positional loop will duplicate the contents "iteration block" and provide access to a special loop item builtin limited to the scope of that iteration block.

[\item]

Any instance of loop item within the iteration block renders to the value of the current Positional Argument.

In the first form of the Positional Loop, if no Positional Arguments are present, then nothing is rendered. In the second form of the Positional Loop, if no Positional Arguments are present, then the contents of "empty block" are rendered.

Note: Positional Loops must not be nested.

3 User Tags


#tagup