crafty_novels

A library for converting text formats. Intended for converting Minecraft: Java Edition books to HTML, but it exposes traits necessary to implement arbitrary formats.

How it works

crafty_novels revolves around syntax:

Lexical tokens (crafty_novels::syntax::Token) represent plain text, formatting, document structure, etc.
Similarly, crafty_novels::syntax::Metadata tokens represent meta information about a work (currently the title and author name).
A crafty_novels::syntax::TokenList represents an entire work by holding arrays of those Tokens and Metadata tokens.

Structs that implement the crafty_novels::Tokenize trait take input (impl std::io::Read or &str) in their format's syntax and parse it into a TokenList.

Structs that implement the crafty_novels::Export trait take that TokenList, convert it to their format's syntax, and write that to an output (impl std::io::Write or Box<str>).

crafty_novels contains some built-in implementations of these traits, but the traits are exposed if you would like to implement your own.

Supported formats

Import

• Stendhal exports

Export

• HTML

Implementations

crafty_novels_cli

Currently, only for testing the lib.

In the future, it will handle file/stdin parsing, file/stdout export, and possibly a TUI (similar to the GUI) using Ratatui.

crafty_novels_gui

Not yet implemented. Will likely use Iced to implement a simple and user-friendly file picker and format selector interface.

Roadmap

• Basic Stendhal syntax parsing
  • Frontmatter parsing
• Basic HTML export
  • Frontmatter export
• Apply API best practices
  • More/better documentation for public items
    • Crate level docs
      C-CRATE-DOC
    • All items have examples
      C-EXAMPLE
    • Examples use ?, not unwrap
      C-QUESTION-MARK
    • Documentation of errors from Result functions and other failures (including for traits)
      C-FAILURE
    • Frequently use of links in doc comments
      C-LINK
    • Release notes and Git tags
      C-RELNOTES
    • Use of pub(crate) and #[doc(hidden)] to hide unhelpful implementation details from appearing in Rustdoc
      C-HIDDEN
  • Expose intermediary steps
  • Implement common traits
    • C-COMMON-TRAITS
    • C-SEND-SYNC
    • C-GOOD-ERR
    • C-SERDE
    • C-NUM-FMT
    • C-RW-VALUE
    • C-DEBUG
      • Debug representations are never empty (ex. assert_eq!(format!("{:?}", ""), r#""""#))
        C-DEBUG-NONEMPTY
  • Predicable, dependable, and type-safe code
    • Bind conversions to the most specific form of a data (ex. str::from_utf8, not <&[u8]>::to_string)
      C-CONV-SPECIFIC
    • Arguments convey meaning and requirements through types
      • Ex. Widget::new(Small, Round), not Widget::new(true, false) for clarity
        C-CUSTOM-TYPE
      • Ex. fn foo(a: Ascii) instead of fn foo(a: u8) -> Result<_, InvalidAscii> (or worse, a foo that panics)
        C-VALIDATE#Static Enforcement
    • Use newtypes to limit the scope of a function signature's promises and hide implementation details
      C-NEWTYPE-HIDE
      • Use of -> impl Trait maybe be used instead, but comes with some limitations like not ensuring Debug
    • Use derives instead of trait bounds for generic structs where possible
      C-STRUCT-BOUNDS
  • Flexible code
    • When encountering errors -- whether returned, like String::from_utf8 stopping at bad UTF-8, or ignored like HashMap::insert overwriting values at the key -- return intermediary work, like the point in an array that a missing item should have been or the point in a buffer where a bad byte was found.
      C-INTERMEDIATE
    • Prefer private fields (using getters/setters) to avoid committing to an API
      C-STRUCT-PRIVATE
  • Consider changing to a more permissive license (like the LGPL or MIT & Apache 2.0) for wider compatibility
    C-PERMISSIVE
• CLI
  • TUI
• GUI

License

crafty_novels is in no way affiliated with Microsoft, Mojang, Minecraft, Stendhal, or NebSpacefarer. All trademarks belong to their respective owners.

crafty_novels is licensed under the GNU Affero General Public License version 3, or (at your option) any later version. You should have received a copy of the GNU Affero General Public License along with crafty_novels, found in LICENSE. If not, see <https://www.gnu.org/licenses/>.