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//! lib-humus helps with some fertile ground to build a web project on.
14//!
15//! # What is lib-humus?
16//!
17//! 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.
18//!
19//! 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.
20//!
21//! It allows you to focus on the data and the templates without having to worry about template engine details.
22//!
23//! Under the hood it uses well known crates like [tera] for templates and [fluent] for localization.
24//!
25//! # lib-humus is a family
26//!
27//! * [lib_humus_configuration] - filepath in, parsed data or a good error out, for json, json5 and toml files.
28//!
29//! # Overview
30//!
31//! The original idea behind this is that all the data that gets rendered as html
32//! should also be available as a JSON-API (and other formats if useful).
33//! The HTML should also come from easily replaceable templates
34//! that are themselves configurable.
35//!
36//! The [HumusEngine] helps you with that,
37//! it generated an appropriate response given a [HumusView] and [HumusQuerySettings].
38//!
39//! 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.
40//!
41//! The [HumusQuerySettings] instance provides information on how to render the result.
42//!
43//! Loading the templates and the template configuration
44//! can be done using the [HumusEngineLoader].
45//!
46//! The [HumusQuerySettings] can be obtanied by adding a [TemplateSettingsLayer][middleware::TemplateSettingsLayer] as an axum middleware.
47//!
48//! The [LanguageEngine][crate::language::LanguageEngine] is provided to both the templates [and your code][HumusEngine::language_engine] to generate localized responses.
49//!
50//! This library is derived from (and now used by) the
51//! [echoip-slatecave service](https://codeberg.org/slatian/service.echoip-slatecave).
52//!
53//! For more documentation see the [doc module][doc].
54//!
55//! # Feature-flags
56//!
57//! Feature flags have been removed in version `0.6`.
58
59///////////////////////////////////////
60// Tera-Loader
61
62mod humus_engine_loader;
63
64pub use self::humus_engine_loader::*;
65
66///////////////////////////////////////
67// Axum-View
68
69mod engine;
70mod query_settings;
71pub mod templating;
72mod view;
73
74pub use self::{engine::*, query_settings::*, view::*};
75
76///////////////////////////////////////
77// Language Engine
78
79pub mod language;
80
81///////////////////////////////////////
82// Middleware
83
84pub mod middleware;
85
86///////////////////////////////////////
87// HTTP Headers
88
89pub mod headers;
90
91///////////////////////////////////////
92// Helper modules
93
94pub mod crates;
95pub mod doc;
96pub mod util;