Struct crowbook::Book
[−]
[src]
pub struct Book { pub chapters: Vec<Chapter>, pub options: BookOptions, // some fields omitted }
A Book.
Probably the central structure for of Crowbook, as it is the one that calls the other ones.
It has the tasks of loading a configuration file, loading chapters
and using Parser
to parse them, and then calling various renderers
(HtmlRendrer
, LatexRenderer
, EpubRenderer
and/or OdtRenderer
)
to convert the AST into documents.
Examples
use crowbook::{Book, Number}; // Create a book with some options let mut book = Book::new(); book.set_options(&[("author", "Joan Doe"), ("title", "An untitled book"), ("lang", "en")]); // Add a chapter to the book book.add_chapter_from_source(Number::Default, "# The beginning#\nBla, bla, bla".as_bytes()).unwrap(); // Render the book as html to stdout book.render_format_to("html", &mut std::io::stdout()).unwrap();
Fields
chapters: Vec<Chapter>
Internal structure. You should not accesss this directly except if you are writing a new renderer.
options: BookOptions
Options of the book
Methods
impl Book
[src]
fn new() -> Book
Creates a new, empty Book
fn add_format<S: Into<String>>(
&mut self,
format: &'static str,
description: S,
renderer: Box<BookRenderer>
) -> &mut Self
&mut self,
format: &'static str,
description: S,
renderer: Box<BookRenderer>
) -> &mut Self
Register a format that can be rendered.
The renderer for this format must implement the BookRenderer
trait.
Example
use crowbook::{Result, Book, BookRenderer}; use std::io::Write; struct Dummy {} impl BookRenderer for Dummy { fn render(&self, book: &Book, to: &mut Write) -> Result<()> { write!(to, "This does nothing useful").unwrap(); Ok(()) } } let mut book = Book::new(); book.add_format("foo", "Some dummy implementation", Box::new(Dummy{}));
fn set_options<'a, I>(&mut self, options: I) -> &mut Book where
I: IntoIterator<Item = &'a (&'a str, &'a str)>,
I: IntoIterator<Item = &'a (&'a str, &'a str)>,
Sets the options of a Book
Arguments
options
: a (possibly empty) list (or other iterator) of (key, value) tuples.
Example
use crowbook::Book; let mut book = Book::new(); book.set_options(&[("author", "Foo"), ("title", "Bar")]); assert_eq!(book.options.get_str("author").unwrap(), "Foo"); assert_eq!(book.options.get_str("title").unwrap(), "Bar");
fn set_verbosity(&mut self, verbosity: InfoLevel) -> &mut Book
Sets the verbosity of a book
See InfoLevel
for more information on verbosity
Example
use crowbook::{Book, InfoLevel}; let mut book = Book::new(); book.set_verbosity(InfoLevel::Warning);
fn load_file<P: AsRef<Path>>(&mut self, path: P) -> Result<&mut Book>
Loads a book configuration file
Argument
path
: the path of the file to load. The directory of this file is used as a "root" directory for all paths referenced in books, whether chapter files, templates, cover images, and so on.
Example
let mut book = Book::new(); let result = book.load_file("some.book");
fn load_markdown_file<P: AsRef<Path>>(&mut self, path: P) -> Result<&mut Self>
Loads a single markdown file
This is not used to add a chapter to an existing book, but to to load the book configuration file from a single Markdown file.
Since it is designed for single-chapter short stories, this method also sets
the tex.class
option to article
.
Example
use crowbook::Book; let mut book = Book::new(); book.load_markdown_file("foo.md"); // not unwraping since foo.md doesn't exist
fn read_markdown_config<R: Read>(&mut self, source: R) -> Result<&mut Self>
Reads a single markdown config from a Read
able object.
Similar to load_markdown_file
, except it reads a source instead of a file.
Example
use crowbook::Book; let content = "\ --- author: Foo title: Bar --- Some content in *markdown*."; let mut book = Book::new(); book.read_markdown_config(content.as_bytes()).unwrap(); assert_eq!(book.options.get_str("title").unwrap(), "Bar");
fn read_config<R: Read>(&mut self, source: R) -> Result<&mut Book>
Reads a book configuration from a Read
able source.
Book configuration
A line with "option: value" sets the option to value
chapter_name.md adds the (default numbered) chapter
chapter_name.md adds the (unnumbered) chapter
- chapter_name.md adds the (custom numbered) chapter
See also
load_file
Example
use crowbook::Book; let content = "\ author: Foo title: Bar ! intro.md + chapter_01.md"; let mut book = Book::new(); book.read_config(content.as_bytes()); // no unwraping as `intro.md` and `chapter_01.md` don't exist
fn render_format(&self, format: &str)
Renders the book to the given format if output.{format} is set; do nothing otherwise.
Example
use crowbook::Book; let mut book = Book::new(); /* Will do nothing as book is empty and has no output format specified */ book.render_format("pdf");
fn render_all(&self)
Generates output files acccording to book options.
Example
use crowbook::Book; let content = "\ --- title: Foo output.tex: /tmp/foo.tex --- Bar and baz, too."; Book::new() .read_markdown_config(content.as_bytes()) .unwrap() .render_all(); // renders foo.tex in /tmp
fn render_format_to<T: Write>(&self, format: &str, f: &mut T) -> Result<()>
Render book to specified format according to book options, and write the results
in the Write
object.
This method will fail if the format is not handled by the book, or if there is a problem during rendering, or if the renderer can't render to a byte stream (e.g. multiple files HTML renderer can't, as it must create a directory.)
See also
render_format_to_file
, which creates a new file (that can be a directory).render_format
, which won't do anything ifoutput.{format}
isn't specified in the book configuration file.
fn render_format_to_file<P: Into<PathBuf>>(
&self,
format: &str,
path: P
) -> Result<()>
&self,
format: &str,
path: P
) -> Result<()>
Render book to specified format according to book options. Creates a new file and write the result in it.
This method will fail if the format is not handled by the book, or if there is a problem during rendering.
See also
render_format_to
, which writes in anyWrite
able object.render_format
, which won't do anything ifoutput.{format}
isn't specified in the book configuration file.
fn add_chapter_from_named_source<R: Read>(
&mut self,
number: Number,
file: &str,
source: R
) -> Result<&mut Self>
&mut self,
number: Number,
file: &str,
source: R
) -> Result<&mut Self>
Adds a chapter to the book.
This method is the backend used both by add_chapter
and add_chapter_from_source
.
fn add_subchapter(&mut self, level: i32, file: &str) -> Result<&mut Self>
Adds a chapter, as a file name, to the book
fn add_chapter(&mut self, number: Number, file: &str) -> Result<&mut Self>
Adds a chapter, as a file name, to the book
Book
will then parse the file and store the AST (i.e., a vector
of Token
s).
Arguments
number
: specifies if the chapter must be numbered, not numbered, or if its title must be hidden. SeeNumber
.file
: path of the file for this chapter
Returns an error if file
does not exist, could not be read, of if there was
some error parsing it.
fn add_chapter_from_source<R: Read>(
&mut self,
number: Number,
source: R
) -> Result<&mut Self>
&mut self,
number: Number,
source: R
) -> Result<&mut Self>
Adds a chapter to the book from a source (any object implementing Read
)
Book
will then parse the string and store the AST (i.e., a vector
of Token
s).
Arguments
number
: specifies if the chapter must be numbered, not numbered, or if its title must be hidden. SeeNumber
.content
: the content of the chapter.
Returns an error if there was some errror parsing content
.