# Orgize
A Rust library for parsing orgmode files.
## Parse
To parse a orgmode string, simply invoking the `Org::parse` function:
```rust
use orgize::Org;
let org = Org::parse(r#"* Title 1
*Section 1*
** Title 2
_Section 2_
* Title 3
/Section 3/
* Title 4
=Section 4="#);
```
## Iter
`Org::iter` function will return a iteractor of `Event`s, which is
a simple wrapper of `Element`.
```rust
for event in org.iter() {
// handling the event
}
```
**Note**: whether an element is container or not, it will appears two times in a loop.
One as `Event::Start(element)`, one as `Event::End(element)`.
## Render html
You can call the `Org::html_default` function to generate html directly, which
uses the `DefaultHtmlHandler` internally:
```rust
let mut writer = Vec::new();
org.html_default(&mut writer).unwrap();
assert_eq!(
String::from_utf8(writer).unwrap(),
"Title 1
\
Title 2
\
Title 3
\
Title 4
"
);
```
## Render html with custom HtmlHandler
To customize html rending, simply implementing `HtmlHandler` trait and passing
it to the `Org::html` function.
The following code demonstrates how to add a id for every headline and return
own error type while rendering.
```rust
#[derive(Debug)]
enum MyError {
IO(IOError),
Heading,
Utf8(FromUtf8Error),
}
// From trait is required for custom error type
impl From for MyError {
fn from(err: IOError) -> Self {
MyError::IO(err)
}
}
impl From for MyError {
fn from(err: FromUtf8Error) -> Self {
MyError::Utf8(err)
}
}
struct MyHtmlHandler;
impl HtmlHandler for MyHtmlHandler {
fn start(&mut self, mut w: W, element: &Element<'_>) -> Result<(), MyError> {
let mut default_handler = DefaultHtmlHandler;
match element {
Element::Headline { headline, .. } => {
if headline.level > 6 {
return Err(MyError::Heading);
} else {
let slugify = slugify!(headline.title);
write!(
w,
"{2}",
headline.level,
slugify,
Escape(headline.title),
)?;
}
}
// fallthrough to default handler
_ => default_handler.start(w, element)?,
}
Ok(())
}
}
fn main() -> Result<(), MyError> {
let contents = r"* Title 1
*Section 1*
** Title 2
_Section 2_
* Title 3
/Section 3/
* Title 4
=Section 4=";
let mut writer = Vec::new();
Org::parse(&contents).html(&mut writer, MyHtmlHandler)?;
assert_eq!(
String::from_utf8(writer)?,
"\
\
\
"
);
Ok(())
}
```
**Note**: as I mentioned above, each element will appears two times while iterating.
And handler will silently ignores all end events from non-container elements.
So if you want to change how a non-container element renders, just redefine the start
function and leave the end function untouched.
## Serde
`Org` struct have already implemented serde's `Serialize` trait. It means you can
freely serialize it into any format that serde supports such as json:
```rust
use orgize::Org;
use serde_json::{json, to_string};
let org = Org::parse("I 'm *bold*.");
println!("{}", to_string(&org).unwrap());
// {
// "type": "document",
// "children": [{
// "type": "section",
// "children": [{
// "type": "paragraph",
// "children":[{
// "type": "text",
// "value":"I 'm "
// }, {
// "type": "bold",
// "children":[{
// "type": "text",
// "value": "bold"
// }]
// }, {
// "type":"text",
// "value":"."
// }]
// }]
// }]
// }
```
## License
MIT