synthra 0.1.0

data/tech_docs/dsl/grammar.md

@@ -0,0 +1,431 @@
+# DSL Grammar Reference
+
+Complete grammar specification for FakeDataDSL schemas.
+
+## Table of Contents
+
+- [Basic Syntax](#basic-syntax)
+- [Comments](#comments)
+- [Quoting Rules](#quoting-rules)
+- [Escaping](#escaping)
+- [Multi-line Values](#multi-line-values)
+- [Indentation](#indentation)
+- [Schema Structure](#schema-structure)
+- [Field Definitions](#field-definitions)
+- [Type System](#type-system)
+- [Annotations](#annotations)
+
+---
+
+## Basic Syntax
+
+FakeDataDSL uses a YAML-like indentation-based syntax:
+
+```dsl
+SchemaName:
+  field_name: type
+  field_name: type(arguments)
+```
+
+### Rules
+
+1. **Schema names** start with uppercase letter: `User`, `OrderItem`, `TwitterDM`
+2. **Field names** are lowercase with underscores: `user_id`, `created_at`
+3. **Types** are lowercase: `uuid`, `text`, `number`
+4. **Indentation** must be exactly 2 spaces (no tabs)
+
+---
+
+## Comments
+
+Comments start with `#` and continue to end of line:
+
+```dsl
+# This is a comment
+User:
+  id: uuid              # Inline comment
+  name: text            # Full name
+  # This field is optional
+  phone?: phone
+```
+
+### Comment Rules
+
+- `#` starts a comment anywhere on a line
+- Comments can appear on their own line or after code
+- Comments inside strings are NOT comments: `text: const("#hashtag")`
+- Empty lines are allowed and ignored
+
+---
+
+## Quoting Rules
+
+### When Quotes Are Required
+
+| Context | Quoted | Unquoted | Notes |
+|---------|--------|----------|-------|
+| `const()` values | ✅ Required | ❌ Invalid | `const("value")` |
+| `enum()` values | ❌ Optional | ✅ OK | `enum(a, b, c)` |
+| Path in `copy()` | ✅ Required | ❌ Invalid | `copy("user.id")` |
+| Type arguments | ❌ No | ✅ Yes | `text(10..50)` |
+| Schema references | ❌ No | ✅ Yes | `user: User` |
+
+### Examples
+
+```dsl
+User:
+  # const() REQUIRES quotes
+  type: const("user")
+  status: const("active")
+  
+  # enum() quotes are optional
+  role: enum(admin, user, guest)
+  role: enum("admin", "user", "guest")  # Also valid
+  
+  # copy() REQUIRES quotes for path
+  full_name: copy("first_name")
+  
+  # Ranges don't use quotes
+  age: number(18..65)
+  
+  # Schema references don't use quotes
+  address: Address
+```
+
+### String Literals
+
+Use double quotes for string literals:
+
+```dsl
+User:
+  type: const("message_create")    # ✅ Correct
+  type: const(message_create)      # ❌ Invalid - missing quotes
+  type: const('message_create')    # ❌ Invalid - single quotes not supported
+```
+
+---
+
+## Escaping
+
+### Escape Sequences in Strings
+
+| Sequence | Meaning |
+|----------|---------|
+| `\"` | Double quote |
+| `\\` | Backslash |
+| `\n` | Newline |
+| `\t` | Tab |
+
+### Examples
+
+```dsl
+User:
+  # Quote in string
+  greeting: const("Hello \"World\"")
+  
+  # Backslash
+  path: const("C:\\Users\\Name")
+  
+  # Newline (in generated text)
+  bio: const("Line 1\nLine 2")
+```
+
+### Special Characters
+
+Most special characters work without escaping in appropriate contexts:
+
+```dsl
+User:
+  # Email with special chars
+  email: email  # Generates: user@example.com
+  
+  # URL with special chars
+  website: url  # Generates: https://example.com/path?query=1
+  
+  # JSON-safe text is auto-escaped in output
+```
+
+---
+
+## Multi-line Values
+
+### Not Supported in Current Version
+
+Multi-line string literals are **not** currently supported in the DSL:
+
+```dsl
+# ❌ NOT VALID
+User:
+  bio: const("This is a
+    multi-line
+    string")
+```
+
+### Workaround
+
+Use `\n` escape sequences for multi-line content:
+
+```dsl
+# ✅ Valid
+User:
+  bio: const("Line 1\nLine 2\nLine 3")
+```
+
+Or use the `paragraph` type for generated multi-line text:
+
+```dsl
+User:
+  bio: paragraph(2..5)  # 2-5 paragraphs of Lorem ipsum
+```
+
+---
+
+## Indentation
+
+### Rules
+
+1. **Use exactly 2 spaces** for each indentation level
+2. **Tabs are not allowed** and will cause parse errors
+3. **Consistent indentation** required within a schema
+
+### Correct Example
+
+```dsl
+User:                           # Level 0
+  id: uuid                      # Level 1 (2 spaces)
+  name: text                    # Level 1
+  address: Address              # Level 1
+
+Address:                        # Level 0
+  street: text                  # Level 1
+  city: city                    # Level 1
+```
+
+### Common Mistakes
+
+```dsl
+# ❌ Wrong: using tabs
+User:
+	id: uuid                    # Tab character - ERROR
+
+# ❌ Wrong: inconsistent indentation
+User:
+  id: uuid                      # 2 spaces
+   name: text                   # 3 spaces - ERROR
+
+# ❌ Wrong: no indentation
+User:
+id: uuid                        # No indent - ERROR
+```
+
+---
+
+## Schema Structure
+
+### Basic Schema
+
+```dsl
+SchemaName:
+  field1: type1
+  field2: type2
+```
+
+### Schema with Annotations
+
+```dsl
+User:
+  @version 1.0
+  @deprecated Use UserV2 instead
+  
+  id: uuid
+  name: text
+```
+
+### Schema with Behaviors
+
+```dsl
+APIResponse:
+  @latency 100..500ms
+  @failure 5%
+  
+  status: number
+  data: object
+```
+
+### Multiple Schemas in One File
+
+```dsl
+User:
+  id: uuid
+  name: text
+
+Address:
+  street: text
+  city: city
+
+Order:
+  user: User
+  shipping: Address
+```
+
+---
+
+## Field Definitions
+
+### Basic Field
+
+```dsl
+field_name: type
+```
+
+### Field with Arguments
+
+```dsl
+field_name: type(arg1, arg2)
+field_name: type(name: value, name2: value2)
+```
+
+### Optional Field (May Not Appear)
+
+```dsl
+phone?: phone
+```
+
+### Nullable Field (May Be Null)
+
+```dsl
+nickname: text?
+```
+
+### Optional AND Nullable
+
+```dsl
+bio?: text?
+```
+
+### Conditional Field
+
+```dsl
+tracking_number: text if shipped
+```
+
+### Field with Behavior
+
+```dsl
+email: email @partial_data 10%
+```
+
+---
+
+## Type System
+
+### Primitive Types
+
+```dsl
+id: uuid                  # UUID v4
+count: number(1..100)     # Integer in range
+price: float(0.99..99.99) # Float in range
+name: text(5..50)         # String of length
+active: boolean           # true/false
+status: enum(a, b, c)     # One of values
+type: const("literal")    # Constant value
+```
+
+### Complex Types
+
+```dsl
+items: array(Item, 1..5)           # Array of schemas
+user: User                          # Nested schema
+user_id: Ref(User.id)               # Reference to another schema
+sender_id: copy("sender.id")        # Copy from generated field
+recipient: shared(User)              # Shared across batch
+users: map_by_field("id", a: S1)    # Dynamic keys
+payload: one_of(A, B, C)            # Polymorphic
+```
+
+---
+
+## Annotations
+
+### @version
+
+Declares schema version:
+
+```dsl
+User:
+  @version 1.0
+  id: uuid
+```
+
+### @deprecated
+
+Marks schema as deprecated:
+
+```dsl
+LegacyUser:
+  @deprecated Use User instead
+  id: uuid
+```
+
+### @latency
+
+Adds delay to generation:
+
+```dsl
+APIResponse:
+  @latency 100..500ms
+  data: object
+```
+
+### @failure
+
+Simulates failures:
+
+```dsl
+APIResponse:
+  @failure 5%
+  data: object
+```
+
+### @partial_data
+
+Randomly omits optional fields:
+
+```dsl
+User:
+  @partial_data 20%
+  name: text
+  phone?: phone
+```
+
+---
+
+## Grammar BNF (Formal)
+
+```bnf
+dsl           := schema*
+schema        := SCHEMA_NAME ':' NEWLINE INDENT annotation* field* DEDENT
+annotation    := '@' IDENTIFIER value? NEWLINE
+field         := FIELD_NAME optional? ':' type nullable? condition? behavior* NEWLINE
+optional      := '?'
+nullable      := '?'
+type          := TYPE_NAME arguments?
+arguments     := '(' arg_list ')'
+arg_list      := arg (',' arg)*
+arg           := value | named_arg | range
+named_arg     := IDENTIFIER ':' value
+range         := NUMBER '..' NUMBER
+condition     := 'if' IDENTIFIER
+behavior      := '@' IDENTIFIER value?
+value         := STRING | NUMBER | BOOLEAN | IDENTIFIER
+```
+
+---
+
+## Next Steps
+
+- [Core Types](core_types.md) - All built-in types
+- [Complex Types](complex_types.md) - Arrays, objects, references
+- [Field Modifiers](field_modifiers.md) - Optional, nullable, conditional
+- [Behaviors](../behaviors/overview.md) - Latency, failure, etc.
+