lrpar/

ctbuilder.rs

//! Build grammars at compile-time so that they can be statically included into a binary.

use std::{
    collections::{HashMap, HashSet},
    env::{current_dir, var},
    error::Error,
    fmt::{self, Debug, Write as fmtWrite},
    fs::{self, File, create_dir_all, read_to_string},
    hash::Hash,
    io::Write,
    marker::PhantomData,
    path::{Path, PathBuf},
    sync::{LazyLock, Mutex},
};

use crate::{
    LexerTypes, RTParserBuilder, RecoveryKind,
    codegen::{
        ParserBuildEnv, ParserBuildEnvArgs, ParserBuildEnvError, ParserCodegen, ParserSrcEnv,
        ParserSrcEnvError,
    },
    diagnostics::{DiagnosticFormatter, SpannedDiagnosticFormatter},
};

#[cfg(feature = "_unstable_api")]
use crate::unstable_api::UnstableApi;

use cfgrammar::{
    Location,
    header::{Header, HeaderError, HeaderErrorKind, HeaderValue, Namespaced, Setting, Value},
    markmap::{Entry, MergeBehavior},
    yacc::{YaccGrammar, YaccKind, ast::ASTWithValidityInfo},
};
use filetime::FileTime;
use lrtable::{StateGraph, StateTable, statetable::Conflicts};
use num_traits::{AsPrimitive, PrimInt, Unsigned};
use wincode::{SchemaRead, SchemaReadOwned, SchemaWrite};

const RUST_FILE_EXT: &str = "rs";
const WARNING: &str = "[Warning]";
pub(crate) const ERROR: &str = "[Error]";

static GENERATED_PATHS: LazyLock<Mutex<HashSet<PathBuf>>> =
    LazyLock::new(|| Mutex::new(HashSet::new()));

pub(crate) struct CTConflictsError<StorageT: Eq + Hash> {
    pub(crate) conflicts_diagnostic: String,
    #[cfg(test)]
    #[cfg_attr(test, allow(dead_code))]
    pub(crate) stable: StateTable<StorageT>,
    pub(crate) phantom: PhantomData<StorageT>,
}

impl<StorageT> fmt::Display for CTConflictsError<StorageT>
where
    StorageT: 'static + Debug + Hash + PrimInt + Unsigned,
    usize: AsPrimitive<StorageT>,
{
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{}", self.conflicts_diagnostic)
    }
}

impl<StorageT> fmt::Debug for CTConflictsError<StorageT>
where
    StorageT: 'static + Debug + Hash + PrimInt + Unsigned,
    usize: AsPrimitive<StorageT>,
{
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{}", self.conflicts_diagnostic)
    }
}

impl<StorageT> Error for CTConflictsError<StorageT>
where
    StorageT: 'static + Debug + Hash + PrimInt + Unsigned,
    usize: AsPrimitive<StorageT>,
{
}

/// A string which uses `Display` for it's `Debug` impl.
struct ErrorString(String);
impl fmt::Display for ErrorString {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let ErrorString(s) = self;
        write!(f, "{}", s)
    }
}
impl fmt::Debug for ErrorString {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let ErrorString(s) = self;
        write!(f, "{}", s)
    }
}
impl Error for ErrorString {}

/// Specify the visibility of the module generated by `CTBuilder`.
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum Visibility {
    /// Module-level visibility only.
    Private,
    /// `pub`
    Public,
    /// `pub(super)`
    PublicSuper,
    /// `pub(self)`
    PublicSelf,
    /// `pub(crate)`
    PublicCrate,
    /// `pub(in {arg})`
    PublicIn(String),
}

/// Specifies the [Rust Edition] that will be emitted during code generation.
///
/// [Rust Edition]: https://doc.rust-lang.org/edition-guide/rust-2021/index.html
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum RustEdition {
    Rust2015,
    Rust2018,
    Rust2021,
}

/// Sets the underlying encoding algorithm for serialising the `ParserData` into the generated source files.
///
/// This correlates to a specific `Configuration` of [wincode::config](https://docs.rs/wincode/latest/wincode/config/index.html).
#[non_exhaustive]
#[derive(SchemaRead, SchemaWrite, Debug, Clone, Copy)]
pub enum SerialisationFormat {
    /// See [wincode::FixedInt](https://docs.rs/wincode/latest/wincode/int_encoding/struct.FixedInt.html)
    FixedSizeInteger,
    /// See [wincode::VarInt](https://docs.rs/wincode/latest/wincode/int_encoding/struct.VarInt.html)
    VariableSizedInteger,
}

impl TryFrom<SerialisationFormat> for Value<Location> {
    type Error = cfgrammar::header::HeaderError<Location>;
    fn try_from(kind: SerialisationFormat) -> Result<Value<Location>, HeaderError<Location>> {
        let from_loc = Location::Other("From<SerialisationFormat>".to_string());
        Ok(match kind {
            SerialisationFormat::FixedSizeInteger => Value::Setting(Setting::Unitary(Namespaced {
                namespace: Some(("serialisationformat".to_string(), from_loc.clone())),
                member: ("fixedsizeinteger".to_string(), from_loc),
            })),
            SerialisationFormat::VariableSizedInteger => {
                Value::Setting(Setting::Unitary(Namespaced {
                    namespace: Some(("serialisationformat".to_string(), from_loc.clone())),
                    member: ("variablesizedinteger".to_string(), from_loc),
                }))
            }
        })
    }
}

