Update command line arguments (#22)

* Add options --(no-)stream-result and --(no-)-stream-background

* Use the option --trace to directly provide the name of the trace file and use *_trace.json as default trace file name

* Change `--data_file` into `--data-file`

Author: mandel

.gitignore

@@ -147,8 +147,7 @@ pdl-live/package-lock.json
 
 
 # PDL trace
-*_result.json
-*_result.yaml
+*_trace.json
 
 # Built docs
 _site

README.md

@@ -77,13 +77,13 @@ pdl --data <JSON-or-YAML-data> <my-example>
 This can also be done by passing a JSON or YAML file:
 
 ```
-pdl --data_file <JSON-or-YAML-file> <my-example>
+pdl --data-file <JSON-or-YAML-file> <my-example>
 ```
 
 The interpreter can also output a trace file that is used by the Live Document visualization tool (see [Live Document](#live_document)):
 
 ```
-pdl --trace <json | yaml> <my-example>
+pdl <my-example> --trace
 ```
 
 For more information:
@@ -356,13 +356,13 @@ See [PDL Language Tutorial](https://ibm.github.io/prompt-declaration-language/tu
 ## Live Document Visualizer
 
 PDL has a Live Document visualizer to help in program understanding given an execution trace.
-To produce an execution trace consumable by the Live Document, you can run the interpreter with the `--trace` argument and set the value to either `json` or `yaml`:
+To produce an execution trace consumable by the Live Document, you can run the interpreter with the `--trace` argument:
 
 ```
-pdl --trace <json | yaml> <my-example>
+pdl <my-example> --trace
 ```
 
-This produces an additional file named `my-example_result.json` or `my-example_result.yaml` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
+This produces an additional file named `my-example_trace.json` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
 in the right pane. 
 
 This is similar to a spreadsheet for tabular data, where data is in the forefront and the user can inspect the formula that generates the data in each cell. In the Live Document, cells are not uniform but can take arbitrary extents. Clicking on them similarly reveals the part of the code that produced them.

docs/README.md

@@ -79,7 +79,7 @@ python3 -m pdl.pdl --data <JSON-or-YAML-data> <my-example>
 This can also be done by passing a JSON or YAML file:
 
 ```
-python3 -m pdl.pdl --data_file <JSON-or-YAML-file> <my-example>
+python3 -m pdl.pdl --data-file <JSON-or-YAML-file> <my-example>
 ```
 
 ## Overview
@@ -345,10 +345,10 @@ PDL has a Live Document visualizer to help in program understanding given an exe
 To produce an execution trace consumable by the Live Document, you can run the interpreter with the `--trace` argument and set the value to either `json` or `yaml`:
 
 ```
-python -m pdl.pdl --trace <json | yaml> <my-example>
+python -m pdl.pdl <my-example> --trace
 ```
 
-This produces an additional file named `my-example_result.json` or `my-example_result.yaml` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
+This produces an additional file named `my-example_trace.json` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
 in the right pane. 
 
 This is similar to a spreadsheet for tabular data, where data is in the forefront and the user can inspect the formula that generates the data in each cell. In the Live Document, cells are not uniform but can take arbitrary extents. Clicking on them similarly reveals the part of the code that produced them.

docs/tutorial.md

@@ -1283,10 +1283,10 @@ PDL has a Live Document visualizer to help in program understanding given an exe
 To produce an execution trace consumable by the Live Document, you can run the interpreter with the `--trace` argument and set the value to either `json` or `yaml`:
 
 ```
-python -m pdl.pdl --trace <json | yaml> <my-example>
+python -m pdl.pdl <my-example> --trace
 ```
 
-This produces an additional file named `my-example_result.json` or `my-example_result.yaml` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
+This produces an additional file named `my-example_trace.json` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
 in the right pane. 
 
 This is similar to a spreadsheet for tabular data, where data is in the forefront and the user can inspect the formula that generates the data in each cell. In the Live Document, cells are not uniform but can take arbitrary extents. Clicking on them similarly reveals the part of the code that produced them.

pdl/pdl.py

@@ -1,5 +1,6 @@
 import argparse
 import json
+from pathlib import Path
 from typing import Any, Optional, TypedDict
 
 import yaml
@@ -140,7 +141,8 @@ def main():
 
     parser.add_argument(
         "-f",
-        "--data_file",
+        "--data-file",
+        dest="data_file",
         help="initial scope data file",
     )
 
@@ -150,12 +152,29 @@ def main():
         help="scope data",
     )
 
-    parser.add_argument("-o", "--output", help="output file")
     parser.add_argument(
-        "-t", "--trace", help="output trace for live document", choices=["json", "yaml"]
+        "--stream-result",
+        dest="stream_result",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="stream the result on the standard output instead of printing it at the end of the execution",
+    )
+
+    parser.add_argument(
+        "--stream-background",
+        dest="stream_background",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="stream the background messages on the standard output",
+    )
+
+    parser.add_argument(
+        "-t",
+        "--trace",
+        nargs="?",
+        const="*_trace.json",
+        help="output trace for live document",
     )
-    parser.add_argument("--json", help="json file")
-    parser.add_argument("--yaml", help="yaml file")
     parser.add_argument("pdl", nargs="?", help="pdl file", type=str)
 
     args = parser.parse_args()
@@ -180,12 +199,19 @@ def main():
     if args.data is not None:
         initial_scope = initial_scope | yaml.safe_load(args.data)
 
+    config = InterpreterConfig(
+        yield_result=args.stream_result, yield_background=args.stream_background
+    )
+    if args.trace == "*_trace.json":
+        trace_file = str(Path(args.pdl).with_suffix("")) + "_trace.json"
+    else:
+        trace_file = args.trace
     pdl_interpreter.generate(
         args.pdl,
         args.log,
+        InterpreterState(**config),
         initial_scope,
-        args.trace,
-        args.output,
+        trace_file,
     )
 
 

pdl/pdl_interpreter.py

@@ -2,8 +2,7 @@
 import re
 import types
 from itertools import batched
-from pathlib import Path
-from typing import Any, Generator, Iterable, Literal, Optional, Sequence
+from typing import Any, Generator, Iterable, Optional, Sequence
 
 import requests
 import yaml
@@ -55,7 +54,7 @@
     empty_block_location,
 )
 from .pdl_ast_utils import iter_block_children, iter_blocks
-from .pdl_dumper import block_to_dict, dump_yaml
+from .pdl_dumper import block_to_dict
 from .pdl_llms import BamModel, LitellmModel, WatsonxModel
 from .pdl_location_utils import append, get_loc_string
 from .pdl_parser import PDLParseError, parse_file
@@ -99,24 +98,25 @@ def with_role(self: "InterpreterState", role: RoleType) -> "InterpreterState":
 def generate(
     pdl_file: str,
     log_file: Optional[str],
+    state: Optional[InterpreterState],
     initial_scope: ScopeType,
-    output_trace: Optional[Literal["json", "yaml"]],
-    output_file: Optional[str],
+    trace_file: Optional[str],
 ):
     """Execute the PDL program defined in `pdl_file`.
 
     Args:
         pdl_file: Program to execute.
         log_file: File where the log is written. If `None`, use `log.txt`.
         initial_scope: Environment defining the variables in scope to execute the program.
-        output_trace: Format in which the execution trace must be produced.
-        output_file: File to save the execution trace.
+        state: Initial state of the interpreter.
+        trace_file: Indicate if the execution trace must be produced and the file to save it.
     """
     if log_file is None:
         log_file = "log.txt"
     try:
         prog, loc = parse_file(pdl_file)
-        state = InterpreterState()
+        if state is None:
+            state = InterpreterState()
         result, _, _, trace = process_prog(state, initial_scope, prog, loc)
         if not state.yield_result:
             if state.yield_background:
@@ -125,34 +125,24 @@ def generate(
         with open(log_file, "w", encoding="utf-8") as log_fp:
             for line in state.log:
                 log_fp.write(line)
-        if output_trace is not None and trace is not None:
-            write_trace(pdl_file, output_trace, output_file, trace)
+        if trace_file:
+            write_trace(trace_file, trace)
     except PDLParseError as e:
         print("\n".join(e.msg))
 
 
 def write_trace(
-    pdl_file: str,
-    mode: Literal["json", "yaml"],
-    output_file: Optional[str],
+    trace_file: str,
     trace: BlockType,
 ):
     """Write the execution trace into a file.
 
     Args:
-        pdl_file: Name of the PDL program executed.
-        mode: Format in which the execution trace must be produced.
-        output_file:  File to save the execution trace.
+        trace_file:  File to save the execution trace.
         trace: Execution trace.
     """
-    if output_file is None:
-        output_file = str(Path(pdl_file).with_suffix("")) + f"_result.{mode}"
-    with open(output_file, "w", encoding="utf-8") as fp:
-        match mode:
-            case "json":
-                json.dump(block_to_dict(trace), fp)
-            case "yaml":
-                dump_yaml(block_to_dict(trace), stream=fp)
+    with open(trace_file, "w", encoding="utf-8") as fp:
+        json.dump(block_to_dict(trace), fp)
 
 
 def process_prog(

tests/test_line_table.py

@@ -2,7 +2,7 @@
 
 
 def do_test(t, capsys):
-    generate(t["file"], None, {}, None, None)
+    generate(t["file"], None, None, {}, None)
     captured = capsys.readouterr()
     output = captured.out.split("\n")
     print(output)