🦠 The Definitive Gemini Protocol Toolkit
gemini
gemini-protocol
gemtext
parser
zero-dependency
toolkit
ast
converter
html
markdown
cli
networking
docs(examples): comment examples
+148
-45
+1
-1
README.md
+1
-1
README.md
+10
-1
examples/ast.rs
+10
-1
examples/ast.rs
···
16
16
// Copyright (C) 2022-2022 Fuwn <contact@fuwn.me>
17
17
// SPDX-License-Identifier: GPL-3.0-only
18
18
19
+
//! This example demonstrates Germ's capabilities for parsing Gemtext into an
20
+
//! abstract syntax tree.
21
+
19
22
const EXAMPLE_GEMTEXT: &str = r#"```This is alt-text
20
23
Here goes the pre-formatted text.
21
24
···
46
49
That was a link without text."#;
47
50
48
51
fn main() {
49
-
for node in germ::ast::Ast::from_string(EXAMPLE_GEMTEXT).inner() {
52
+
// Parse `EXAMPLE_GEMTEXT` into an abstract syntax tree
53
+
let ast = germ::ast::Ast::from_string(EXAMPLE_GEMTEXT);
54
+
// Get the nodes of the abstract syntax tree
55
+
let ast_nodes = ast.inner();
56
+
57
+
// Print the abstract syntax tree nodes, one-by-one
58
+
for node in ast_nodes {
50
59
println!("{:?}", node);
51
60
}
52
61
}
+10
-1
examples/ast_to_gemtext.rs
+10
-1
examples/ast_to_gemtext.rs
···
16
16
// Copyright (C) 2022-2022 Fuwn <contact@fuwn.me>
17
17
// SPDX-License-Identifier: GPL-3.0-only
18
18
19
+
//! This example converts Gemtext into an abstract syntax tree and then back
20
+
//! into Gemtext, demonstrating both Germ's parsing and generation capabilities.
21
+
19
22
const EXAMPLE_GEMTEXT: &str = r#"```This is alt-text
20
23
Here goes the pre-formatted text.
21
24
···
46
49
That was a link without text."#;
47
50
48
51
fn main() {
49
-
println!("{}", germ::ast::Ast::from_string(EXAMPLE_GEMTEXT).to_gemtext());
52
+
// Parse `EXAMPLE_GEMTEXT` into an abstract syntax tree
53
+
let ast = germ::ast::Ast::from_string(EXAMPLE_GEMTEXT);
54
+
// Convert the abstract syntax tree back to Gemtext
55
+
let gemtext = ast.to_gemtext();
56
+
57
+
// Print the Gemtext, identical to `EXAMPLE_GEMTEXT`
58
+
println!("{gemtext}");
50
59
}
+10
-5
examples/html.rs
+10
-5
examples/html.rs
···
16
16
// Copyright (C) 2022-2022 Fuwn <contact@fuwn.me>
17
17
// SPDX-License-Identifier: GPL-3.0-only
18
18
19
+
//! This example demonstrates Germ's capabilities for converting Gemtext to
20
+
//! HTML.
21
+
19
22
const EXAMPLE_GEMTEXT: &str = r#"```This is alt-text
20
23
Here goes the pre-formatted text.
21
24
···
46
49
That was a link without text."#;
47
50
48
51
fn main() {
49
-
std::fs::write(
50
-
"examples/convert.html",
51
-
germ::convert::from_string(EXAMPLE_GEMTEXT, &germ::convert::Target::HTML),
52
-
)
53
-
.expect("could not write to file");
52
+
// Convert the Gemtext to HTML
53
+
let html =
54
+
germ::convert::from_string(EXAMPLE_GEMTEXT, &germ::convert::Target::HTML);
55
+
56
+
// Write the HTML to a file
57
+
std::fs::write("examples/convert.html", html)
58
+
.expect("could not write to file");
54
59
}
+11
-8
examples/markdown.rs
+11
-8
examples/markdown.rs
···
16
16
// Copyright (C) 2022-2022 Fuwn <contact@fuwn.me>
17
17
// SPDX-License-Identifier: GPL-3.0-only
18
18
19
+
//! This example demonstrates Germ's capabilities for converting Gemtext to
20
+
//! Markdown.
21
+
19
22
const EXAMPLE_GEMTEXT: &str = r#"```This is alt-text
20
23
Here goes the pre-formatted text.
21
24
···
46
49
That was a link without text."#;
47
50
48
51
fn main() {
49
-
std::fs::write(
50
-
"examples/convert.md",
51
-
germ::convert::from_string(
52
-
EXAMPLE_GEMTEXT,
53
-
&germ::convert::Target::Markdown,
54
-
),
55
-
)
56
-
.expect("could not write to file");
52
+
// Convert the Gemtext to Markdown
53
+
let html = germ::convert::from_string(
54
+
EXAMPLE_GEMTEXT,
55
+
&germ::convert::Target::Markdown,
56
+
);
57
+
58
+
// Write the Markdown to a file
59
+
std::fs::write("examples/convert.md", html).expect("could not write to file");
57
60
}
+18
-4
examples/meta.rs
+18
-4
examples/meta.rs
···
16
16
// Copyright (C) 2022-2022 Fuwn <contact@fuwn.me>
17
17
// SPDX-License-Identifier: GPL-3.0-only
18
18
19
+
//! This example demonstrates Germ's capabilities for parsing Gemini meta
20
+
//! sections.
21
+
19
22
fn main() {
20
-
println!(
21
-
"{:?}",
22
-
germ::meta::Meta::from_string("text/gemini; hi=2; hi2=string=2")
23
-
)
23
+
// Parse Gemini meta section into a structured meta representation
24
+
let meta = germ::meta::Meta::from_string("text/gemini; hi=2; hi2=string=2");
25
+
26
+
// Debug view of the structured meta representation
27
+
println!("{:?}", meta);
28
+
29
+
// Convert the structured meta representation back to a string, identical to
30
+
// the original meta section
31
+
println!("{}", meta.to_string());
32
+
33
+
// The MIME type of the meta section
34
+
println!("{}", meta.mime());
35
+
36
+
// A debug view of the parameters of the meta section
37
+
println!("{:?}", meta.parameters());
24
38
}
+29
-4
examples/request.rs
+29
-4
examples/request.rs
···
16
16
// Copyright (C) 2022-2022 Fuwn <contact@fuwn.me>
17
17
// SPDX-License-Identifier: GPL-3.0-only
18
18
19
+
//! This example demonstrates Germ's capabilities for performing a non-blocking
20
+
//! request to a Gemini capsule.
21
+
19
22
#[tokio::main]
20
23
async fn main() {
21
-
match germ::request::request(&url::Url::parse("gemini://fuwn.me").unwrap())
22
-
.await
23
-
{
24
-
Ok(response) => println!("{:?}", response),
24
+
// Form a valid URL to a Gemini capsule
25
+
let url = url::Url::parse("gemini://fuwn.me").unwrap();
26
+
// Perform a non-blocking request to the Gemini capsule
27
+
let request = germ::request::request(&url).await;
28
+
29
+
match request {
30
+
// If the request was successful, print a debug view of the response
31
+
Ok(response) => {
32
+
// Print the status of the response
33
+
println!("{:?}", response.status());
34
+
35
+
// Print the meta string of the response
36
+
//
37
+
// More detailed meta usage can be found in the `meta` example
38
+
println!("{}", response.meta());
39
+
40
+
// Print the content of the response, if present
41
+
println!("{:?}", response.content());
42
+
43
+
// Print the size of the response
44
+
println!("{:?}", response.size());
45
+
46
+
// Print a debug view of the SSL suite used
47
+
println!("{:?}", response.suite());
48
+
}
49
+
// If the request was unsuccessful, do nothing
25
50
Err(_) => {}
26
51
}
27
52
}
+29
-4
examples/request_blocking.rs
+29
-4
examples/request_blocking.rs
···
16
16
// Copyright (C) 2022-2022 Fuwn <contact@fuwn.me>
17
17
// SPDX-License-Identifier: GPL-3.0-only
18
18
19
+
//! This example demonstrates Germ's capabilities for performing a blocking
20
+
//! request to a Gemini capsule.
21
+
19
22
fn main() {
20
-
match germ::request::blocking::request(
21
-
&url::Url::parse("gemini://fuwn.me").unwrap(),
22
-
) {
23
-
Ok(response) => println!("{:?}", response),
23
+
// Form a valid URL to a Gemini capsule
24
+
let url = url::Url::parse("gemini://fuwn.me").unwrap();
25
+
// Perform a blocking request to the Gemini capsule
26
+
let request = germ::request::blocking::request(&url);
27
+
28
+
match request {
29
+
// If the request was successful, print a debug view of the response
30
+
Ok(response) => {
31
+
// Print the status of the response
32
+
println!("{:?}", response.status());
33
+
34
+
// Print the meta string of the response
35
+
//
36
+
// More detailed meta usage can be found in the `meta` example
37
+
println!("{}", response.meta());
38
+
39
+
// Print the content of the response, if present
40
+
println!("{:?}", response.content());
41
+
42
+
// Print the size of the response
43
+
println!("{:?}", response.size());
44
+
45
+
// Print a debug view of the SSL suite used
46
+
println!("{:?}", response.suite());
47
+
}
48
+
// If the request was unsuccessful, do nothing
24
49
Err(_) => {}
25
50
}
26
51
}
+27
-10
examples/request_blocking_to_gemtext_from_ast.rs
+27
-10
examples/request_blocking_to_gemtext_from_ast.rs
···
16
16
// Copyright (C) 2022-2022 Fuwn <contact@fuwn.me>
17
17
// SPDX-License-Identifier: GPL-3.0-only
18
18
19
+
//! This example demonstrates a chain of Germ's capabilities by fetching a
20
+
//! Gemini capsule, parsing the response content into an abstract syntax tree,
21
+
//! and converting the abstract syntax tree back to Gemtext, identical to the
22
+
//! Gemini response content.
23
+
19
24
fn main() {
20
-
match germ::request::blocking::request(
21
-
&url::Url::parse("gemini://fuwn.me/").unwrap(),
22
-
) {
23
-
Ok(response) => println!(
24
-
"{}",
25
-
germ::ast::Ast::from_string(
26
-
&*response.content().clone().unwrap_or_else(|| "".to_string())
27
-
)
28
-
.to_gemtext()
29
-
),
25
+
// Form a valid URL to a Gemini capsule
26
+
let url = url::Url::parse("gemini://fuwn.me/").unwrap();
27
+
// Perform a blocking request to the Gemini capsule
28
+
let request = germ::request::blocking::request(&url);
29
+
30
+
match request {
31
+
// If the request was successful:
32
+
Ok(response) => {
33
+
// Obtain the content of the Gemini response
34
+
let response_content =
35
+
&*response.content().clone().unwrap_or_else(|| "".to_string());
36
+
// Parse the Gemini response content into an abstract syntax tree
37
+
let ast = germ::ast::Ast::from_string(response_content);
38
+
// Convert the abstract syntax tree back to Gemtext, identical to the
39
+
// Gemini response content, constructed from the parsed abstract syntax
40
+
// tree
41
+
let gemtext = ast.to_gemtext();
42
+
43
+
// Print the Gemtext
44
+
println!("{}", gemtext)
45
+
}
46
+
// If the request was unsuccessful, do nothing
30
47
Err(_) => {}
31
48
}
32
49
}
+3
-7
src/request.rs
+3
-7
src/request.rs
···
22
22
mod status;
23
23
mod verifier;
24
24
25
-
#[cfg(feature = "blocking")]
26
-
pub mod blocking;
27
-
28
-
#[cfg(feature = "request")]
29
-
pub mod non_blocking;
25
+
#[cfg(feature = "blocking")] pub mod blocking;
30
26
31
-
#[cfg(feature = "request")]
32
-
pub use non_blocking::request;
27
+
#[cfg(feature = "request")] pub mod non_blocking;
33
28
29
+
#[cfg(feature = "request")] pub use non_blocking::request;
34
30
pub(crate) use verifier::GermVerifier;
35
31
pub use {response::Response, status::Status};