impl<T: Clone + Debug> TryFrom<&Value<T>> for SerialisationFormat {
    type Error = HeaderError<T>;
    fn try_from(value: &Value<T>) -> Result<SerialisationFormat, HeaderError<T>> {
        let mut err_locs = Vec::new();
        match value {
            // Finally handle enum values.
            Value::Setting(Setting::Unitary(Namespaced {
                namespace,
                member: (enc_value, enc_value_loc),
            })) => {
                if let Some((ns, ns_loc)) = namespace
                    && ns != "serialisationformat"
                {
                    err_locs.push(ns_loc.clone());
                }
                let encodings = [
                    (
                        "fixedsizeinteger".to_string(),
                        SerialisationFormat::FixedSizeInteger,
                    ),
                    (
                        "variablesizedinteger".to_string(),
                        SerialisationFormat::VariableSizedInteger,
                    ),
                ];
                let enc_found = encodings
                    .iter()
                    .find_map(|(enc_str, enc)| (enc_str == enc_value).then_some(enc));
                if let Some(enc) = enc_found {
                    if err_locs.is_empty() {
                        Ok(*enc)
                    } else {
                        Err(HeaderError {
                            kind: HeaderErrorKind::InvalidEntry("serialisation_format"),
                            locations: err_locs,
                        })
                    }
                } else {
                    err_locs.push(enc_value_loc.clone());
                    Err(HeaderError {
                        kind: HeaderErrorKind::InvalidEntry("serialisation_format"),
                        locations: err_locs,
                    })
                }
            }
            val => {
                err_locs.push(val.primary_location().clone());
                Err(HeaderError {
                    kind: HeaderErrorKind::InvalidEntry("serialisation_format"),
                    locations: err_locs,
                })
            }
        }
    }
}

// We export this for generated code to refer to.
#[doc(hidden)]
pub use wincode;

/// A `CTParserBuilder` allows one to specify the criteria for building a statically generated
/// parser.
pub struct CTParserBuilder<'a, LexerTypesT: LexerTypes>
where
    LexerTypesT::StorageT: Eq + Hash,
    usize: AsPrimitive<LexerTypesT::StorageT>,
{
    // Anything stored in here (except `output_path`, `conflicts`, and `error_on_conflict`) almost
    // certainly needs to be included as part of the rebuild_cache function below so that, if it's
    // changed, the grammar is rebuilt.
    grammar_path: Option<PathBuf>,
    // If specified rather than reading source from `grammar_path`, use this string directly
    grammar_src: Option<String>,
    // If specified along with `grammar_src`, use this rather than building an ast from `grammar_src`.
    from_ast: Option<ASTWithValidityInfo>,
    output_path: Option<PathBuf>,
    mod_name: Option<&'a str>,
    recoverer: Option<RecoveryKind>,
    yacckind: Option<YaccKind>,
    error_on_conflicts: bool,
    warnings_are_errors: bool,
    show_warnings: bool,
    visibility: Visibility,
    rust_edition: RustEdition,
    inspect_rt: Option<
        Box<
            dyn for<'b> FnMut(
                &'b mut Header<Location>,
                RTParserBuilder<LexerTypesT::StorageT, LexerTypesT>,
                &'b HashMap<String, LexerTypesT::StorageT>,
                &PathBuf,
            ) -> Result<(), Box<dyn Error>>,
        >,
    >,
    serialisation_format: Option<SerialisationFormat>,
    // test function for inspecting private state
    #[cfg(test)]
    inspect_callback: Option<Box<dyn Fn(RecoveryKind) -> Result<(), Box<dyn Error>>>>,
    phantom: PhantomData<LexerTypesT>,
}

/// Defaults to `wincode::int_encoding::VarInt`.
pub(crate) type FixIntConfig = wincode::config::Configuration;
/// The default config with the last parameter set to `VarInt`
pub(crate) type VarIntConfig = wincode::config::Configuration<
    true,
    4194304,
    wincode::len::BincodeLen,
    wincode::int_encoding::LittleEndian,
    wincode::int_encoding::VarInt,
>;

impl<
    'a,
    StorageT: 'static
        + Debug
        + Hash
        + PrimInt
        + SchemaWrite<FixIntConfig, Src = StorageT>
        + SchemaWrite<VarIntConfig, Src = StorageT>
        + Unsigned,
    LexerTypesT: LexerTypes<StorageT = StorageT>,
