Make AST comments executable

Author: mandel

src/pdl/pdl-schema.json

@@ -1349,7 +1349,7 @@
     },
     "CodeBlock": {
       "additionalProperties": false,
-      "description": "Execute a piece of code.\n\nExample:\n```PDL\n- def: N\n  lang: python\n  code: |\n    import random\n    # (In PDL, set `result` to the output you wish for your code block.)\n    result = random.randint(1, 20)\n```",
+      "description": "Execute a piece of code.\n\nExample:\n```PDL\nlang: python\ncode: |\n    import random\n    # (In PDL, set `result` to the output you wish for your code block.)\n    result = random.randint(1, 20)\n```",
       "properties": {
         "description": {
           "anyOf": [
@@ -4318,7 +4318,7 @@
     },
     "IfBlock": {
       "additionalProperties": false,
-      "description": "Conditional control structure.\n\nExample:\n```PDL\n- if: ${ eval == 'no' }\n  then:\n    text:\n    - read:\n      message: \"Why not?\\n\"\n```",
+      "description": "Conditional control structure.\n\nExample:\n```PDL\ndefs:\n  answer:\n    read:\n    message: \"Enter a number? \"\nif: ${ (answer | int) == 42 }\nthen: You won!\n```",
       "properties": {
         "description": {
           "anyOf": [
@@ -7186,7 +7186,7 @@
     },
     "MatchBlock": {
       "additionalProperties": false,
-      "description": "Match control structure.",
+      "description": "Match control structure.\n\nExample:\n```PDL\ndefs:\n  answer:\n    read:\n    message: \"Enter a number? \"\nmatch: ${ (answer | int) }\nwith:\n- case: 42\n  then: You won!\n- case:\n    any:\n    def: x\n  if: ${ x > 42 }\n  then: Too high\n- then: Too low",
       "properties": {
         "description": {
           "anyOf": [

src/pdl/pdl_ast.py

@@ -466,9 +466,8 @@ class CodeBlock(BaseCodeBlock):
 
     Example:
     ```PDL
-    - def: N
-      lang: python
-      code: |
+    lang: python
+    code: |
         import random
         # (In PDL, set `result` to the output you wish for your code block.)
         result = random.randint(1, 20)
@@ -600,11 +599,12 @@ class IfBlock(StructuredBlock):
 
     Example:
     ```PDL
-    - if: ${ eval == 'no' }
-      then:
-        text:
-        - read:
-          message: "Why not?\\n"
+    defs:
+      answer:
+        read:
+        message: "Enter a number? "
+    if: ${ (answer | int) == 42 }
+    then: You won!
     ```
     """
 
@@ -642,7 +642,25 @@ class MatchCase(BaseModel):
 
 
 class MatchBlock(StructuredBlock):
-    """Match control structure."""
+    """Match control structure.
+
+    Example:
+    ```PDL
+    defs:
+      answer:
+        read:
+        message: "Enter a number? "
+    match: ${ (answer | int) }
+    with:
+    - case: 42
+      then: You won!
+    - case:
+        any:
+        def: x
+      if: ${ x > 42 }
+      then: Too high
+    - then: Too low
+    """
 
     kind: Literal[BlockKind.MATCH] = BlockKind.MATCH
     match_: ExpressionType[Any] = Field(alias="match")
@@ -735,7 +753,20 @@ class RepeatBlock(StructuredBlock):
 
 
 class ReadBlock(LeafBlock):
-    """Read from a file or standard input."""
+    """Read from a file or standard input.
+
+    Example. Read from the standard input with a prompt starting with `> `.
+    ```PDL
+    read:
+    message: "> "
+    ```
+
+    Example. Read the file `./data.yaml` in the same directory of the PDL file containing the block and parse it into YAML.
+    ```PDL
+    read: ./data.yaml
+    parser: yaml
+    ```
+    """
 
     kind: Literal[BlockKind.READ] = BlockKind.READ
     read: ExpressionType[str] | None