Introduce translation phase (#101)

This takes the parser's internal Abstract Syntax Tree and lowers it to
an Intermediate Representation with symbols resolved and a series of
operations to be evaluated.

This happens in a new `translation` phase after the `parsing` phase to
the compiler. The _technique check_ command is now augmented with an
`--until` option that if specified stops the compiler after reaching and
completing that phase.

The Intermediate Representation deliberately uses type names that are
different than those used by the surface language's Abstract Syntax Tree
representation. So a Technique language::Procedure becomes
program::Subroutine and so on.

Reorganized the known-good and known-bad test samples by phase.

Author: istathar

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "technique"
-version = "0.5.5"
+version = "0.5.6"
 edition = "2021"
 description = "A domain specific language for procedures."
 authors = [ "Andrew Cowie" ]

Cargo.toml

@@ -23,7 +23,7 @@
 use crate::regex::*;
 use std::fmt::{self, Display};
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Quantity<'i> {
     pub mantissa: Decimal,
     pub uncertainty: Option<Decimal>,

src/language/quantity.rs

@@ -108,7 +108,7 @@ impl<'i> Procedure<'i> {
     }
 }
 
-#[derive(Eq, Debug)]
+#[derive(Clone, Copy, Eq, Debug)]
 pub struct Identifier<'i> {
     pub value: &'i str,
     pub span: Span,
@@ -445,7 +445,7 @@ impl PartialEq for Expression<'_> {
     }
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Numeric<'i> {
     Integral(i64),
     Scientific(Quantity<'i>),

src/language/types.rs

@@ -3,5 +3,7 @@ pub mod formatting;
 pub mod highlighting;
 pub mod language;
 pub mod parsing;
+pub mod program;
 pub(crate) mod regex;
 pub mod templating;
+pub mod translation;

src/lib.rs

@@ -10,17 +10,26 @@ use technique::formatting::{self, Identity};
 use technique::highlighting::{self, Terminal};
 use technique::parsing;
 use technique::templating::{self, Checklist, NasaEsaIss, Procedure, Recipe, Source};
+use technique::translation;
 
 mod editor;
 mod output;
 mod problem;
 
 #[derive(Eq, Debug, PartialEq)]
+#[allow(dead_code)]
 enum Output {
+    Terminal,
     Native,
     Silent,
 }
 
+#[derive(Eq, Debug, PartialEq)]
+enum Phase {
+    Parsing,
+    Translation,
+}
+
 fn main() {
     const VERSION: &str = concat!("v", env!("CARGO_PKG_VERSION"));
 
@@ -72,6 +81,18 @@ fn main() {
                         .action(ArgAction::Set)
                         .help("Which kind of diagnostic output to print when checking.")
                 )
+                .arg(
+                    Arg::new("until")
+                        .long("until")
+                        .value_name("phase")
+                        .value_parser(["parsing", "translation"])
+                        .default_value("parsing")
+                        .action(ArgAction::Set)
+                        .help("Stop compilation after the given phase is complete so that the result can be inspected. \
+                            Use this in conjunction with the --output option. The phases are: \
+                            parsing, where the input is parsed from the surface language to an internal abstract syntax tree; then \
+                            translation, which resolves names, checks references, and ensures the input is valid Technique.")
+                )
                 .arg(
                     Arg::new("filename")
                         .required(true)
@@ -173,12 +194,23 @@ fn main() {
                 .unwrap();
             let output = match output.as_str() {
                 "native" => Output::Native,
-                "none" => Output::Silent,
+                "none" => Output::Terminal,
                 _ => panic!("Unrecognized --output value"),
             };
 
             debug!(?output);
 
+            let until = submatches
+                .get_one::<String>("until")
+                .unwrap();
+            let until = match until.as_str() {
+                "parsing" => Phase::Parsing,
+                "translation" => Phase::Translation,
+                _ => panic!("Unrecognized --until value"),
+            };
+
+            debug!(?until);
+
             let filename = submatches
                 .get_one::<String>("filename")
                 .unwrap(); // argument are required by definition so always present
@@ -213,12 +245,51 @@ fn main() {
                 }
             };
 
-            // TODO continue with validation of the returned technique
+            if let Phase::Parsing = until {
+                match output {
+                    Output::Terminal => {
+                        eprintln!("{}", "ok".bright_green());
+                    }
+                    Output::Native => {
+                        println!("{:#?}", technique);
+                    }
+                    Output::Silent => {}
+                }
+                std::process::exit(0);
+            }
 
-            eprintln!("{}", "ok".bright_green());
+            let program = match translation::translate(&technique) {
+                Ok(program) => program,
+                Err(errors) => {
+                    for (i, error) in errors
+                        .iter()
+                        .enumerate()
+                    {
+                        if i > 0 {
+                            eprintln!();
+                        }
+                        eprintln!(
+                            "{}",
+                            problem::concise_translation_error(
+                                &error, &filename, &content, &Terminal
+                            )
+                        );
+                    }
+                    std::process::exit(1);
+                }
+            };
 
-            if let Output::Native = output {
-                println!("{:#?}", technique);
+            if let Phase::Translation = until {
+                match output {
+                    Output::Terminal => {
+                        eprintln!("{}", "ok".bright_green());
+                    }
+                    Output::Native => {
+                        println!("{:#?}", program);
+                    }
+                    Output::Silent => {}
+                }
+                std::process::exit(0);
             }
         }
         Some(("format", submatches)) => {

src/main.rs

@@ -1566,7 +1566,7 @@ III. Implementation
 
 #[test]
 fn spans_are_populated() {
-    let source = std::fs::read_to_string("tests/samples/KnownSpanLengths.tq").unwrap();
+    let source = std::fs::read_to_string("tests/samples/parsing/KnownSpanLengths.tq").unwrap();
 
     let mut input = Parser::new();
     input.initialize(&source);

src/parsing/checks/verify.rs

@@ -1,7 +1,10 @@
-use super::messages::generate_error_message;
+use super::messages::{generate_error_message, generate_translation_error};
 use owo_colors::OwoColorize;
 use std::path::Path;
-use technique::{formatting::Render, language::LoadingError, parsing::ParsingError};
+use technique::{
+    formatting::Render, language::LoadingError, parsing::ParsingError,
+    translation::TranslationError,
+};
 
 /// Format a parsing error with full details including source code context
 pub fn full_parsing_error<'i>(
@@ -89,6 +92,33 @@ pub fn concise_parsing_error<'i>(
     )
 }
 
+/// Format a translation error with concise single-line output.
+pub fn concise_translation_error<'i>(
+    error: &TranslationError<'i>,
+    filename: &'i Path,
+    source: &'i str,
+    renderer: &impl Render,
+) -> String {
+    let (problem, _) = generate_translation_error(error, renderer);
+    let input = generate_filename(filename);
+    let offset = error
+        .span()
+        .offset;
+    let i = calculate_line_number(source, offset);
+    let j = calculate_column_number(source, offset);
+    let line = i + 1;
+    let column = j + 1;
+
+    format!(
+        "{}: {}:{}:{} {}",
+        "error".bright_red(),
+        input,
+        line,
+        column,
+        problem.bold(),
+    )
+}
+
 /// Format a LoadingError with concise single-line output
 pub fn concise_loading_error<'i>(error: &LoadingError<'i>) -> String {
     format!(

src/problem/format.rs

@@ -1,5 +1,7 @@
 use crate::problem::Present;
-use technique::{formatting::Render, language::*, parsing::ParsingError};
+use technique::{
+    formatting::Render, language::*, parsing::ParsingError, translation::TranslationError,
+};
 
 /// Generate problem and detail messages for parsing errors using AST construction
 pub fn generate_error_message<'i>(error: &ParsingError, renderer: &dyn Render) -> (String, String) {
@@ -1015,3 +1017,34 @@ Hyphens, underscores, spaces, or subscripts are not valid in unit symbols.
         }
     }
 }
