From 3de69aed9b5f36d76382fe22d748a6fc478e66f8 Mon Sep 17 00:00:00 2001
From: Miraculous Ladybugreport <3642643+PeyTy@users.noreply.github.com>
Date: Thu, 23 May 2024 12:12:48 +0300
Subject: [PATCH] Update specification.md

---
 docs/specification.md | 53 +++++++++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 7 deletions(-)

diff --git a/docs/specification.md b/docs/specification.md
index 1439bfe..7fa0118 100644
--- a/docs/specification.md
+++ b/docs/specification.md
@@ -44,9 +44,16 @@ CRLF aka `\r\n` line ending format is considered to be valid.
 
 Having a semicolon `;` is always syntax error.
 
+Shebang example:
+
+```sh
+#!/shebang
+... code ...
+```
+
 # Grammar
 
-Here is a simplified grammar overview in a normalized (Backus–Naur) form. Compiler follows this rules list exactly, where possible, but may unify or split some elements to ease parsing. Use it to make your own parsers, syntax highlighters, macro preprocessors or compilers.
+Here is a simplified grammar overview in a normalized form. Compiler follows this rules list exactly, where possible, but may unify or split some elements to ease parsing. Use it to make your own parsers, syntax highlighters, macro preprocessor or compilers.
 
 ## Keywords
 
@@ -103,22 +110,54 @@ Node = /[a-z]/
 
 ## Grammar
 
+### Module
+
 Module is defined as follows:
 
-```ts
-Module = `\239\187\191`? (`#!shebang` ~ `\r`? ~ `\n`? )? (Expression | Comment)*
+```js
+Module = `\239\187\191`? (`#!shebang` ~ `\r`? ~ `\n`? )? (TopLevel | Expression)*
 ```
 
-Syntax tree definition:
+### Top-Level Patterns
+
+Those patterns may be present at any token boundary.
+
+```js
+TopLevel = (IfDef | Comment)*
+```
+
+#### Conditional Compilation
+
+Operates at the token level and may split expressions.
+
+```js
+Tokens = TopLevel? ...
+IfDef = `#if` Condition Tokens ElseIf* ElseDef? End
+ElseDef = `#else` Tokens
+ElseIf = `#elseif` Condition Tokens
+End = `#end`
+```
+
+#### Comments
+
+Its assumed that subset of Markdown format is used within comment bodies, but not enforced by the compiler.
 
 ```js
 // Comments
-Documentation = `///` ~ /.*/? ~ `\n`
+Markdown = /.*/
+Documentation = `///` ~ Markdown? ~ `\n`
 Comment = CommentLine | CommentNestable
-CommentLine = `//` ~ /.*/? ~ `\n`
+CommentLine = `//` ~ Markdown? ~ `\n`
 // Nested multiline comments /* /* nested */ */
-CommentNestable = `/*` ~ (/.*/ | CommentNestable | `\n`)* ~ `*/`
+CommentNestable = `/*` ~ (Markdown | CommentNestable | `\n`)* ~ `*/`
+```
 
+### Abstract Syntax Tree
+
+Syntax tree definition:
+
+
+```js
 // Literals
 Title = /[A-Z][a-Z_0-9]*/
 Camel = /[a-z_][a-Z_0-9]*/