continued documentation

src/lib/book.rs

@@ -339,7 +339,7 @@ impl Book {
     ///
     /// # Arguments
     /// * `filename`: the path of file to load.
-    /// * `verbose`: sets the book to verbose mode either if the file's doesn't specify it
+    /// * `verbose`: sets the book to verbose mode even if the file's doesn't specify it
     ///    or specifies `verbose: false`
     pub fn new_from_file(filename: &str, verbose: bool) -> Result<Book> {
         let path = Path::new(filename);

src/lib/lib.rs

@@ -19,6 +19,80 @@
 //!  Note: this documentation is relative to `crowbook` *as a library*.
 //!  For documentation regarding the *program* `crowbook`, see
 //!  [the Github page](https://github.com/lise-henry/crowbook).
+//!
+//! # Book
+//!
+//! The central structure of Crowbook is `Book`, who coordinates everything.
+//!
+//! Its roles are:
+//! * reading a book configuration file and setting the book options accordingly
+//! * giving the chapters (written in Markdown) listed in this configuration file
+//!   to `Parser`, get back an AST and store it in memory
+//! * call `HtmlRenderer`, `EpubRenderer`, `LatexRenderer` and/or `OdtRenderer`
+//!   according to the book's parameters and generate the appopriate files.
+//!
+//! ## Example
+//!
+//! ```ignore
+//! use crowbook::Book;
+//! // Reads configuration file "foo.book" (and set verbose mode to `false`)
+//! let mut book = Book::new_from_file("foo.book", false).unwrap();
+//! // Render all formats according to this configuration file
+//! book.render_all().unwrap();
+//! ```
+//!
+//! This is basically the code for the `crowbook` binary (though it contains a
+//! bit more error handling, checking parameters from command line and so on).
+//! This is, however, not very interesting for a library usage.
+//!
+//! The `Book` structure, however, exposes its `chapter` fields, which contains
+//! a vector with an element by chapter. With it, you can access the Markdown
+//! for all chapters represented as an Abstact Syntax Tree (i.e., a vector of `Token`s).
+//! It is thus possible to create a new renderer (or manipulate this AST in other ways).
+//!
+//! # Parser
+//!
+//! It is also possible to directly use `Parser` to transform some markdown string or file
+//! to this AST:
+//!
+//! ```
+//! use crowbook::{Parser,Token};
+//! let mut parser = Parser::new();
+//! let result = parser.parse("Some *valid* Markdown").unwrap();
+//! assert_eq!(format!("{:?}", result),
+//! r#"[Paragraph([Str("Some "), Emphasis([Str("valid")]), Str(" Markdown")])]"#);
+//! ```
+//!
+//! Of course, you probably want to do something else with this AST than display it.
+//! Let's assume you want to count the number of links in a document.
+//!
+//! ```
+//! use crowbook::{Parser,Token};
+//! fn count(ast: &[Token]) -> u32 {
+//!    let mut n = 0;
+//!    for token in ast {
+//!        match *token {
+//!            // It's a link, increase counter
+//!            Token::Link(_,_,_) => n += 1,
+//!            // It's not a link, let's count the number of links
+//!            // inside of the inner element (if there is one)
+//!           _ => {
+//!                if let Some(sub_ast) = token.inner() {
+//!                    n += count(sub_ast);
+//!                }
+//!            }
+//!       }
+//!    }
+//!    n
+//! }
+//! 
+//! let md = "# Here's a [link](http://foo.bar) #\n And *another [one](http://foo.bar)* !";
+//!
+//! let mut parser = Parser::new();
+//! let ast = parser.parse(md).unwrap();
+//! assert_eq!(count(&ast), 2);
+//! ```
+
 
 
 extern crate pulldown_cmark as cmark;

src/lib/tests/parser.rs

@@ -7,6 +7,7 @@ fn parse_from_str(doc: &str) -> Vec<Token> {
     parser.parse(doc).unwrap()
 }
 
+
 #[test]
 fn h_p_em() {
     let doc = "

src/lib/token.rs

@@ -69,3 +69,34 @@ pub enum Token {
     Image(String, String, Vec<Token>), 
 }
 
+use Token::*;
+
+impl Token {
+    /// Returns the inner list of tokens contained in this token (if any)
+    pub fn inner(&self) -> Option<&[Token]> {
+        match *self {
+            Rule
+                | SoftBreak
+                | HardBreak
+                | Str(_) => None,
+            Paragraph(ref v) 
+                | Header(_, ref v)
+                | Emphasis(ref v)
+                | Strong(ref v)
+                | Code(ref v)
+                | BlockQuote(ref v)
+                | CodeBlock(_, ref v)
+                | List(ref v)
+                | OrderedList(_, ref v)
+                | Item(ref v)
+                | Table(_, ref v)
+                | TableHead(ref v)
+                | TableRow(ref v)
+                | TableCell(ref v)
+                | Footnote(ref v)
+                | Link(_,_,ref v)
+                | Image(_,_,ref v) => Some(v)
+        }
+    }
+}
+