+
+/// Generate problem and detail messages for translation errors.
+pub fn generate_translation_error<'i>(
+    error: &TranslationError<'i>,
+    _renderer: &dyn Render,
+) -> (String, String) {
+    match error {
+        TranslationError::DuplicateProcedure(Identifier { value: name, .. }) => (
+            format!("Duplicate procedure name '{}'", name),
+            "A procedure with this name has already been declared in this document.".to_string(),
+        ),
+        TranslationError::DuplicateTitle {
+            procedure: Identifier { value: name, .. },
+            ..
+        } => (
+            format!("Duplicate title in procedure '{}'", name),
+            "A procedure can have at most one title.".to_string(),
+        ),
+        TranslationError::InterleavedDescription {
+            procedure: Identifier { value: name, .. },
+            ..
+        } => (
+            format!("Description out of place in procedure '{}'", name),
+            "A procedure's free-text description must appear immediately after the title and before any steps or code blocks.".to_string(),
+        ),
+        TranslationError::UnresolvedProcedure(Identifier { value: name, .. }) => (
+            format!("Unresolved procedure '{}'", name),
+            "A `<name>` invocation must refer to a procedure declared in this document. Built-in functions use the `name(...)` form (without angle brackets).".to_string(),
+        ),
+    }
+}

src/problem/messages.rs

@@ -0,0 +1,6 @@
+//! Intermediate Representation suitable for an interpreter.
+
+mod types;
+
+// Re-export all public symbols
+pub use types::*;