Rebase to current master

.gitignore

@@ -1,3 +1,4 @@
 /target
+/book/book
 **/*.rs.bk
 Cargo.lock

book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Maciej Hirsz"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Logos Handbook"

book/src/SUMMARY.md

@@ -0,0 +1,11 @@
+# Summary
+
++ [Intro](./intro.md)
++ [Attributes](./attributes.md)
+  + [`#[logos]`](./attributes/logos.md)
+  + [`#[error]`](./attributes/error.md)
+  + [`#[token]` and `#[regex]`](./attributes/token_and_regex.md)
++ [Token disambiguation](./token-disambiguation.md)
++ [Using `Extras`](./extras.md)
++ [Using callbacks](./callbacks.md)
++ [Common regular expressions](./common-regex.md)

book/src/attributes.md

@@ -0,0 +1,18 @@
+# Attributes
+
+The `#[derive(Logos)]` procedural macro recognizes four different attribute
+names.
+
++ [`#[logos]`](./attributes/logos.md) is the main attribute which can be
+  attached to the `enum` of your token definition. It allows you to define the
+  `Extras` associated type in order to put custom state into the `Lexer`, or
+  declare concrete types for generic type parameters, if your `enum` uses such.
+  It is strictly optional.
++ [`#[error]`](./attributes/error.md) is the only mandatory attribute. It
+  can be used only once and will be used for any inputs that don't produce a
+  correct match with any defined pattern.
++ Last but definitely not least are the [`#[token]` and `#[regex]`](./attributes/token_and_regex.md)
+  attributes. Those allow you to define patterns to match against the input,
+  either plain text strings with `#[token]`, or using regular expression
+  syntax with `#[regex]`. Aside from that difference, they are equivalent,
+  and any extra arguments you can pass to one, you can pass to the other.

book/src/attributes/error.md

@@ -0,0 +1 @@
+# `#[error]`

book/src/attributes/logos.md

@@ -0,0 +1 @@
+# `#[logos]`

book/src/attributes/token_and_regex.md

@@ -0,0 +1 @@
+# `#[token]` and `#[regex]`

book/src/callbacks.md

@@ -0,0 +1 @@
+# Using callbacks

book/src/common-regex.md

@@ -0,0 +1 @@
+# Common regular expressions

book/src/extras.md

@@ -0,0 +1 @@
+# Using `Extras`

book/src/intro.md

@@ -0,0 +1,27 @@
+# Logos Handbook
+
+[![Crates.io version shield](https://img.shields.io/crates/v/logos.svg)](https://crates.io/crates/logos)
+[![Docs](https://docs.rs/logos/badge.svg)](https://docs.rs/logos)
+[![Crates.io license shield](https://img.shields.io/crates/l/logos.svg)](https://crates.io/crates/logos)
+
+<img src="https://github.com/maciejhirsz/logos/master/logos.svg?sanitize=true" alt="Logos logo" width="250" align="right">
+
+Hi there!
+
+**Logos** is a fast and easy to use [lexer](https://en.wikipedia.org/wiki/Lexical_analysis)
+generator written in Rust. While Rust has excellent documentation tools (and you can access
+the [API docs for Logos at docs.rs](https://docs.rs/logos/)), it's not the easiest thing to
+document custom syntax used by procedural macros, of which Logos has a bit. This Handbook
+seeks to remedy this!
+
+## In a nut shell
+
+There are two main types in **Logos**:
+
++ The `Logos` trait, which comes out with it's own derive macro. The derive
+  macro uses custom attributes (the things using these brackets: `#[...]`)
+  with plain string or [regular expression](https://en.wikipedia.org/wiki/Regular_expression)
+  syntax on `enum` variants as _patterns_ for some input.
++ The `Lexer<T: Logos>`, which is an iterator that takes some input (`&str`,
+  simetimes `&[u8]`) and performs lexical analysis on the input on the go,
+  producing variants of the enum `T` matching the defined patterns.

book/src/token-disambiguation.md

@@ -0,0 +1 @@
+# Token disambiguation