Struct CTParserBuilder

pub struct CTParserBuilder<'a, LexerTypesT: LexerTypes>
where
    LexerTypesT::StorageT: Eq + Hash,
    usize: AsPrimitive<LexerTypesT::StorageT>,
{ /* private fields */ }

A CTParserBuilder allows one to specify the criteria for building a statically generated parser.

Implementations

impl<'a, StorageT: 'static + Debug + Hash + PrimInt + Encode + Unsigned, LexerTypesT: LexerTypes<StorageT = StorageT>> CTParserBuilder<'a, LexerTypesT>

where usize: AsPrimitive<StorageT>,

pub fn new() -> Self

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

CTParserBuilder::<DefaultLexerTypes<u8>>::new()
    .grammar_in_src_dir("grm.y")?
    .build()?;

pub fn grammar_in_src_dir<P>(self, srcp: P) -> Result<Self, Box<dyn Error>>

where P: AsRef<Path>,

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_path<P>(self, inp: P) -> Self

where P: AsRef<Path>,

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 output_path<P>(self, outp: P) -> Self

where P: AsRef<Path>,

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 mod_name(self, mod_name: &'a str) -> 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 visibility(self, vis: Visibility) -> Self

Set the visibility of the generated module to vis. Defaults to Visibility::Private.

pub fn recoverer(self, rk: RecoveryKind) -> Self

Set the recoverer for this parser to rk. Defaults to RecoveryKind::CPCTPlus.

pub fn yacckind(self, yk: YaccKind) -> Self

Set the YaccKind for this parser to ak.

pub fn error_on_conflicts(self, b: bool) -> 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 warnings_are_errors(self, b: bool) -> Self

If set to true, CTParserBuilder::build will return an error if the given grammar contains any warnings. Defaults to true.

pub fn show_warnings(self, b: bool) -> Self

If set to true, CTParserBuilder::build will print warnings to stderr, or via cargo when running under cargo. Defaults to true.

pub fn rust_edition(self, edition: RustEdition) -> Self

Sets the rust edition to be used for generated code. Defaults to the latest edition of rust supported by grmtools.

pub fn build(self) -> Result<CTParser<StorageT>, Box<dyn Error>>

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:

  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:

  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 process_file_in_src( &mut self, srcp: &str, ) -> Result<HashMap<String, StorageT>, Box<dyn Error>>

👎Deprecated since 0.11.0: Please use grammar_in_src_dir(), build(), and token_map() instead

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 which makes it easier to compile grammar files stored in a project’s src/ directory: please see process_file for additional constraints and information about the generated files.

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>,

👎Deprecated since 0.11.0: Please use grammar_path(), output_path(), build(), and token_map() instead

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:

  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
  • 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>

Panics

If StorageT is not big enough to index the grammar’s tokens, rules, or productions.