Repository: Geal/nom
Pull request #793 (2018-06-16 10:20:30)

Simplify aliasing in docs

coveralls: 
[![Coverage Status](https://coveralls.io/builds/17527968/badge)](https://coveralls.io/builds/17527968)

Coverage decreased (-0.02%) to 87.542% when pulling **bf5fa07b80ad569fc1576082e628077b143afe8e on RReverser:patch-1** into **64af2d1cac7298b511eb671163dcdbb2ad197d17 on Geal:master**.


Patch:
diff --git a/doc/how_nom_macros_work.md b/doc/how_nom_macros_work.md
index 578f63f..5f5c97f 100644
--- a/doc/how_nom_macros_work.md
+++ b/doc/how_nom_macros_work.md
@@ -140,7 +140,7 @@ transformed with the second pattern:
 opt!(call!(digit))
 ```
 
-The `call!` macro transforms `call!(input, f)` into `f(i)`. If you need to pass more parameters to the function, you can Use `call!(input, f, arg, arg2)` to get `f(i, arg, arg2)`.
+The `call!` macro transforms `call!(input, f)` into `f(input)`. If you need to pass more parameters to the function, you can Use `call!(input, f, arg, arg2)` to get `f(input, arg, arg2)`.
 
 ## Using the macro's parameters
 
diff --git a/doc/making_a_new_parser_from_scratch.md b/doc/making_a_new_parser_from_scratch.md
index e1b43fe..c6b2f92 100644
--- a/doc/making_a_new_parser_from_scratch.md
+++ b/doc/making_a_new_parser_from_scratch.md
@@ -251,7 +251,7 @@ This particular one is caused by `named!` generating a function returning a `IRe
 
 There are a few tools you can use to debug how code is generated.
 
-## trace_macros
+## trace\_macros
 
 The `trace_macros` feature show how macros are applied. To use it, add `#![feature(trace_macros)]` at the top of your file (you need Rust nightly for this), then apply it like this:
 
diff --git a/doc/upgrading_to_nom_2.md b/doc/upgrading_to_nom_2.md
index 0eb2abc..b60b908 100644
--- a/doc/upgrading_to_nom_2.md
+++ b/doc/upgrading_to_nom_2.md
@@ -106,7 +106,7 @@ you can fix it with:
 +    c == 0x0
 ```
 
-## length_value, length_bytes refactoring
+## `length_value!`, `length_bytes!` refactoring
 
 The "length-value" pattern usually indicates that we get a length from the input, then take a slice of that size from the input, and convert that to a value of the type we need. The `length_value!` macro was using the length parameter to apply the value parser a specific number of times.
 
@@ -133,7 +133,7 @@ error[E0308]: mismatched types
          sig_hash_algs_len: be_u16 ~
 ```
 
-## error! does not exist anymore
+## `error!` does not exist anymore
 
 The `error!` macro, that was used to return a parsing error without backtracking through the parser tree, is now called `return_error!`. This change was done because the "log" crate also uses an `error!` macro, and they complained about the name conflict to nom instead of complaining to log, much to my dismay.
 
diff --git a/doc/upgrading_to_nom_4.md b/doc/upgrading_to_nom_4.md
index a28c4bd..76c2b13 100644
--- a/doc/upgrading_to_nom_4.md
+++ b/doc/upgrading_to_nom_4.md
@@ -231,10 +231,7 @@ If those types feel a bit long to write everywhere in the parsers, it's possible
 to alias them like this:
 
 ```rust,ignore
-type Input<'a> = CompleteByteSlice<'a>;
-pub fn Input<'a>(input:&'a[u8]) -> Input<'a> {
-  CompleteByteSlice(input)
-}
+use nom::types::CompleteByteSlice as Input;
 ```
 
 ## Custom error types
diff --git a/src/bits.rs b/src/bits.rs
index f0c3e77..ffb7531 100644
--- a/src/bits.rs
+++ b/src/bits.rs
@@ -159,7 +159,7 @@ macro_rules! bytes_impl (
   ($macro_i:expr, $submac:ident!( $($args:tt)* )) => (
     {
       use $crate::lib::std::result::Result::*;
-      use $crate::{Err,Needed};
+      use $crate::{Err,Needed,Context};
 
       let inp;
       if $macro_i.1 % 8 != 0 {
@@ -219,7 +219,7 @@ macro_rules! bytes_impl (
   ($macro_i:expr, $submac:ident!( $($args:tt)* )) => (
     {
       use $crate::lib::std::result::Result::*;
-      use $crate::{Err,Needed};
+      use $crate::{Err,Needed,Context};
 
       let inp;
       if $macro_i.1 % 8 != 0 {
diff --git a/src/bytes.rs b/src/bytes.rs
index ea37ffd..d5c0a47 100644
--- a/src/bytes.rs
+++ b/src/bytes.rs
@@ -300,6 +300,7 @@ macro_rules! escaped_transform (
       use $crate::ExtendInto;
       use $crate::InputIter;
       use $crate::InputLength;
+      use $crate::Needed;
       use $crate::Slice;
       use $crate::need_more;
 
@@ -759,7 +760,7 @@ macro_rules! take_until_and_consume1 (
 /// consumes data until it finds the specified tag.
 ///
 /// The remainder still contains the tag.
-/// (As opposed to `take_until!` which removes it from the remainder.)
+/// (As opposed to `take_until_and_consume!` which removes it from the remainder.)
 ///
 /// # Example
 /// ```
diff --git a/src/macros.rs b/src/macros.rs
index c1e571f..ee3dae5 100644
--- a/src/macros.rs
+++ b/src/macros.rs
@@ -150,6 +150,33 @@ macro_rules! named (
 );
 
 /// Makes a function from a parser combination with arguments.
+///
+/// ```ignore
+/// //takes `&[u8]` as input
+/// named_args!(tagged(open_tag: &[u8], close_tag: &[u8])<&str>,
+///   delimited!(tag!(open_tag), map_res!(take!(4), str::from_utf8), tag!(close_tag))
+/// );
+
+/// //takes `&str` as input
+/// named_args!(tagged(open_tag: &str, close_tag: &str)<&str, &str>,
+///   delimited!(tag!(open_tag), take!(4), tag!(close_tag))
+/// );
+/// ```
+///
+/// Note: if using arguments that way gets hard to read, it is always
+/// possible to write the equivalent parser definition manually, like
+/// this:
+///
+/// ```ignore
+/// fn tagged(input: &[u8], open_tag: &[u8], close_tag: &[u8]) -> IResult<&[u8], &str> {
+///   // the first combinator in the tree gets the input as argument. It is then
+///   // passed from one combinator to the next through macro rewriting
+///   delimited!(input,
+///     tag!(open_tag), take!(4), tag!(close_tag)
+///   )
+/// );
+/// ```
+///
 #[macro_export]
 macro_rules! named_args {
     (pub $func_name:ident ( $( $arg:ident : $typ:ty ),* ) < $return_type:ty > , $submac:ident!( $($args:tt)* ) ) => {


Test patch:
diff --git a/tests/issues.rs b/tests/issues.rs
index 66d3753..8d4115e 100644
--- a/tests/issues.rs
+++ b/tests/issues.rs
@@ -272,3 +272,12 @@ fn issue_759() {
 named_args!(issue_771(count: usize)<Vec<u32>>,
   length_count!(value!(count), call!(nom::be_u32))
 );
+
+/// This test is in a separate module to check that all required symbols are imported in
+/// `escaped_transform!()`. Without the module, the `use`-es of the current module would
+/// mask the error ('"Use of undeclared type or module `Needed`" in escaped_transform!').
+mod issue_780 {
+  named!(issue_780<&str, String>,
+    escaped_transform!(call!(::nom::alpha), '\\', tag!("n"))
+  );
+}