lib_humus/lib.rs
1#![warn(missing_docs)]
2#![allow(clippy::needless_return)] // Explicit returning can improve readability
3#![allow(clippy::result_unit_err)] // Better than uing an Option …
4#![allow(clippy::to_string_trait_impl)] // Don't want to deal with reimplmenting as `Display` right now.
5#![allow(clippy::redundant_field_names)] // Those are okay
6#![allow(clippy::tabs_in_doc_comments)]
7// Tabs are just fine
8
9// SPDX-FileCopyrightText: 2026 Slatian <baschdel@disroot.org>
10//
11// SPDX-License-Identifier: AGPL-3.0-or-later
12
13//! [Codeberg](https://codeberg.org/slatian/lib-humus/) | [API Documentation](Self) | [Manuals](doc)
14//!
15//! lib-humus helps with some fertile ground to build a web project on.
16//!
17//! # What is lib-humus?
18//!
19//! lib-humus is an opinioated, pre-assembled templating engine that takes care of the frontend for a web application that builds on top of the [axum] framework.
20//!
21//! Its main use is in your handler functions right at the end to turn data from your application into the response that the client wants, be it HTML, plain text, json or something else.
22//!
23//! It allows you to focus on the data and the templates without having to worry about template engine details.
24//!
25//! Under the hood it uses well known crates like [tera] for templates and [fluent] for localization.
26//!
27//! # lib-humus is a family
28//!
29//! * [lib_humus_configuration] - filepath in, parsed data or a good error out, for json, json5 and toml files.
30//!
31//! # Overview
32//!
33//! The original idea behind this is that all the data that gets rendered as html
34//! should also be available as a JSON-API (and other formats if useful).
35//! The HTML should also come from easily replaceable templates
36//! that are themselves configurable.
37//!
38//! The [HumusEngine] helps you with that,
39//! it generated an appropriate response given a [HumusView] and [HumusQuerySettings].
40//!
41//! The [HumusView] providing the data and metadata for the frontend in the form of being serde serializable and through a number of callbacks and hooks.
42//!
43//! The [HumusQuerySettings] instance provides information on how to render the result.
44//!
45//! Loading the templates and the template configuration
46//! can be done using the [HumusEngineLoader].
47//!
48//! The [HumusQuerySettings] can be obtanied by adding a [TemplateSettingsLayer][middleware::TemplateSettingsLayer] as an axum middleware.
49//!
50//! The [LanguageEngine][crate::language::LanguageEngine] is provided to both the templates [and your code][HumusEngine::language_engine] to generate localized responses.
51//!
52//! This library is derived from (and now used by) the
53//! [echoip-slatecave service](https://codeberg.org/slatian/service.echoip-slatecave).
54//!
55//! [**For more documentation see the doc module.**][doc]
56//!
57//! # Feature-flags
58//!
59//! Feature flags have been removed in version `0.6`.
60
61///////////////////////////////////////
62// Tera-Loader
63
64mod humus_engine_loader;
65
66pub use self::humus_engine_loader::*;
67
68///////////////////////////////////////
69// Axum-View
70
71mod engine;
72mod query_settings;
73pub mod templating;
74mod view;
75
76pub use self::{engine::*, query_settings::*, view::*};
77
78///////////////////////////////////////
79// Language Engine
80
81pub mod language;
82
83///////////////////////////////////////
84// Middleware
85
86pub mod middleware;
87
88///////////////////////////////////////
89// HTTP Headers
90
91pub mod headers;
92
93///////////////////////////////////////
94// Helper modules
95
96pub mod crates;
97pub mod doc;
98pub mod util;