Update extension used by Technique files (#74)

istathar · web-flow · commit 46c75bc1266e · 2025-08-30T15:27:47.000+10:00
Ironically, the compiler itself doesn't actually care about the
extension of the input file, but the samples in the repository needed
updating to the new _.tq_ extension.

Bumps major version to 0.4, representing both this change and the
milestone of having completed the first iteration of the v1 parser!

While we're at it, move the golden test examples to _tests/golden/_,
other examples that we expect to parse but not necessarily be perfectly
formatted (after all, that's the whole point of the parser being as
permissive as possible) to _tests/sample/_, and known-bad edge cases to
_tests/broken/_.

This allows us to run the known-good and known-bad exampkes through the
parser as part of the test suite, so we've added an additional test to
do that.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "technique"
-version = "0.3.6"
+version = "0.4.0"
 edition = "2021"
 description = "A domain specific language for procedures."
 authors = [ "Andrew Cowie" ]
diff --git a/examples/minimal/ExampleOfEverything.tq b/examples/minimal/ExampleOfEverything.tq
@@ -0,0 +1,32 @@
+% technique v1
+! MIT; © 2024 ACME, Inc
+& checklist
+
+making_coffee : Ingredients -> Coffee
+
+# Heading
+
+Ask these questions: are you really sure you want a coffee?
+
+Assuming you do, then:
+
+    1.  { repeat <making_coffee>(e) ~ cups }
+        a.  First task
+        b.  Second another task
+                'Yes' | 'No'
+    2.  Do things { exec(
+        ```bash
+            ./stuff
+        ```
+        ) }
+
+another_example(e) : Input -> Output
+{
+    [
+        "answer" = 42
+        "Question Time" = "What is the question?"
+        "timestamp" = now()
+        "message" = e
+        "interpolation" = "The value is { e }"
+    ]
+}
diff --git a/src/main.rs b/src/main.rs
@@ -56,12 +56,12 @@ fn main() {
                 .action(ArgAction::Version))
         .subcommand(
             Command::new("check")
-                .about("Syntax- and type-check the given procedure")
+                .about("Validate the syntax, structure, and types in the given Technique document.")
                 .arg(
                     Arg::new("watch")
                         .long("watch")
                         .action(clap::ArgAction::SetTrue)
-                        .help("Watch the given procedure file and recompile if changes are detected."),
+                        .help("Watch the given file containing a Technique document and recompile if changes are detected."),
                 )
                 .arg(
                     Arg::new("output")
@@ -75,12 +75,12 @@ fn main() {
                 .arg(
                     Arg::new("filename")
                         .required(true)
-                        .help("The file containing the code for the procedure you want to type-check."),
+                        .help("The file containing the code for the Technique you want to type-check."),
                 ),
         )
         .subcommand(
             Command::new("format")
-                .about("Code format the given procedure")
+                .about("Format the code in the given Technique document.")
                 .arg(
                     Arg::new("raw-control-chars")
                         .short('R')
@@ -100,29 +100,29 @@ fn main() {
                 .arg(
                     Arg::new("filename")
                         .required(true)
-                        .help("The file containing the code for the procedure you want to format."),
+                        .help("The file containing the code for the Technique you want to format."),
                 ),
         )
         .subcommand(
             Command::new("render")
-                .about("Render the Technique procedure into a printable PDF")
-                .long_about("Render the Technique procedure into a printable \
+                .about("Render the Technique document into a printable PDF.")
+                .long_about("Render the Technique document into a printable \
                     PDF. By default this will highlight the source of the \
                     input file for the purposes of reviewing the raw \
-                    procedure.")
+                    procedure in code form.")
                 .arg(
                     Arg::new("output")
                         .short('o')
                         .long("output")
                         .value_parser(["typst", "none"])
                         .default_value("none")
                         .action(ArgAction::Set)
-                        .help("Output format: pdf (default) or typst markup.")
+                        .help("Which kind of diagnostic output to print when rendering.")
                 )
                 .arg(
                     Arg::new("filename")
                         .required(true)
-                        .help("The file containing the code for the procedure you want to print."),
+                        .help("The file containing the code for the Technique you want to print."),
                 ),
         )
         .get_matches();
diff --git a/tests/broken/BadDeclaration.tq b/tests/broken/BadDeclaration.tq
@@ -0,0 +1 @@
+making_coffee : Ingredients Coffee
diff --git a/tests/broken/IllegalUnitSymbol.tq b/tests/broken/IllegalUnitSymbol.tq
@@ -0,0 +1,10 @@
+% technique v1
+
+result :
+{
+    [
+        "speed" = 3.0 × 10⁸ m_s
+        "weight" = 84.0 +/- 3.6 kg
+        "height" = 1.93 * 10^2 cm
+    ]
+}
diff --git a/tests/broken/MagicLine.tq b/tests/broken/MagicLine.tq
@@ -0,0 +1 @@
+% technique v0
diff --git a/tests/broken/UnclosedInterpolation.tq b/tests/broken/UnclosedInterpolation.tq
@@ -0,0 +1,12 @@
+% technique v1
+
+another_example(e) : Input -> Output
+{
+    [
+        "answer" = 42
+        "Question Time" = "What is the question?"
+        "timestamp" = now()
+        "message" = e
+        "interpolation" = "The value is { e "
+    ]
+}
diff --git a/tests/formatting/golden.rs b/tests/formatting/golden.rs
@@ -59,13 +59,13 @@ mod examples {
 
     #[test]
     fn ensure_identical_output() {
-        // Read all .t files from examples/prototype/
-        let dir = Path::new("examples/golden");
+        // Read all .tq files from examples/prototype/
+        let dir = Path::new("tests/golden/");
 
         // Ensure the directory exists
         assert!(dir.exists(), "examples directory missing");
 
-        // Get all .t files in the directory
+        // Get all .tq files in the directory
         let entries = fs::read_dir(dir).expect("Failed to read examples directory");
 
         let mut files = Vec::new();
@@ -76,14 +76,14 @@ mod examples {
             if path
                 .extension()
                 .and_then(|s| s.to_str())
-                == Some("t")
+                == Some("tq")
             {
                 files.push(path);
             }
         }
 
         // Ensure we found some test files
-        assert!(!files.is_empty(), "No .t files found in examples directory");
+        assert!(!files.is_empty(), "No .tq files found in examples directory");
 
         let mut failures = Vec::new();
 
diff --git a/tests/golden/Bedtime.tq b/tests/golden/Bedtime.tq
diff --git a/tests/golden/ExampleOfEverything.tq b/tests/golden/ExampleOfEverything.tq
@@ -0,0 +1,32 @@
+% technique v1
+! MIT; © 2024 ACME, Inc
+& checklist
+
+making_coffee : Ingredients -> Coffee
+
+# Heading
+
+Ask these questions: are you really sure you want a coffee?
+
+Assuming you do, then:
+
+    1.  { repeat <making_coffee>(e) ~ cups }
+        a.  First task
+        b.  Second another task
+                'Yes' | 'No'
+    2.  Do things { exec(
+        ```bash
+            ./stuff
+        ```
+        ) }
+
+another_example(e) : Input -> Output
+{
+    [
+        "answer" = 42
+        "Question Time" = "What is the question?"
+        "timestamp" = now()
+        "message" = e
+        "interpolation" = "The value is { e }"
+    ]
+}
diff --git a/tests/golden/ManyAttributes.tq b/tests/golden/ManyAttributes.tq
diff --git a/tests/parsing/mod.rs b/tests/parsing/mod.rs
@@ -1,2 +1,3 @@
 mod errors;
 mod parser;
+mod samples;
diff --git a/tests/parsing/samples.rs b/tests/parsing/samples.rs
@@ -0,0 +1,101 @@
+#[cfg(test)]
+mod samples {
+    use std::fs;
+    use std::path::Path;
+
+    use technique::parsing;
+
+    #[test]
+    fn ensure_samples_parse() {
+        let dir = Path::new("tests/samples/");
+
+        assert!(dir.exists(), "samples directory missing");
+
+        let entries = fs::read_dir(dir).expect("Failed to read samples directory");
+
+        let mut files = Vec::new();
+        for entry in entries {
+            let entry = entry.expect("Failed to read directory entry");
+            let path = entry.path();
+
+            if path
+                .extension()
+                .and_then(|s| s.to_str())
+                == Some("tq")
+            {
+                files.push(path);
+            }
+        }
+
+        assert!(!files.is_empty(), "No .tq files found in samples directory");
+
+        let mut failures = Vec::new();
+
+        for file in &files {
+            let content = parsing::load(&file)
+                .unwrap_or_else(|e| panic!("Failed to load file {:?}: {:?}", file, e));
+
+            match parsing::parse(&file, &content) {
+                Ok(_) => {}
+                Err(e) => {
+                    println!("File {:?} failed to parse: {:?}", file, e);
+                    failures.push(file.clone());
+                }
+            }
+        }
+
+        if !failures.is_empty() {
+            panic!(
+                "Sample files should parse successfully, but {} files failed",
+                failures.len()
+            );
+        }
+    }
+
+    #[test]
+    fn ensure_broken_fail() {
+        let dir = Path::new("tests/broken/");
+
+        assert!(dir.exists(), "broken directory missing");
+
+        let entries = fs::read_dir(dir).expect("Failed to read broken directory");
+
+        let mut files = Vec::new();
+        for entry in entries {
+            let entry = entry.expect("Failed to read directory entry");
+            let path = entry.path();
+
+            if path
+                .extension()
+                .and_then(|s| s.to_str())
+                == Some("tq")
+            {
+                files.push(path);
+            }
+        }
+
+        assert!(!files.is_empty(), "No .tq files found in broken directory");
+
+        let mut unexpected_successes = Vec::new();
+
+        for file in &files {
+            let content = parsing::load(&file)
+                .unwrap_or_else(|e| panic!("Failed to load file {:?}: {:?}", file, e));
+
+            match parsing::parse(&file, &content) {
+                Ok(_) => {
+                    println!("File {:?} unexpectedly parsed successfully", file);
+                    unexpected_successes.push(file.clone());
+                }
+                Err(_) => {}
+            }
+        }
+
+        if !unexpected_successes.is_empty() {
+            panic!(
+                "Broken files should not to parse successfully, but {} files passed",
+                unexpected_successes.len()
+            );
+        }
+    }
+}
diff --git a/tests/samples/HeaderAndDeclaration.tq b/tests/samples/HeaderAndDeclaration.tq
diff --git a/tests/samples/TabletOfQuantity.tq b/tests/samples/TabletOfQuantity.tq
@@ -0,0 +1,10 @@
+% technique v1
+
+result :
+{
+    [
+        "speed" = 3.0 × 10⁸ m/s
+        "weight" = 84.0 +/- 3.6 kg
+        "height" = 1.93 * 10^2 cm
+    ]
+}