> CTParserBuilder<'a, LexerTypesT>
where
    usize: AsPrimitive<StorageT>,
{
    /// Create a new `CTParserBuilder`.
    ///
    /// `StorageT` must be an unsigned integer type (e.g. `u8`, `u16`) which is:
    ///   * big enough to index (separately) all the tokens, rules, productions in the grammar,
    ///   * big enough to index the state table created from the grammar,
    ///   * less than or equal in size to `u32`.
    ///
    /// In other words, if you have a grammar with 256 tokens, 256 rules, and 256 productions,
    /// which creates a state table of 256 states you can safely specify `u8` here; but if any of
    /// those counts becomes 257 or greater you will need to specify `u16`. If you are parsing
    /// large files, the additional storage requirements of larger integer types can be noticeable,
    /// and in such cases it can be worth specifying a smaller type. `StorageT` defaults to `u32`
    /// if unspecified.
    ///
    /// # Examples
    ///
    /// ```text
    /// CTParserBuilder::<DefaultLexerTypes<u8>>::new()
    ///     .grammar_in_src_dir("grm.y")?
    ///     .build()?;
    /// ```
    pub fn new() -> Self {
        CTParserBuilder {
            grammar_path: None,
            grammar_src: None,
            from_ast: None,
            output_path: None,
            mod_name: None,
            recoverer: None,
            yacckind: None,
            error_on_conflicts: true,
            warnings_are_errors: true,
            show_warnings: true,
            visibility: Visibility::Private,
            rust_edition: RustEdition::Rust2021,
            inspect_rt: None,
            serialisation_format: None,
            #[cfg(test)]
            inspect_callback: None,
            phantom: PhantomData,
        }
    }

    /// Set the input grammar path to a file relative to this project's `src` directory. This will
    /// also set the output path (i.e. you do not need to call [CTParserBuilder::output_path]).
    ///
    /// For example if `a/b.y` is passed as `inp` then [CTParserBuilder::build] will:
    ///   * use `src/a/b.y` as the input file.
    ///   * write output to a file which can then be imported by calling `lrpar_mod!("a/b.y")`.
    ///   * create a module in that output file named `b_y`.
    ///
    /// You can override the output path and/or module name by calling [CTParserBuilder::output_path]
    /// and/or [CTParserBuilder::mod_name], respectively, after calling this function.
    ///
    /// This is a convenience function that makes it easier to compile grammar files stored in a
    /// project's `src/` directory: please see [CTParserBuilder::build] for additional constraints
    /// and information about the generated files. Note also that each `.y` file can only be
    /// processed once using this function: if you want to generate multiple grammars from a single
    /// `.y` file, you will need to use [CTParserBuilder::output_path].
    pub fn grammar_in_src_dir<P>(mut self, srcp: P) -> Result<Self, Box<dyn Error>>
    where
        P: AsRef<Path>,
    {
        if !srcp.as_ref().is_relative() {
            return Err(format!(
                "Grammar path '{}' must be a relative path.",
                srcp.as_ref().to_str().unwrap_or("<invalid UTF-8>")
            )
            .into());
        }

        let mut grmp = current_dir()?;
        grmp.push("src");
        grmp.push(srcp.as_ref());
        self.grammar_path = Some(grmp);

        let mut outp = PathBuf::new();
        outp.push(var("OUT_DIR").unwrap());
        outp.push(srcp.as_ref().parent().unwrap().to_str().unwrap());
        create_dir_all(&outp)?;
        let mut leaf = srcp
            .as_ref()
            .file_name()
            .unwrap()
            .to_str()
            .unwrap()
            .to_owned();
        write!(leaf, ".{}", RUST_FILE_EXT).ok();
        outp.push(leaf);
        Ok(self.output_path(outp))
    }

    /// If set, specifies that this grammar should be built from a pre-validated AST
    /// instead of a `.y`` file. When this is specified, `grammar_path` will not be read.
    #[cfg(feature = "_unstable_api")]
    pub fn grammar_ast(mut self, valid_ast: ASTWithValidityInfo, _api_key: UnstableApi) -> Self {
        self.from_ast = Some(valid_ast);
        self
    }

    /// Set the input grammar path to `inp`. If specified, you must also call
    /// [CTParserBuilder::output_path]. In general it is easier to use
    /// [CTParserBuilder::grammar_in_src_dir].
    pub fn grammar_path<P>(mut self, inp: P) -> Self
    where
        P: AsRef<Path>,
    {
        self.grammar_path = Some(inp.as_ref().to_owned());
        self
    }

    #[cfg(feature = "_unstable_api")]
    pub fn with_grammar_src(mut self, src: String, _api_key: UnstableApi) -> Self {
        self.grammar_src = Some(src);
        self
    }

    /// Set the output grammar path to `outp`. Note that there are no requirements on `outp`: the
    /// file can exist anywhere you can create a valid [Path] to. However, if you wish to use
    /// [crate::lrpar_mod!] you will need to make sure that `outp` is in
    /// [std::env::var]`("OUT_DIR")` or one of its subdirectories.
    pub fn output_path<P>(mut self, outp: P) -> Self
    where
        P: AsRef<Path>,
    {
        self.output_path = Some(outp.as_ref().to_owned());
        self
    }

    /// Set the generated module name to `mod_name`. If no module name is specified,
    /// [CTParserBuilder::build] will attempt to create a sensible default based on the grammar
    /// filename.
    pub fn mod_name(mut self, mod_name: &'a str) -> Self {
        self.mod_name = Some(mod_name);
        self
    }

    /// Set the visibility of the generated module to `vis`. Defaults to `Visibility::Private`.
    pub fn visibility(mut self, vis: Visibility) -> Self {
        self.visibility = vis;
        self
    }

    /// Set the recoverer for this parser to `rk`. Defaults to `RecoveryKind::CPCTPlus`.
    pub fn recoverer(mut self, rk: RecoveryKind) -> Self {
        self.recoverer = Some(rk);
        self
    }

    /// Set the `YaccKind` for this parser to `ak`.
    pub fn yacckind(mut self, yk: YaccKind) -> Self {
        self.yacckind = Some(yk);
        self
    }

    /// If set to true, [CTParserBuilder::build] will return an error if the given grammar contains
    /// any Shift/Reduce or Reduce/Reduce conflicts. Defaults to `true`.
    pub fn error_on_conflicts(mut self, b: bool) -> Self {
        self.error_on_conflicts = b;
        self
    }

    /// If set to true, [CTParserBuilder::build] will return an error if the given grammar contains
    /// any warnings. Defaults to `true`.
    pub fn warnings_are_errors(mut self, b: bool) -> Self {
        self.warnings_are_errors = b;
        self
    }

    /// If set to true, [CTParserBuilder::build] will print warnings to stderr, or via cargo when
    /// running under cargo. Defaults to `true`.
    pub fn show_warnings(mut self, b: bool) -> Self {
        self.show_warnings = b;
        self
    }

    /// Sets the rust edition to be used for generated code. Defaults to the latest edition of
    /// rust supported by grmtools.
    pub fn rust_edition(mut self, edition: RustEdition) -> Self {
        self.rust_edition = edition;
        self
    }

    pub fn serialisation_format(mut self, serialisation_format: SerialisationFormat) -> Self {
        self.serialisation_format = Some(serialisation_format);
        self
    }

    #[cfg(test)]
    pub fn inspect_recoverer(
        mut self,
        cb: Box<dyn for<'h, 'y> Fn(RecoveryKind) -> Result<(), Box<dyn Error>>>,
    ) -> Self {
        self.inspect_callback = Some(cb);
        self
    }

    #[doc(hidden)]
    pub fn inspect_rt(
        mut self,
        cb: Box<
            dyn for<'b, 'y> FnMut(
                &'b mut Header<Location>,
                RTParserBuilder<'y, StorageT, LexerTypesT>,
                &'b HashMap<String, StorageT>,
                &PathBuf,
            ) -> Result<(), Box<dyn Error>>,
        >,
    ) -> Self {
        self.inspect_rt = Some(cb);
        self
    }

    /// Statically compile the Yacc file specified by [CTParserBuilder::grammar_path()] into Rust,
    /// placing the output into the file spec [CTParserBuilder::output_path()]. Note that three
    /// additional files will be created with the same name as specified in [self.output_path] but
    /// with the extensions `grm`, and `stable`, overwriting any existing files with those names.
    ///
    /// If `%parse-param` is not specified, the generated module follows the form:
    ///
    /// ```text
    ///   mod <modname> {
    ///     pub fn parse<'lexer, 'input: 'lexer>(lexer: &'lexer dyn NonStreamingLexer<...>)
    ///       -> (Option<ActionT>, Vec<LexParseError<...>> { ... }
    ///
    ///     pub fn token_epp<'a>(tidx: ::cfgrammar::TIdx<StorageT>) -> ::std::option::Option<&'a str> {
    ///       ...
    ///     }
    ///
    ///     ...
    ///   }
    /// ```
    ///
    /// If `%parse-param x: t` is specified, the generated module follows the form:
    ///
    /// ```text
    ///   mod <modname> {
    ///     pub fn parse<'lexer, 'input: 'lexer>(lexer: &'lexer dyn NonStreamingLexer<...>, x: t)
    ///       -> (Option<ActionT>, Vec<LexParseError<...>> { ... }
    ///
    ///     pub fn token_epp<'a>(tidx: ::cfgrammar::TIdx<StorageT>) -> ::std::option::Option<&'a str> {
    ///       ...
    ///     }
    ///
    ///     ...
    ///   }
    /// ```
    ///
    /// where:
    ///  * `modname` is either:
    ///    * the module name specified by [CTParserBuilder::mod_name()];
    ///    * or, if no module name was explicitly specified, then for the file `/a/b/c.y` the
    ///      module name is `c_y` (i.e. the file's leaf name, minus its extension, with a prefix of
    ///      `_y`).
    ///  * `ActionT` is either:
    ///    * if the `yacckind` was set to `YaccKind::GrmTools` or
    ///      `YaccKind::Original(YaccOriginalActionKind::UserAction)`, it is
    ///      the return type of the `%start` rule;
    ///    * or, if the `yacckind` was set to
    ///      `YaccKind::Original(YaccOriginalActionKind::GenericParseTree)`, it
    ///      is `Node<StorageT>` where the `Node` type is defined within your `lrpar_mod!`.
    ///
    /// # Panics
    ///
    /// If `StorageT` is not big enough to index the grammar's tokens, rules, or productions.
    pub fn build(mut self) -> Result<CTParser<StorageT>, Box<dyn Error>> {
        let grmp = self
            .grammar_path
            .as_ref()
            .expect("grammar_path must be specified before processing.");
        let outp = self
            .output_path
            .as_ref()
            .expect("output_path must be specified before processing.");
        let mut header = Header::new();

        match header.entry("cfgrammar.yacckind".to_string()) {
            Entry::Occupied(_) => unreachable!(),
            Entry::Vacant(mut v) => match self.yacckind {
                Some(YaccKind::Eco) => panic!("Eco compile-time grammar generation not supported."),
                Some(yk) => {
                    let yk_value = Value::try_from(yk)?;
                    let mut o = v.insert_entry(HeaderValue(
                        Location::Other("CTParserBuilder".to_string()),
                        yk_value,
                    ));
                    o.set_merge_behavior(MergeBehavior::Ours);
                }
                None => {
                    v.mark_required();
                }
            },
        }
        if let Some(recoverer) = self.recoverer {
            match header.entry("lrpar.recoverer".to_string()) {
                Entry::Occupied(_) => unreachable!(),
                Entry::Vacant(v) => {
                    let rk_value: Value<Location> = Value::try_from(recoverer)?;
                    let mut o = v.insert_entry(HeaderValue(
                        Location::Other("CTParserBuilder".to_string()),
                        rk_value,
                    ));
                    o.set_merge_behavior(MergeBehavior::Ours);
                }
            }
        }

        if let Some(encoding) = self.serialisation_format {
            match header.entry("lrpar.serialisation_format".to_string()) {
                Entry::Occupied(_) => unreachable!(),
                Entry::Vacant(v) => {
                    let rk_value: Value<Location> = Value::try_from(encoding)?;
                    let mut o = v.insert_entry(HeaderValue(
                        Location::Other("CTParserBuilder".to_string()),
                        rk_value,
                    ));
                    o.set_merge_behavior(MergeBehavior::Ours);
                }
            }
        }

        {
            let mut lk = GENERATED_PATHS.lock().unwrap();
            if lk.contains(outp.as_path()) {
                return Err(format!("Generating two parsers to the same path ('{}') is not allowed: use CTParserBuilder::output_path (and, optionally, CTParserBuilder::mod_name) to differentiate them.", outp.to_str().unwrap()).into());
            }
            lk.insert(outp.clone());
        }

        let inc = if let Some(grammar_src) = &self.grammar_src {
            grammar_src.clone()
        } else {
            read_to_string(grmp).map_err(|e| format!("When reading '{}': {e}", grmp.display()))?
        };

        let src_env = ParserSrcEnv::new_with_header(&inc, Some(grmp), header);
        let yacc_diag = SpannedDiagnosticFormatter::new(&inc, grmp);
        let build_args = ParserBuildEnvArgs::new()
            .ast_with_validity_info(self.from_ast.as_ref())
            .mod_name(self.mod_name)
            .show_warnings(self.show_warnings)
            .error_on_conflicts(self.error_on_conflicts)
            .warnings_are_errors(self.warnings_are_errors)
            .visibility(self.visibility.clone())
            .rust_edition(self.rust_edition);
        let mut build_env = src_env.build_env(build_args).map_err(|e| match e {
            ParserSrcEnvError::GrmtoolsSectionParseError(es) => {
                let mut out = String::new();
                out.push_str(&format!(
                    "\n{ERROR}{}\n",
                    yacc_diag.file_location_msg(" parsing the `%grmtools` section", None)
                ));
                for e in es {
                    out.push_str(&indent("     ", &yacc_diag.format_error(e).to_string()));
                    out.push('\n');
                }
                Box::<dyn Error>::from(ErrorString(out))
            }
            e => e.to_string().into(),
        })?;
        // Temporarily we update self.yacckind and self.recoverer from the build_env
        // Until codegen reads these variables from the build_env directly.
        self.recoverer = Some(build_env.recoverer());
        self.yacckind = Some(build_env.yacc_kind());

        let warnings = build_env.ast_with_validity_info().ast().warnings();
        if self.warnings_are_errors && !warnings.is_empty() {
            let mut out = String::new();
            out.push_str(&format!(
                "\n{ERROR}{}\n",
                yacc_diag.file_location_msg("", None)
            ));
            for e in warnings {
                out.push_str(&format!(
                    "{}\n",
                    indent("     ", &yacc_diag.format_warning(e).to_string())
                ));
            }
            return Err(ErrorString(out).into());
        } else if !warnings.is_empty() {
            for w in warnings {
                let ws_loc = yacc_diag.file_location_msg("", None);
                let ws = indent("     ", &yacc_diag.format_warning(w).to_string());
                // Assume if this variable is set we are running under cargo.
                if std::env::var("OUT_DIR").is_ok() && self.show_warnings {
                    for line in ws_loc.lines().chain(ws.lines()) {
                        println!("cargo:warning={}", line);
                    }
                } else if self.show_warnings {
                    eprintln!("{}", ws_loc);
                    eprintln!("{WARNING} {}", ws);
                }
            }
        }

        #[cfg(test)]
        if let Some(cb) = &self.inspect_callback {
            cb(build_env.recoverer())?;
        }

        let timestamp = env!("VERGEN_BUILD_TIMESTAMP");
        let code_gen = build_env.code_generator(timestamp).map_err(|e| match e {
            ParserBuildEnvError::YaccGrammarErrors(errs) => {
                let mut out = String::new();
                out.push_str(&format!(
                    "\n{ERROR}{}\n",
                    yacc_diag.file_location_msg("", None)
                ));
                for e in errs {
                    out.push_str(&indent("     ", &yacc_diag.format_error(e).to_string()));
                    out.push('\n');
                }
                ErrorString(out)
            }
            e => ErrorString(e.to_string()),
        })?;
        let grm = code_gen.grm();
        let rule_ids = grm
            .tokens_map()
            .iter()
            .map(|(&n, &i)| (n.to_owned(), i.as_storaget()))
            .collect::<HashMap<_, _>>();

        let cache = code_gen.cache_str(&build_env);

        // We don't need to go through the full rigmarole of generating an output file if all of
        // the following are true: the output file exists; it is newer than the input file; and the
        // cache hasn't changed. The last of these might be surprising, but it's vital: we don't
        // know, for example, what the IDs map might be from one run to the next, and it might
        // change for reasons beyond lrpar's control. If it does change, that means that the lexer
        // and lrpar would get out of sync, so we have to play it safe and regenerate in such
        // cases.
        if let Ok(ref inmd) = fs::metadata(grmp)
            && let Ok(ref out_rs_md) = fs::metadata(outp)
            && FileTime::from_last_modification_time(out_rs_md)
                > FileTime::from_last_modification_time(inmd)
            && let Ok(outc) = read_to_string(outp)
        {
            if outc.contains(&cache) {
                let (grm, _, _) = code_gen.finish();

                return Ok(CTParser {
                    regenerated: false,
                    rule_ids,
                    yacc_grammar: grm,
                    grammar_src: inc,
                    grammar_path: self.grammar_path.unwrap(),
                    conflicts: None,
                });
            } else {
                #[cfg(grmtools_extra_checks)]
                if std::env::var("CACHE_EXPECTED").is_ok() {
                    eprintln!("outc: {}", outc);
                    eprintln!("using cache: {}", cache,);
                    // Primarily for use in the testsuite.
                    panic!("The cache regenerated however, it was expected to match");
                }
            }
        }

        // At this point, we know we're going to generate fresh output; however, if something goes
        // wrong in the process between now and us writing /out/blah.rs, rustc thinks that
        // everything's gone swimmingly (even if build.rs errored!), and tries to carry on
        // compilation, leading to weird errors. We therefore delete /out/blah.rs at this point,
        // which means, at worse, the user gets a "file not found" error from rustc (which is less
        // confusing than the alternatives).
        fs::remove_file(outp).ok();

        let stable = code_gen.stable();
        if self.error_on_conflicts
            && let Some(c) = stable.conflicts()
        {
            match (grm.expect(), grm.expectrr()) {
                (Some(i), Some(j)) if i == c.sr_len() && j == c.rr_len() => (),
                (Some(i), None) if i == c.sr_len() && 0 == c.rr_len() => (),
                (None, Some(j)) if 0 == c.sr_len() && j == c.rr_len() => (),
                (None, None) if 0 == c.rr_len() && 0 == c.sr_len() => (),
                _ => {
                    let conflicts_diagnostic = yacc_diag.format_conflicts::<LexerTypesT>(
                        grm,
                        build_env.ast_with_validity_info().ast(),
                        c,
                        code_gen.sgraph(),
                        stable,
                    );
                    #[cfg(test)]
                    let (_, _, stable) = code_gen.finish();
                    return Err(Box::new(CTConflictsError {
                        conflicts_diagnostic,
                        phantom: PhantomData,
                        #[cfg(test)]
                        stable,
                    }));
                }
            }
        }

        if let Some(ref mut inspector_rt) = self.inspect_rt {
            let rt: RTParserBuilder<'_, StorageT, LexerTypesT> = RTParserBuilder::new(grm, stable);
            let rt = if let Some(rk) = self.recoverer {
                rt.recoverer(rk)
            } else {
                rt
            };
            inspector_rt(build_env.header_mut(), rt, &rule_ids, grmp)?
        }

        build_env
            .check_unused_header_keys()
            .map_err(|e| ErrorString(e.to_string()))?;

        self.output_file(
            &code_gen,
            outp,
            &format!("/* CACHE INFORMATION {} */\n", cache),
            &build_env,
        )?;
        let (grm, sgraph, stable) = code_gen.finish();
        let conflicts = if stable.conflicts().is_some() {
            Some((sgraph, stable))
        } else {
            None
        };
        Ok(CTParser {
            regenerated: true,
            rule_ids,
            yacc_grammar: grm,
            grammar_src: inc,
            grammar_path: self.grammar_path.unwrap(),
            conflicts,
        })
    }

    /// Given the filename `a/b.y` as input, statically compile the grammar `src/a/b.y` into a Rust
    /// module which can then be imported using `lrpar_mod!("a/b.y")`. This is a convenience
    /// function around [`process_file`](#method.process_file) which makes it easier to compile
    /// grammar files stored in a project's `src/` directory: please see
    /// [`process_file`](#method.process_file) for additional constraints and information about the
    /// generated files.
    #[deprecated(
        since = "0.11.0",
        note = "Please use grammar_in_src_dir(), build(), and token_map() instead"
    )]
    #[allow(deprecated)]
    pub fn process_file_in_src(
        &mut self,
        srcp: &str,
    ) -> Result<HashMap<String, StorageT>, Box<dyn Error>> {
        let mut inp = current_dir()?;
        inp.push("src");
        inp.push(srcp);
        let mut outp = PathBuf::new();
        outp.push(var("OUT_DIR").unwrap());
        outp.push(Path::new(srcp).parent().unwrap().to_str().unwrap());
        create_dir_all(&outp)?;
        let mut leaf = Path::new(srcp)
            .file_name()
            .unwrap()
            .to_str()
            .unwrap()
            .to_owned();
        write!(leaf, ".{}", RUST_FILE_EXT).ok();
        outp.push(leaf);
        self.process_file(inp, outp)
    }

    /// Statically compile the Yacc file `inp` into Rust, placing the output into the file `outp`.
    /// Note that three additional files will be created with the same name as `outp` but with the
    /// extensions `grm`, and `stable`, overwriting any existing files with those names.
    ///
    /// `outp` defines a module as follows:
    ///
    /// ```text
    ///   mod modname {
    ///     pub fn parse(lexemes: &::std::vec::Vec<::lrpar::Lexeme<StorageT>>) { ... }
    ///         -> (::std::option::Option<ActionT>,
    ///             ::std::vec::Vec<::lrpar::LexParseError<StorageT>>)> { ...}
    ///
    ///     pub fn token_epp<'a>(tidx: ::cfgrammar::TIdx<StorageT>) -> ::std::option::Option<&'a str> {
    ///       ...
    ///     }
    ///
    ///     ...
    ///   }
    /// ```
    ///
    /// where:
    ///  * `modname` is either:
    ///    * the module name specified [`mod_name`](#method.mod_name)
    ///    * or, if no module name was explicitly specified, then for the file `/a/b/c.y` the
    ///      module name is `c_y` (i.e. the file's leaf name, minus its extension, with a prefix of
    ///      `_y`).
    ///  * `ActionT` is either:
    ///    * the `%actiontype` value given to the grammar
    ///    * or, if the `yacckind` was set YaccKind::Original(YaccOriginalActionKind::UserAction),
    ///      it is [`Node<StorageT>`](../parser/enum.Node.html)
    ///
    /// # Panics
    ///
    /// If `StorageT` is not big enough to index the grammar's tokens, rules, or
    /// productions.
    #[deprecated(
        since = "0.11.0",
        note = "Please use grammar_path(), output_path(), build(), and token_map() instead"
    )]
    pub fn process_file<P, Q>(
        &mut self,
        inp: P,
        outp: Q,
    ) -> Result<HashMap<String, StorageT>, Box<dyn Error>>
    where
        P: AsRef<Path>,
        Q: AsRef<Path>,
    {
        self.grammar_path = Some(inp.as_ref().to_owned());
        self.output_path = Some(outp.as_ref().to_owned());
        let cl: CTParserBuilder<LexerTypesT> = CTParserBuilder {
            grammar_path: self.grammar_path.clone(),
            grammar_src: None,
            from_ast: None,
            output_path: self.output_path.clone(),
            mod_name: self.mod_name,
            recoverer: self.recoverer,
            yacckind: self.yacckind,
            error_on_conflicts: self.error_on_conflicts,
            warnings_are_errors: self.warnings_are_errors,
            show_warnings: self.show_warnings,
            visibility: self.visibility.clone(),
            rust_edition: self.rust_edition,
            inspect_rt: None,
            serialisation_format: self.serialisation_format,
            #[cfg(test)]
            inspect_callback: None,
            phantom: PhantomData,
        };
        Ok(cl.build()?.rule_ids)
    }

    fn output_file<P: AsRef<Path>>(
        &self,
        code_gen: &ParserCodegen<LexerTypesT>,
        outp_rs: P,
        cache: &str,
        build_env: &ParserBuildEnv<'_, LexerTypesT>,
    ) -> Result<(), Box<dyn Error>> {
        let outs = code_gen
            .generate(build_env)
            .map_err(|e| ErrorString(e.to_string()))?;
        let mut f = File::create(outp_rs)?;
        f.write_all(outs.as_bytes())?;
        f.write_all(cache.as_bytes())?;
        Ok(())
    }
}

