diff --git a/src/ast/mod.rs b/src/ast/mod.rs index 29a1fab..7aeb56b 100644 --- a/src/ast/mod.rs +++ b/src/ast/mod.rs @@ -13,7 +13,6 @@ // limitations under the License. //! The definitions of the ucg AST and Tokens. - use std; use std::borrow::Borrow; use std::cmp::Eq; @@ -626,6 +625,7 @@ pub enum BinaryExprType { Div, } +/// CompareType signals the type of a comparison for a binary expression. #[derive(Debug, PartialEq, Clone)] pub enum CompareType { Equal, @@ -636,6 +636,7 @@ pub enum CompareType { LTEqual, } +/// ComparisonDef Represents a comparison between two expressions. #[derive(Debug, PartialEq, Clone)] pub struct ComparisonDef { pub kind: CompareType, @@ -676,12 +677,14 @@ pub struct ListDef { pub pos: Position, } +/// ListOpType represents the type of list operation for a ListOpDef. #[derive(Debug, PartialEq, Clone)] pub enum ListOpType { Map, Filter, } +/// ListOpDef implements the list operations in the UCG AST. #[derive(Debug, PartialEq, Clone)] pub struct ListOpDef { pub typ: ListOpType, diff --git a/src/build/mod.rs b/src/build/mod.rs index 9772b43..5a2160d 100644 --- a/src/build/mod.rs +++ b/src/build/mod.rs @@ -286,13 +286,14 @@ impl From for Val { /// Defines a set of values in a parsed file. type ValueMap = HashMap, Rc>; +/// AssertCollector collects the results of assertions in the UCG AST. pub struct AssertCollector { pub success: bool, pub summary: String, pub failures: String, } -/// Handles building ucg code. +/// Builder handles building ucg code. pub struct Builder { root: PathBuf, validate_mode: bool, @@ -432,6 +433,7 @@ impl Builder { Ok(()) } + /// Evaluate an input string as UCG. pub fn eval_string(&mut self, input: &str) -> Result, Box> { match parse(Span::new(input)) { Ok(stmts) => { @@ -453,18 +455,13 @@ impl Builder { } } - /// Builds a string of ucg syntax. - pub fn build_file_string(&mut self, input: String) -> BuildResult { - self.last = Some(try!(self.eval_string(&input))); - Ok(()) - } - /// Builds a ucg file at the named path. pub fn build_file(&mut self, name: &str) -> BuildResult { let mut f = try!(File::open(name)); let mut s = String::new(); try!(f.read_to_string(&mut s)); - self.build_file_string(s) + self.last = Some(try!(self.eval_string(&s))); + Ok(()) } fn build_import(&mut self, def: &ImportDef) -> Result, Box> { diff --git a/src/build/test.rs b/src/build/test.rs index b7dcb9b..7c79cb0 100644 --- a/src/build/test.rs +++ b/src/build/test.rs @@ -803,7 +803,7 @@ fn test_let_statement() { #[test] fn test_build_file_string() { let mut b = Builder::new(std::env::current_dir().unwrap()); - b.build_file_string("let foo = 1;".to_string()).unwrap(); + b.eval_string("let foo = 1;").unwrap(); let key = value_node!("foo".to_string(), 1, 0); assert!(b.out.contains_key(&key)); } diff --git a/src/convert/env.rs b/src/convert/env.rs index 2ecac4f..5086fc1 100644 --- a/src/convert/env.rs +++ b/src/convert/env.rs @@ -12,7 +12,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! An environment variable converter. +//! Contains code for converting a UCG Val into the environment variable output target. use std::io::Write; use std::rc::Rc; @@ -20,7 +20,8 @@ use ast::Positioned; use build::Val; use convert::traits::{Converter, Result}; -/// EnvConverter implements the conversion logic for converting a Val into a set of environment variables. +/// EnvConverter implements the conversion logic for converting a Val into a +/// set of environment variables. pub struct EnvConverter {} impl EnvConverter { diff --git a/src/convert/flags.rs b/src/convert/flags.rs index c606720..19206a3 100644 --- a/src/convert/flags.rs +++ b/src/convert/flags.rs @@ -19,7 +19,8 @@ use std::rc::Rc; use build::Val; use convert::traits::{Converter, Result}; -/// FlagConverter implements the conversion logic for converting a Val into a set of command line flags. +/// FlagConverter implements the conversion logic for converting a Val into a set +/// of command line flags. pub struct FlagConverter {} impl FlagConverter { diff --git a/src/lib.rs b/src/lib.rs index 150e3db..64d5dea 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,7 +17,7 @@ //! //! Ucg defines a common grammar for describing a collection of configuration values. //! ucg allows you to specify configuration values with a syntax that that is immutable, -//! comoposable with copy-on-write semantics, and safe. +//! composable, with copy-on-write semantics, and safe. //! //! ## Example //! diff --git a/src/parse/mod.rs b/src/parse/mod.rs index efe18dc..c3f9c4e 100644 --- a/src/parse/mod.rs +++ b/src/parse/mod.rs @@ -63,6 +63,7 @@ macro_rules! trace_nom { } }; } + fn symbol_to_value(s: &Token) -> ParseResult { Ok(Value::Symbol(value_node!( s.fragment.to_string(), @@ -134,6 +135,7 @@ fn triple_to_number(v: (Option, Option, Option)) -> ParseRe return Ok(Value::Float(value_node!(f, pref_pos))); } +/// alt_peek conditionally runs a combinator if a lookahead combinator matches. macro_rules! alt_peek { (__inner $i:expr, $peekrule:ident!( $($peekargs:tt)* ) => $parserule:ident | $($rest:tt)* ) => ( alt_peek!(__inner $i, $peekrule!($($peekargs)*) => call!($parserule) | $($rest)* ) @@ -291,7 +293,6 @@ named!(field_list, ); named!( - #[doc="Capture a tuple of named fields with values. {=,...}"], tuple, map_res!( do_parse!( @@ -334,7 +335,7 @@ named!(empty_value, ) ); -named!(pub compound_value, +named!(compound_value, alt_peek!( punct!("[") => trace_nom!(list_value) | punct!("{") => trace_nom!(tuple) @@ -350,7 +351,7 @@ named!(scalar_value, ) ); -named!(pub value, +named!(value, alt!( trace_nom!(selector_value) | trace_nom!(compound_value) @@ -733,7 +734,7 @@ named!(list_op_expression, ) ); -named!(pub non_op_expression, +named!(non_op_expression, alt!(trace_nom!(list_op_expression) | trace_nom!(macro_expression) | trace_nom!(format_expression) | @@ -744,7 +745,7 @@ named!(pub non_op_expression, trace_nom!(simple_expression)) ); -named!(pub expression, +named!(expression, alt_complete!(trace_nom!(op_expression) | trace_nom!(non_op_expression)) ); @@ -752,7 +753,7 @@ fn expression_to_statement(v: Expression) -> ParseResult { Ok(Statement::Expression(v)) } -named!(pub expression_statement, +named!(expression_statement, map_res!( terminated!(trace_nom!(expression), punct!(";")), expression_to_statement diff --git a/src/parse/precedence.rs b/src/parse/precedence.rs index d06f61b..0c427a6 100644 --- a/src/parse/precedence.rs +++ b/src/parse/precedence.rs @@ -11,6 +11,9 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. + +//! Bottom up parser for precedence parsing of expressions separated by binary +//! operators. use std; use nom::{ErrorKind, IResult, InputIter, InputLength, Slice}; @@ -20,6 +23,7 @@ use ast::*; use error; use tokenizer::TokenIter; +/// Defines the intermediate stages of our bottom up parser for precedence parsing. #[derive(Debug, PartialEq, Clone)] pub enum Element { Expr(Expression), @@ -27,7 +31,7 @@ pub enum Element { CompareOp(CompareType), } -named!(pub math_op_type, +named!(math_op_type, alt!( do_parse!(punct!("+") >> (Element::MathOp(BinaryExprType::Add))) | do_parse!(punct!("-") >> (Element::MathOp(BinaryExprType::Sub))) | @@ -180,19 +184,19 @@ macro_rules! do_binary_expr { }; } -named!(pub sum_expression, +named!(sum_expression, do_binary_expr!( parse_sum_operator, alt!(trace_nom!(product_expression) | trace_nom!(parse_expression))) ); -named!(pub product_expression, +named!(product_expression, do_binary_expr!( parse_product_operator, trace_nom!(parse_expression)) ); -named!(pub math_expression, +named!(math_expression, alt!(trace_nom!(sum_expression) | trace_nom!(product_expression)) ); @@ -209,7 +213,7 @@ fn tuple_to_compare_expression( })) } -named!(pub compare_op_type, +named!(compare_op_type, alt!( do_parse!(punct!("==") >> (Element::CompareOp(CompareType::Equal))) | do_parse!(punct!("!=") >> (Element::CompareOp(CompareType::NotEqual))) | @@ -245,7 +249,7 @@ fn parse_compare_operator(i: OpListIter) -> IResult, +named!(compare_expression, map_res!( do_parse!( left: alt!(trace_nom!(math_expression) | trace_nom!(parse_expression)) >> @@ -258,8 +262,8 @@ named!(pub compare_expression, ) ); -// Implement nom::Input Length and nom::Slice for OpListIter. -pub fn parse_operand_list(i: TokenIter) -> NomResult> { +/// Parse a list of expressions separated by operators into a Vec. +fn parse_operand_list(i: TokenIter) -> NomResult> { // 1. First try to parse a non_op_expression, let mut _i = i.clone(); let mut list = Vec::new(); @@ -390,6 +394,7 @@ impl<'a> InputIter for OpListIter<'a> { } } +/// Parse a binary operator expression. pub fn op_expression(i: TokenIter) -> NomResult { let preparse = parse_operand_list(i.clone()); match preparse { diff --git a/src/tokenizer/mod.rs b/src/tokenizer/mod.rs index 6a094cc..5b2b9a7 100644 --- a/src/tokenizer/mod.rs +++ b/src/tokenizer/mod.rs @@ -420,6 +420,9 @@ pub fn tokenize(input: Span) -> Result, (Position, nom::ErrorKind)> { Ok(out) } +/// Clones a token. +/// +/// This is necessary to allow the match_type and match_token macros to work. pub fn token_clone(t: &Token) -> Result { Ok(t.clone()) }