add initial guide module

Cargo.toml

@@ -26,6 +26,8 @@ simd = ["std", "memchr/std", "bytecount/runtime-dispatch-simd"]
 unicode = ["unicode-width"]
 # Enables full context backtraces.
 full-backtrace = ["alloc"]
+# Enables the guide module.
+guide = []
 
 [dependencies]
 zc = { version = "0.4", optional = true, default-features = false }

src/guide/bounded.rs

@@ -0,0 +1 @@
+//! TODO

src/guide/external.rs

@@ -0,0 +1,3 @@
+//! Using with external types and parsers.
+//!
+//! TODO

src/guide/faq.rs

@@ -0,0 +1,17 @@
+//! Frequently asked questions (ie. Why can't I do this?)
+//!
+//! ## Why isn't parsing numbers from string representation supported?
+//!
+//! Numbers have many different types of representations in string formats and
+//! can be parsed in many different ways. While Rust's standard library supports
+//! parsing numbers from strings, it doesn't support parsing them directly from
+//! bytes. Dangerous seeks to provide a foundation for other parsing libraries
+//! leaving the representation and the method of parsing as a downstream
+//! concern.
+//!
+//! Dangerous does implement support via [`error::External`] for the errors
+//! returned by the standard library's `from_str_radix` functions. See
+//! [`guide::external`] for more information.
+//!
+//! [`guide::external`]: crate::guide::external  
+//! [`error::External`]: crate::error::External

src/guide/mod.rs

@@ -0,0 +1,32 @@
+//! Usage guide.
+//!
+//! # Basic usage
+//!
+//! ```
+//! use dangerous::{Input, Invalid};
+//!
+//! let input = dangerous::input(b"hello");
+//! let result: Result<_, Invalid> = input.read_partial(|r| {
+//!     r.read()
+//! });
+//!
+//! assert_eq!(result, Ok((b'h', dangerous::input(b"ello"))));
+//! ```
+//! # Feature flags
+//!
+//! - `std` (**default feature**): Enables `std::error::Error` support and `alloc`.
+//! - `alloc` (**default feature**): Enables allocations.
+//! - `simd` (**default feature**): Enables all supported SIMD optimisations.
+//! - `unicode` (**default feature**): Enables improved unicode printing support.
+//! - `full-backtrace` (**default feature**): Enables collection of all contexts for `Expected`.
+//!
+//! **Third-party crate support (opt-in)**
+//!
+//! - `zc`: Enables `zc` crate support.
+//! - `nom`: Enables `nom` crate error support.
+//! - `regex`: Enables `regex` pattern support.
+
+pub mod bounded;
+pub mod external;
+pub mod faq;
+pub mod streaming;

src/guide/streaming.rs

@@ -0,0 +1 @@
+//! TODO

src/lib.rs

@@ -1,30 +1,6 @@
 //! Safely and explicitly parse untrusted aka `dangerous` data.
 //!
-//! # Basic usage
-//!
-//! ```
-//! use dangerous::{Input, Invalid};
-//!
-//! let input = dangerous::input(b"hello");
-//! let result: Result<_, Invalid> = input.read_partial(|r| {
-//!     r.read()
-//! });
-//!
-//! assert_eq!(result, Ok((b'h', dangerous::input(b"ello"))));
-//! ```
-//!
-//! # Feature flags
-//!
-//! | Feature          | Default     | Description
-//! | ---------------- | ----------- | -------------------------------------------------- |
-//! | `std`            | **Enabled** | Enables `std::error::Error` support and `alloc`    |
-//! | `alloc`          | **Enabled** | Enables allocations.                               |
-//! | `simd`           | **Enabled** | Enables all supported SIMD optimisations.          |
-//! | `unicode`        | **Enabled** | Enables improved unicode printing support.         |
-//! | `full-backtrace` | **Enabled** | Enables collection of all contexts for `Expected`. |
-//! | `zc`             | _Disabled_  | Enables `zc` crate support.                        |
-//! | `nom`            | _Disabled_  | Enables `nom` crate error support.                 |
-//! | `regex`          | _Disabled_  | Enables `regex` pattern support.                   |
+//! See the [`guide`] module to see how to get started.
 
 ///////////////////////////////////////////////////////////////////////////////
 // Library quirks & hacks
@@ -72,6 +48,8 @@ mod util;
 pub mod display;
 pub mod error;
 pub mod input;
+#[cfg(feature = "guide")]
+pub mod guide;
 
 pub use self::error::{Error, Expected, Fatal, Invalid, ToRetryRequirement};
 pub use self::input::{Bound, ByteArray, Bytes, Input, MaybeString, Span, String};