/// Bundles `YaccGrammar` + `StateTable` so that generated parsers can hold
/// them in a `OnceLock` without naming `lrtable` directly.
#[doc(hidden)]
pub struct ParserData<StorageT: Eq + Hash> {
    grm: YaccGrammar<StorageT>,
    stable: StateTable<StorageT>,
}

impl<StorageT: Eq + Hash> ParserData<StorageT> {
    pub fn grm(&self) -> &YaccGrammar<StorageT> {
        &self.grm
    }

    pub fn stable(&self) -> &StateTable<StorageT> {
        &self.stable
    }
}

/// This function is called by generated files; it exists so that generated files don't require a
/// direct dependency on bincode.
#[doc(hidden)]
pub fn _reconstitute<
    C: wincode::config::Config + Clone + Copy,
    StorageT: SchemaReadOwned<C, Dst = StorageT> + Eq + Hash + PrimInt + Unsigned + 'static,
>(
    grm_buf: &[u8],
    stable_buf: &[u8],
    config: C,
) -> ParserData<StorageT> {
    let grm: YaccGrammar<StorageT> = wincode::config::deserialize_from(grm_buf, config).unwrap();
    let stable = wincode::config::deserialize_from(stable_buf, config).unwrap();
    ParserData { grm, stable }
}

