Vyasa Grammar

This document describes the formal grammar of the Vyasa language. It serves as the authoritative reference for parser implementation and tooling.

Notation

The grammar is specified using Extended Backus-Naur Form (EBNF).

Lexical Structure

/* Basic Character Sets */
Digit          ::= [0-9]
Alpha          ::= [a-zA-Z]
Alphanumeric   ::= Alpha | Digit

/* Identifiers */
/* Used for command names, attribute keys */
Identifier     ::= Alpha ( Alphanumeric | "_" | "-" )*

/* Values */
/* Used for command arguments, unquoted attribute values */
ValueString    ::= ( Alphanumeric | "_" | "." | ":" | "-" | "/" )+

Syntax

Document       ::= Node*

Node           ::= Comment
                 | Command
                 | SegmentBreak
                 | Text

/* Comments */
Comment        ::= LineComment | BlockComment
LineComment    ::= ( "`" (" " | "\t") | "//" ) [^\n]*
BlockComment   ::= "`[" .*? "]"

/* Commands */
Command        ::= "`" Identifier
                   (Space Argument)?
                   Space? Delimiter?
                   Space? Attributes?
                   Space? Children?

Argument       ::= ValueString
Delimiter      ::= ";" Identifier

/* Attributes */
Attributes     ::= "{" AttributeMap "}"
AttributeMap   ::= (Pair (","? Space? Pair)*)? ","?
Pair           ::= (Identifier | QuotedString) Space? "=" Space? Value
Value          ::= QuotedString | NestedValue | ValueString

QuotedString   ::= '"' ( [^"\\] | "\\" . )* '"'
NestedValue    ::= "{" [^}]* "}"

/* Children Block */
Children       ::= "[" Node* Terminator? "]"
Terminator     ::= "]" Identifier  /* Must match the Delimiter Identifier */

/* Structural Elements */
SegmentBreak   ::= "|"

/* Text */
Text           ::= ( [^`|\[\]\\] | EscapedChar )+
EscapedChar    ::= "\\" .

Special Characters & Escaping

Vyasa reserves the characters `, |, [, ], \, {, } for syntax.

• Escaping: Any character can be treated as literal text by prefixing it with a backslash \.

  • Example: \` becomes a literal backtick.
  • Example: \| becomes a literal pipe.

• Robustness: The parser attempts to be robust. If a special character (like ` or ]) is encountered in a context where it does not form a valid command or structure, it is treated as literal text.

  • Example: `( parses as a literal backtick followed by (.

Comments

Vyasa supports both line comments and block comments:

• Line Comments: A line starting with a backtick followed by a space or tab (`), OR double slashes (//).
• Block Comments: Enclosed within `[ and ].

[!TIP] Best Practice: It is highly recommended to use the // syntax exclusively in HTML templates for better visibility. For core content source documents (mula, translation, etc.), stick to the backtick-space (`) comment syntax or block comments to avoid collisions with standard prose formatting.

Vyasa does not have C-style /* */ comments. That sequence is ordinary text (or CSS inside style).

[ and ] are Vyasa structure. A bare `style [ ... ] block closes at the first ], including ] inside CSS attribute selectors or inside CSS /* … ] … */. The packer must fail if the rendered layout looks truncated.

Use a delimited block so ] in CSS is literal (see Delimited Blocks):

`style;css [
  html[data-pub-theme="light"] { color: #333; }
  /* CSS comments are fine here */
]css

// on its own line is still a Vyasa line comment and is stripped from the packed CSS.

Examples

Basic Command

`preface { title="Foreword" } [
  This is the preface text.
]

Command with Argument

`chapter 1 { title="Observation" }

Delimited Blocks (Polymorphic closing)

`div;mybox [
  Content inside the box.
]mybox

Nested Attributes

`set entities {
  krishna={ type="person", bio="The Supreme Personality of Godhead" }
}