diff options
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | examples/ast.rs | 11 | ||||
| -rw-r--r-- | examples/ast_to_gemtext.rs | 11 | ||||
| -rw-r--r-- | examples/html.rs | 15 | ||||
| -rw-r--r-- | examples/markdown.rs | 19 | ||||
| -rw-r--r-- | examples/meta.rs | 22 | ||||
| -rw-r--r-- | examples/request.rs | 33 | ||||
| -rw-r--r-- | examples/request_blocking.rs | 33 | ||||
| -rw-r--r-- | examples/request_blocking_to_gemtext_from_ast.rs | 37 | ||||
| -rw-r--r-- | src/request.rs | 10 |
10 files changed, 148 insertions, 45 deletions
@@ -52,7 +52,7 @@ features = ["ast"] # Enable the features you would like to use! ### Examples -Examples can be found within the +Thoroughly commented examples can be found within the [`examples/`](https://github.com/gemrest/germ/tree/main/examples) directory. ## License diff --git a/examples/ast.rs b/examples/ast.rs index 884bd91..5fd0b26 100644 --- a/examples/ast.rs +++ b/examples/ast.rs @@ -16,6 +16,9 @@ // Copyright (C) 2022-2022 Fuwn <[email protected]> // SPDX-License-Identifier: GPL-3.0-only +//! This example demonstrates Germ's capabilities for parsing Gemtext into an +//! abstract syntax tree. + const EXAMPLE_GEMTEXT: &str = r#"```This is alt-text Here goes the pre-formatted text. @@ -46,7 +49,13 @@ This is more text after a blank line. That was a link without text."#; fn main() { - for node in germ::ast::Ast::from_string(EXAMPLE_GEMTEXT).inner() { + // Parse `EXAMPLE_GEMTEXT` into an abstract syntax tree + let ast = germ::ast::Ast::from_string(EXAMPLE_GEMTEXT); + // Get the nodes of the abstract syntax tree + let ast_nodes = ast.inner(); + + // Print the abstract syntax tree nodes, one-by-one + for node in ast_nodes { println!("{:?}", node); } } diff --git a/examples/ast_to_gemtext.rs b/examples/ast_to_gemtext.rs index 4b96893..d163c8f 100644 --- a/examples/ast_to_gemtext.rs +++ b/examples/ast_to_gemtext.rs @@ -16,6 +16,9 @@ // Copyright (C) 2022-2022 Fuwn <[email protected]> // SPDX-License-Identifier: GPL-3.0-only +//! This example converts Gemtext into an abstract syntax tree and then back +//! into Gemtext, demonstrating both Germ's parsing and generation capabilities. + const EXAMPLE_GEMTEXT: &str = r#"```This is alt-text Here goes the pre-formatted text. @@ -46,5 +49,11 @@ This is more text after a blank line. That was a link without text."#; fn main() { - println!("{}", germ::ast::Ast::from_string(EXAMPLE_GEMTEXT).to_gemtext()); + // Parse `EXAMPLE_GEMTEXT` into an abstract syntax tree + let ast = germ::ast::Ast::from_string(EXAMPLE_GEMTEXT); + // Convert the abstract syntax tree back to Gemtext + let gemtext = ast.to_gemtext(); + + // Print the Gemtext, identical to `EXAMPLE_GEMTEXT` + println!("{gemtext}"); } diff --git a/examples/html.rs b/examples/html.rs index 541c01e..391867f 100644 --- a/examples/html.rs +++ b/examples/html.rs @@ -16,6 +16,9 @@ // Copyright (C) 2022-2022 Fuwn <[email protected]> // SPDX-License-Identifier: GPL-3.0-only +//! This example demonstrates Germ's capabilities for converting Gemtext to +//! HTML. + const EXAMPLE_GEMTEXT: &str = r#"```This is alt-text Here goes the pre-formatted text. @@ -46,9 +49,11 @@ This is more text after a blank line. That was a link without text."#; fn main() { - std::fs::write( - "examples/convert.html", - germ::convert::from_string(EXAMPLE_GEMTEXT, &germ::convert::Target::HTML), - ) - .expect("could not write to file"); + // Convert the Gemtext to HTML + let html = + germ::convert::from_string(EXAMPLE_GEMTEXT, &germ::convert::Target::HTML); + + // Write the HTML to a file + std::fs::write("examples/convert.html", html) + .expect("could not write to file"); } diff --git a/examples/markdown.rs b/examples/markdown.rs index c14cdc5..f909894 100644 --- a/examples/markdown.rs +++ b/examples/markdown.rs @@ -16,6 +16,9 @@ // Copyright (C) 2022-2022 Fuwn <[email protected]> // SPDX-License-Identifier: GPL-3.0-only +//! This example demonstrates Germ's capabilities for converting Gemtext to +//! Markdown. + const EXAMPLE_GEMTEXT: &str = r#"```This is alt-text Here goes the pre-formatted text. @@ -46,12 +49,12 @@ This is more text after a blank line. That was a link without text."#; fn main() { - std::fs::write( - "examples/convert.md", - germ::convert::from_string( - EXAMPLE_GEMTEXT, - &germ::convert::Target::Markdown, - ), - ) - .expect("could not write to file"); + // Convert the Gemtext to Markdown + let html = germ::convert::from_string( + EXAMPLE_GEMTEXT, + &germ::convert::Target::Markdown, + ); + + // Write the Markdown to a file + std::fs::write("examples/convert.md", html).expect("could not write to file"); } diff --git a/examples/meta.rs b/examples/meta.rs index a9f4077..e9d4cec 100644 --- a/examples/meta.rs +++ b/examples/meta.rs @@ -16,9 +16,23 @@ // Copyright (C) 2022-2022 Fuwn <[email protected]> // SPDX-License-Identifier: GPL-3.0-only +//! This example demonstrates Germ's capabilities for parsing Gemini meta +//! sections. + fn main() { - println!( - "{:?}", - germ::meta::Meta::from_string("text/gemini; hi=2; hi2=string=2") - ) + // Parse Gemini meta section into a structured meta representation + let meta = germ::meta::Meta::from_string("text/gemini; hi=2; hi2=string=2"); + + // Debug view of the structured meta representation + println!("{:?}", meta); + + // Convert the structured meta representation back to a string, identical to + // the original meta section + println!("{}", meta.to_string()); + + // The MIME type of the meta section + println!("{}", meta.mime()); + + // A debug view of the parameters of the meta section + println!("{:?}", meta.parameters()); } diff --git a/examples/request.rs b/examples/request.rs index 33de2da..bb565c1 100644 --- a/examples/request.rs +++ b/examples/request.rs @@ -16,12 +16,37 @@ // Copyright (C) 2022-2022 Fuwn <[email protected]> // SPDX-License-Identifier: GPL-3.0-only +//! This example demonstrates Germ's capabilities for performing a non-blocking +//! request to a Gemini capsule. + #[tokio::main] async fn main() { - match germ::request::request(&url::Url::parse("gemini://fuwn.me").unwrap()) - .await - { - Ok(response) => println!("{:?}", response), + // Form a valid URL to a Gemini capsule + let url = url::Url::parse("gemini://fuwn.me").unwrap(); + // Perform a non-blocking request to the Gemini capsule + let request = germ::request::request(&url).await; + + match request { + // If the request was successful, print a debug view of the response + Ok(response) => { + // Print the status of the response + println!("{:?}", response.status()); + + // Print the meta string of the response + // + // More detailed meta usage can be found in the `meta` example + println!("{}", response.meta()); + + // Print the content of the response, if present + println!("{:?}", response.content()); + + // Print the size of the response + println!("{:?}", response.size()); + + // Print a debug view of the SSL suite used + println!("{:?}", response.suite()); + } + // If the request was unsuccessful, do nothing Err(_) => {} } } diff --git a/examples/request_blocking.rs b/examples/request_blocking.rs index fed1c41..8d6e513 100644 --- a/examples/request_blocking.rs +++ b/examples/request_blocking.rs @@ -16,11 +16,36 @@ // Copyright (C) 2022-2022 Fuwn <[email protected]> // SPDX-License-Identifier: GPL-3.0-only +//! This example demonstrates Germ's capabilities for performing a blocking +//! request to a Gemini capsule. + fn main() { - match germ::request::blocking::request( - &url::Url::parse("gemini://fuwn.me").unwrap(), - ) { - Ok(response) => println!("{:?}", response), + // Form a valid URL to a Gemini capsule + let url = url::Url::parse("gemini://fuwn.me").unwrap(); + // Perform a blocking request to the Gemini capsule + let request = germ::request::blocking::request(&url); + + match request { + // If the request was successful, print a debug view of the response + Ok(response) => { + // Print the status of the response + println!("{:?}", response.status()); + + // Print the meta string of the response + // + // More detailed meta usage can be found in the `meta` example + println!("{}", response.meta()); + + // Print the content of the response, if present + println!("{:?}", response.content()); + + // Print the size of the response + println!("{:?}", response.size()); + + // Print a debug view of the SSL suite used + println!("{:?}", response.suite()); + } + // If the request was unsuccessful, do nothing Err(_) => {} } } diff --git a/examples/request_blocking_to_gemtext_from_ast.rs b/examples/request_blocking_to_gemtext_from_ast.rs index 6abfdfb..10ff6fb 100644 --- a/examples/request_blocking_to_gemtext_from_ast.rs +++ b/examples/request_blocking_to_gemtext_from_ast.rs @@ -16,17 +16,34 @@ // Copyright (C) 2022-2022 Fuwn <[email protected]> // SPDX-License-Identifier: GPL-3.0-only +//! This example demonstrates a chain of Germ's capabilities by fetching a +//! Gemini capsule, parsing the response content into an abstract syntax tree, +//! and converting the abstract syntax tree back to Gemtext, identical to the +//! Gemini response content. + fn main() { - match germ::request::blocking::request( - &url::Url::parse("gemini://fuwn.me/").unwrap(), - ) { - Ok(response) => println!( - "{}", - germ::ast::Ast::from_string( - &*response.content().clone().unwrap_or_else(|| "".to_string()) - ) - .to_gemtext() - ), + // Form a valid URL to a Gemini capsule + let url = url::Url::parse("gemini://fuwn.me/").unwrap(); + // Perform a blocking request to the Gemini capsule + let request = germ::request::blocking::request(&url); + + match request { + // If the request was successful: + Ok(response) => { + // Obtain the content of the Gemini response + let response_content = + &*response.content().clone().unwrap_or_else(|| "".to_string()); + // Parse the Gemini response content into an abstract syntax tree + let ast = germ::ast::Ast::from_string(response_content); + // Convert the abstract syntax tree back to Gemtext, identical to the + // Gemini response content, constructed from the parsed abstract syntax + // tree + let gemtext = ast.to_gemtext(); + + // Print the Gemtext + println!("{}", gemtext) + } + // If the request was unsuccessful, do nothing Err(_) => {} } } diff --git a/src/request.rs b/src/request.rs index f1eb005..fb161d7 100644 --- a/src/request.rs +++ b/src/request.rs @@ -22,14 +22,10 @@ mod response; mod status; mod verifier; -#[cfg(feature = "blocking")] -pub mod blocking; +#[cfg(feature = "blocking")] pub mod blocking; -#[cfg(feature = "request")] -pub mod non_blocking; - -#[cfg(feature = "request")] -pub use non_blocking::request; +#[cfg(feature = "request")] pub mod non_blocking; +#[cfg(feature = "request")] pub use non_blocking::request; pub(crate) use verifier::GermVerifier; pub use {response::Response, status::Status}; |