/// An interface to the result of [CTParserBuilder::build()].
pub struct CTParser<StorageT = u32>
where
    StorageT: Eq + Hash,
{
    regenerated: bool,
    rule_ids: HashMap<String, StorageT>,
    yacc_grammar: YaccGrammar<StorageT>,
    grammar_src: String,
    grammar_path: PathBuf,
    conflicts: Option<(StateGraph<StorageT>, StateTable<StorageT>)>,
}

impl<StorageT> CTParser<StorageT>
where
    StorageT: 'static + Debug + Hash + PrimInt + Unsigned,
    usize: AsPrimitive<StorageT>,
{
    /// Returns `true` if this compile-time parser was regenerated or `false` if it was not.
    pub fn regenerated(&self) -> bool {
        self.regenerated
    }

    /// Returns a [HashMap] from lexeme string types to numeric types (e.g. `INT: 2`), suitable for
    /// handing to a lexer to coordinate the IDs of lexer and parser.
    pub fn token_map(&self) -> &HashMap<String, StorageT> {
        &self.rule_ids
    }

    /// If there are any conflicts in the grammar, return a tuple which allows users to inspect and
    /// pretty print them; otherwise returns `None`. If the grammar was not regenerated, this will
    /// always return `None`, even if the grammar actually has conflicts.
    ///
    /// **Note: The conflicts feature is currently unstable and may change in the future.**
    #[allow(private_interfaces)]
    pub fn conflicts(
        &self,
        _: crate::unstable::UnstableApi,
    ) -> Option<(
        &YaccGrammar<StorageT>,
        &StateGraph<StorageT>,
        &StateTable<StorageT>,
        &Conflicts<StorageT>,
    )> {
        if let Some((sgraph, stable)) = &self.conflicts {
            return Some((
                &self.yacc_grammar,
                sgraph,
                stable,
                stable.conflicts().unwrap(),
            ));
        }
        None
    }

    #[doc(hidden)]
    pub fn yacc_grammar(&self) -> &YaccGrammar<StorageT> {
        &self.yacc_grammar
    }
    #[doc(hidden)]
    pub fn grammar_src(&self) -> &str {
        &self.grammar_src
    }
    #[doc(hidden)]
    pub fn grammar_path(&self) -> &Path {
        self.grammar_path.as_path()
    }
}

