Document the synom parser macros
diff --git a/synom/src/helper.rs b/synom/src/helper.rs
index 7283e41..e4ada4b 100644
--- a/synom/src/helper.rs
+++ b/synom/src/helper.rs
@@ -1,6 +1,22 @@
use IResult;
use space::{skip_whitespace, word_break};
+/// Parse a piece of punctuation, skipping whitespace before it.
+///
+/// - **Syntax:** `punct!("...")`
+/// - **Output:** `&str`
+///
+/// ```rust
+/// extern crate syn;
+/// #[macro_use] extern crate synom;
+///
+/// named!(bang -> &str, punct!("!"));
+///
+/// fn main() {
+/// let input = " !";
+/// bang(input).expect("bang");
+/// }
+/// ```
#[macro_export]
macro_rules! punct {
($i:expr, $punct:expr) => {
@@ -19,6 +35,24 @@
}
}
+/// Parse a keyword. The word must make up a complete identifier.
+///
+/// - **Syntax:** `keyword!("...")`
+/// - **Output:** `&str`
+///
+/// ```rust
+/// extern crate syn;
+/// #[macro_use] extern crate synom;
+///
+/// named!(apple -> &str, keyword!("apple"));
+///
+/// fn main() {
+/// let input = " apple";
+/// apple(input).expect("apple");
+/// let input = "apples";
+/// assert_eq!(apple(input), synom::IResult::Error);
+/// }
+/// ```
#[macro_export]
macro_rules! keyword {
($i:expr, $keyword:expr) => {
@@ -40,6 +74,25 @@
}
}
+/// Try to run the parser and wrap it in an `Option`, if it fails, succeed but
+/// produce a `None`.
+///
+/// - **Syntax:** `option!(THING)`
+/// - **Output:** `THING`
+///
+/// ```rust
+/// extern crate syn;
+/// #[macro_use] extern crate synom;
+///
+/// named!(maybe_bang -> Option<&str>, option!(punct!("!")));
+///
+/// fn main() {
+/// let input = " !";
+/// assert_eq!(maybe_bang(input).expect("maybe bang"), Some("!"));
+/// let input = "";
+/// assert_eq!(maybe_bang(input).expect("maybe bang"), None);
+/// }
+/// ```
#[macro_export]
macro_rules! option {
($i:expr, $submac:ident!( $($args:tt)* )) => {
@@ -54,6 +107,33 @@
};
}
+/// Try to run the parser, if it fails, succeed and produce an empty Vec.
+///
+/// The argument parser must be a Vec.
+///
+/// - **Syntax:** `opt_vec!(THING)`
+/// - **Output:** `THING`
+///
+/// ```rust
+/// extern crate syn;
+/// #[macro_use] extern crate synom;
+///
+/// use syn::Expr;
+/// use syn::parse::expr;
+///
+/// named!(opt_expr_list -> Vec<Expr>, opt_vec!(
+/// separated_list!(punct!(","), expr)));
+///
+/// fn main() {
+/// let input = "a, 1 + 1, Object { construct: ion }";
+/// let result = opt_expr_list(input).expect("opt expr list");
+/// assert_eq!(result.len(), 3);
+///
+/// let input = "";
+/// let result = opt_expr_list(input).expect("opt expr list");
+/// assert_eq!(result.len(), 0);
+/// }
+/// ```
#[macro_export]
macro_rules! opt_vec {
($i:expr, $submac:ident!( $($args:tt)* )) => {
@@ -64,6 +144,21 @@
};
}
+/// Parses nothing and always succeeds.
+///
+/// - **Syntax:** `epsilon!()`
+/// - **Output:** `()`
+///
+/// ```rust
+/// #[macro_use] extern crate synom;
+///
+/// named!(epsi -> (), epsilon!());
+///
+/// fn main() {
+/// let input = "";
+/// assert_eq!(epsi(input).expect("maybe bang"), ());
+/// }
+/// ```
#[macro_export]
macro_rules! epsilon {
($i:expr,) => {
@@ -71,6 +166,40 @@
};
}
+/// Run a parser, binding the result to a name, and then evaluating an
+/// expression.
+///
+/// Discards the result of the expression and parser.
+///
+/// - **Syntax:** `tap!(NAME : THING => EXPR)`
+/// - **Output:** `()`
+///
+/// ```rust
+/// extern crate syn;
+/// #[macro_use] extern crate synom;
+///
+/// use syn::{Expr, ExprKind};
+/// use syn::parse::expr;
+///
+/// named!(pub expr_with_arrow_call -> Expr, do_parse!(
+/// mut e: expr >>
+/// many0!(tap!(arg: tuple!(punct!("=>"), expr) => {
+/// e = Expr {
+/// node: ExprKind::Call(Box::new(e), vec![arg.1]),
+/// attrs: Vec::new(),
+/// };
+/// })) >>
+/// (e)
+/// ));
+///
+/// fn main() {
+/// let input = "something => argument1 => argument2";
+///
+/// let result = expr_with_arrow_call(input).expect("expr with arrow call");
+///
+/// println!("result = {:?}", result);
+/// }
+/// ```
#[macro_export]
macro_rules! tap {
($i:expr, $name:ident : $submac:ident!( $($args:tt)* ) => $e:expr) => {
@@ -89,6 +218,32 @@
};
}
+/// Parses a series of things, separated by the given punctuation. Does not
+/// allow for a trailing seperator.
+///
+/// The implementation requires that the first parameter is a `punct!` macro,
+/// and the second is a named parser.
+///
+/// - **Syntax:** `separated_list!(punct!("..."), THING)`
+/// - **Output:** `Vec<THING>`
+///
+/// ```rust
+/// extern crate syn;
+/// #[macro_use] extern crate synom;
+///
+/// use syn::Expr;
+/// use syn::parse::expr;
+///
+/// named!(pub expr_list -> Vec<Expr>,
+/// separated_list!(punct!(","), expr));
+///
+/// fn main() {
+/// let input = "1 + 1, things, Construct { this: thing }";
+///
+/// let result = expr_list(input).expect("expr list");
+/// assert_eq!(result.len(), 3);
+/// }
+/// ```
#[macro_export]
macro_rules! separated_list {
($i:expr, punct!($sep:expr), $f:expr) => {
@@ -96,6 +251,32 @@
};
}
+/// Parses a series of things, separated by the given punctuation. Allows for
+/// a trailing seperator.
+///
+/// The implementation requires that the first parameter is a `punct!` macro,
+/// and the second is a named parser.
+///
+/// - **Syntax:** `terminated_list!(punct!("..."), THING)`
+/// - **Output:** `Vec<THING>`
+///
+/// ```rust
+/// extern crate syn;
+/// #[macro_use] extern crate synom;
+///
+/// use syn::Expr;
+/// use syn::parse::expr;
+///
+/// named!(pub expr_list -> Vec<Expr>,
+/// terminated_list!(punct!(","), expr));
+///
+/// fn main() {
+/// let input = "1 + 1, things, Construct { this: thing },";
+///
+/// let result = expr_list(input).expect("expr list");
+/// assert_eq!(result.len(), 3);
+/// }
+/// ```
#[macro_export]
macro_rules! terminated_list {
($i:expr, punct!($sep:expr), $f:expr) => {