/// Indents a multi-line string and trims any trailing newline.
/// This currently assumes that indentation on blank lines does not matter.
///
/// The algorithm used by this function is:
/// 1. Prefix `s` with the indentation, indenting the first line.
/// 2. Trim any trailing newlines.
/// 3. Replace all newlines with `\n{indent}`` to indent all lines after the first.
///
/// It is plausible that we should a step 4, but currently do not:
/// 4. Replace all `\n{indent}\n` with `\n\n`
pub(crate) fn indent(indent: &str, s: &str) -> String {
    format!("{indent}{}\n", s.trim_end_matches('\n')).replace('\n', &format!("\n{}", indent))
}

// Tests dealing with the filesystem not supported under wasm32
#[cfg(all(not(target_arch = "wasm32"), test))]
mod test {
    use std::{fs::File, io::Write, path::PathBuf};

    use super::{CTConflictsError, CTParserBuilder};
    use crate::test_utils::TestLexerTypes;
    use cfgrammar::yacc::{YaccKind, YaccOriginalActionKind};
    use tempfile::TempDir;

    #[test]
    fn test_conflicts() {
        let temp = TempDir::new().unwrap();
        let mut file_path = PathBuf::from(temp.as_ref());
        file_path.push("grm.y");
        let mut f = File::create(&file_path).unwrap();
        let _ = f.write_all(
            "%start A
%%
A : 'a' 'b' | B 'b';
B : 'a' | C;
C : 'a';"
                .as_bytes(),
        );

        match CTParserBuilder::<TestLexerTypes>::new()
            .error_on_conflicts(false)
            .yacckind(YaccKind::Original(YaccOriginalActionKind::GenericParseTree))
            .grammar_path(file_path.to_str().unwrap())
            .output_path(file_path.with_extension("ignored"))
            .build()
            .unwrap()
            .conflicts(crate::unstable::UnstableApi)
        {
            Some((_, _, _, conflicts)) => {
                assert_eq!(conflicts.sr_len(), 1);
                assert_eq!(conflicts.rr_len(), 1);
            }
            None => panic!("Expected error data"),
        }
    }

    #[test]
    fn test_conflicts_error() {
        let temp = TempDir::new().unwrap();
        let mut file_path = PathBuf::from(temp.as_ref());
        file_path.push("grm.y");
        let mut f = File::create(&file_path).unwrap();
        let _ = f.write_all(
            "%start A
%%
A : 'a' 'b' | B 'b';
B : 'a' | C;
C : 'a';"
                .as_bytes(),
        );

        match CTParserBuilder::<TestLexerTypes>::new()
            .yacckind(YaccKind::Original(YaccOriginalActionKind::GenericParseTree))
            .grammar_path(file_path.to_str().unwrap())
            .output_path(file_path.with_extension("ignored"))
            .build()
        {
            Ok(_) => panic!("Expected error"),
            Err(e) => {
                let cs = e.downcast_ref::<CTConflictsError<u16>>();
                assert_eq!(cs.unwrap().stable.conflicts().unwrap().rr_len(), 1);
                assert_eq!(cs.unwrap().stable.conflicts().unwrap().sr_len(), 1);
            }
        }
    }

    #[test]
    fn test_expect_error() {
        let temp = TempDir::new().unwrap();
        let mut file_path = PathBuf::from(temp.as_ref());
        file_path.push("grm.y");
        let mut f = File::create(&file_path).unwrap();
        let _ = f.write_all(
            "%start A
%expect 2
%%
A: 'a' 'b' | B 'b';
B: 'a';"
                .as_bytes(),
        );

        match CTParserBuilder::<TestLexerTypes>::new()
            .yacckind(YaccKind::Original(YaccOriginalActionKind::GenericParseTree))
            .grammar_path(file_path.to_str().unwrap())
            .output_path(file_path.with_extension("ignored"))
            .build()
        {
            Ok(_) => panic!("Expected error"),
            Err(e) => {
                let cs = e.downcast_ref::<CTConflictsError<u16>>();
                assert_eq!(cs.unwrap().stable.conflicts().unwrap().rr_len(), 0);
                assert_eq!(cs.unwrap().stable.conflicts().unwrap().sr_len(), 1);
            }
        }
    }

    #[test]
    fn test_expectrr_error() {
        let temp = TempDir::new().unwrap();
        let mut file_path = PathBuf::from(temp.as_ref());
        file_path.push("grm.y");
        let mut f = File::create(&file_path).unwrap();
        let _ = f.write_all(
            "%start A
%expect 1
%expect-rr 2
%%
A : 'a' 'b' | B 'b';
B : 'a' | C;
C : 'a';"
                .as_bytes(),
        );

        match CTParserBuilder::<TestLexerTypes>::new()
            .yacckind(YaccKind::Original(YaccOriginalActionKind::GenericParseTree))
            .grammar_path(file_path.to_str().unwrap())
            .output_path(file_path.with_extension("ignored"))
            .build()
        {
            Ok(_) => panic!("Expected error"),
            Err(e) => {
                let cs = e.downcast_ref::<CTConflictsError<u16>>();
                assert_eq!(cs.unwrap().stable.conflicts().unwrap().rr_len(), 1);
                assert_eq!(cs.unwrap().stable.conflicts().unwrap().sr_len(), 1);
            }
        }
    }

    #[test]
    /// Tests a yacc .y filename containing a dash character leading to an invalid rust identifier
    /// when that dash is subsequently used as the default `CTParserBuilder::mod_name`.
    fn test_invalid_identifier_in_derived_mod_name() {
        let temp = TempDir::new().unwrap();
        let mut file_path = PathBuf::from(temp.as_ref());
        file_path.push("contains-a-dash.y");
        let mut f = File::create(&file_path).unwrap();
        let _ = f.write_all(
            "%start A
%%
A : 'a';"
                .as_bytes(),
        );
        match CTParserBuilder::<TestLexerTypes>::new()
            .yacckind(YaccKind::Original(YaccOriginalActionKind::GenericParseTree))
            .grammar_path(file_path.to_str().unwrap())
            .output_path(file_path.with_extension("ignored"))
            .build()
        {
            Ok(_) => panic!("Expected error"),
            Err(e) => {
                let err_string = e.to_string();
                assert_eq!(
                    err_string,
                    "mod_name \'contains-a-dash_y\' is not a valid rust identifier due to 'unexpected token'"
                );
            }
        }
    }

    #[cfg(test)]
    #[test]
    fn test_recoverer_header() -> Result<(), Box<dyn std::error::Error>> {
        use crate::RecoveryKind as RK;
        #[rustfmt::skip]
            let recovery_kinds = [
                //  Builder,          Header setting,     Expected result.
                // -----------       ------------------  -------------------
                (Some(RK::None),      Some(RK::None),     Some(RK::None)),
                (Some(RK::None),      Some(RK::CPCTPlus), Some(RK::None)),
                (Some(RK::CPCTPlus),  Some(RK::CPCTPlus), Some(RK::CPCTPlus)),
                (Some(RK::CPCTPlus),  Some(RK::None),     Some(RK::CPCTPlus)),
                (None,                Some(RK::CPCTPlus), Some(RK::CPCTPlus)),
                (None,                Some(RK::None),     Some(RK::None)),
                (None,                None,               Some(RK::CPCTPlus)),
                (Some(RK::None),      None,               Some(RK::None)),
                (Some(RK::CPCTPlus),  None,               Some(RK::CPCTPlus)),
            ];

        for (i, (builder_arg, header_arg, expected_rk)) in
            recovery_kinds.iter().cloned().enumerate()
        {
            let y_src = if let Some(header_arg) = header_arg {
                format!(
                    "\
                    %grmtools{{yacckind: Original(NoAction), recoverer: {}}} \
                    %% \
                    start: ; \
                    ",
                    match header_arg {
                        RK::None => "RecoveryKind::None",
                        RK::CPCTPlus => "RecoveryKind::CPCTPlus",
                    }
                )
            } else {
                r#"
                    %grmtools{yacckind: Original(NoAction)}
                    %%
                    Start: ;
                    "#
                .to_string()
            };
            let out_dir = std::env::var("OUT_DIR").unwrap();
            let y_path = format!("{out_dir}/recoverykind_test_{i}.y");
            let y_out_path = format!("{y_path}.rs");
            std::fs::File::create(y_path.clone()).unwrap();
            std::fs::write(y_path.clone(), y_src).unwrap();
            let mut cp_builder = CTParserBuilder::<TestLexerTypes>::new();
            cp_builder = cp_builder
                .output_path(y_out_path.clone())
                .grammar_path(y_path.clone());
            cp_builder = if let Some(builder_arg) = builder_arg {
                cp_builder.recoverer(builder_arg)
            } else {
                cp_builder
            }
            .inspect_recoverer(Box::new(move |rk| {
                if matches!(
                    (rk, expected_rk),
                    (RK::None, Some(RK::None)) | (RK::CPCTPlus, Some(RK::CPCTPlus))
                ) {
                    Ok(())
                } else {
                    panic!("Unexpected recovery kind")
                }
            }));
            cp_builder.build()?;
        }
        Ok(())
    }
}