CHANGELOG.md

@@ -1,65 +1,67 @@
-= Changelog
+# Changelog
-:toc:
-:toclevels: 1
-:idprefix:
-:idseparator: -
 
-== [Unreleased]
+<!-- next-header -->
 
-== [v1.1.0] - 2024-03-21
+## [Unreleased] - ReleaseDate
 
-=== Added
+### Added
+
+- publishing to [crates.io](https://crates.io)
+
+## [v1.1.0] - 2024-03-21
+
+### Added
 
 - implement serializing into generic `io::Write`
 
-=== Fixed
+### Fixed
 
 - fix parsing CRLF
 
-== [v1.0.0] - 2023-03-10
+## [v1.0.0] - 2023-03-10
 
-=== Added
+### Added
 
 - implement literal strings
 
-=== Fixed
+### Fixed
 
 - fix serializing strings containing `:`
 - fix serializing certain escaped characters
 
-== [v0.2.4] - 2023-03-01
+## [v0.2.4] - 2023-03-01
 
-=== Fixed
+### Fixed
 
 - fix incorrect parsing of unquoted strings
 
-== [v0.2.3] - 2023-02-24
+## [v0.2.3] - 2023-02-24
 
-=== Fixed
+### Fixed
 
 - support backslashes in delimited strings
 
-== [v0.2.2] - 2023-02-18
+## [v0.2.2] - 2023-02-18
 
-=== Fixed
+### Fixed
 
 - fix deserialization failing on arrays and objects in some cases
 
-== [v0.2.1] - 2022-12-28
+## [v0.2.1] - 2022-12-28
 
-=== Fixed
+### Fixed
 
 - fix serializing Unicode
 
-== [v0.2.0] - 2022-11-25
+## [v0.2.0] - 2022-11-25
 
-=== Added
+### Added
 
 * parsing & deserialization
 
-== [v0.1.0] - 2022-11-18
+## [v0.1.0] - 2022-11-18
 
-=== Added
+### Added
 
 * initial release
 * serialization

Cargo.toml

@@ -1,15 +1,27 @@
 [package]
 name = "serde_sjson"
 version = "1.1.0"
+authors = ["Lucas Schwiderski"]
+categories = ["encoding", "parser-implementations"]
+description = "An SJSON serialization file format"
+documentation = "https://docs.rs/serde_sjson"
 edition = "2021"
 keywords = ["serde", "serialization", "sjson"]
-description = "An SJSON serialization file format"
+license-file = "LICENSE"
-categories = ["encoding", "parser-implementations"]
+repository = "https://github.com/sclu1034/serde_sjson"
+exclude = [
+    ".github/",
+    ".ci/",
+    "Justfile"
+]
 
 [dependencies]
-nom = "7.1.3"
+nom = "7"
-nom_locate = "4.1.0"
+nom_locate = "4.1"
-serde = { version = "1.0.154", default-features = false }
+serde = { version = "1.0", default-features = false }
 
 [dev-dependencies]
-serde = { version = "1.0.154", features = ["derive"] }
+serde = { version = "1.0.194", features = ["derive"] }
+
+[badges]
+maintenance = { status = "passively-maintained" }

Justfile

@@ -1,12 +1,26 @@
 project := "serde_sjson"
 default := "run"
 
+build *ARGS:
+    cargo build {{ARGS}}
+    cargo readme > README.md
+
 run *ARGS:
     cargo run -- {{ARGS}}
 
 test *ARGS:
     cargo test {{ARGS}}
 
+doc:
+    cargo doc --no-deps
+    cargo readme > README.md
+
+serve-doc port='8000': doc
+    python3 -m http.server {{port}} --directory target/doc
+
+release version execute='':
+    cargo release --sign --allow-branch master {{ if execute != "" { '-x' } else { '' } }} {{version}}
+
 coverage *ARGS:
     RUSTFLAGS="-C instrument-coverage" cargo test --tests {{ARGS}} || true
     cargo profdata -- merge -sparse default*.profraw -o {{project}}.profdata

README.adoc

@@ -1,13 +0,0 @@
-= Serde SJSON
-:idprefix:
-:idseparator:
-:toc: macro
-:toclevels: 1
-:!toc-title:
-:caution-caption: :fire:
-:important-caption: :exclamtion:
-:note-caption: :paperclip:
-:tip-caption: :bulb:
-:warning-caption: :warning:
-
-A __ser__ialization/__de__serialization library for __Simplified JSON__, specifically, the Bitsquid/Stingray flavor.

README.md

@@ -0,0 +1,69 @@
+# serde_sjson
+
+A **ser**ialization/**de**serialization library for Simplified JSON,
+the Bitsquid/Stingray flavor of JSON.
+
+## Usage
+
+### Serializing
+
+```rust
+use serde::Serialize;
+use serde_sjson::Result;
+
+#[derive(Serialize)]
+struct Person {
+    name: String,
+    age: u8,
+    friends: Vec<String>,
+}
+
+fn main() -> Result<()> {
+    let data = Person {
+        name: String::from("Marc"),
+        age: 21,
+        friends: vec![String::from("Jessica"), String::from("Paul")],
+    };
+
+    let s = serde_sjson::to_string(&data)?;
+
+    println!("{}", s);
+
+    Ok(())
+}
+```
+
+### Deserializing
+
+```rust
+use serde::Deserialize;
+use serde_sjson::Result;
+
+#[derive(Deserialize)]
+struct Person {
+    name: String,
+    age: u8,
+    friends: Vec<String>,
+}
+
+fn main() -> Result<()> {
+    let sjson = r#"
+    name = Marc
+    age = 21
+    friends = [
+        Jessica
+        Paul
+    ]"#;
+
+    let data: Person = serde_sjson::from_str(sjson)?;
+
+    println!(
+        "{} is {} years old and has {} friends.",
+        data.name,
+        data.age,
+        data.friends.len()
+    );
+
+    Ok(())
+}
+```

README.tpl

@@ -0,0 +1,3 @@
+# {{crate}}
+
+{{readme}}

release.toml

@@ -0,0 +1,5 @@
+pre-release-replacements = [
+    {file="CHANGELOG.md", search="Unreleased", replace="{{version}}"},
+    {file="CHANGELOG.md", search="ReleaseDate", replace="{{date}}"},
+    {file="CHANGELOG.md", search="<!-- next-header -->", replace="<!-- next-header -->\n\n## [Unreleased] - ReleaseDate", exactly=1},
+]

src/de.rs

@@ -5,6 +5,7 @@ use serde::Deserialize;
 use crate::error::{Error, ErrorCode, Result};
 use crate::parser::*;
 
+/// A container for deserializing Rust values from SJSON.
 pub struct Deserializer<'de> {
     input: Span<'de>,
     is_top_level: bool,
@@ -12,7 +13,7 @@ pub struct Deserializer<'de> {
 
 impl<'de> Deserializer<'de> {
     #![allow(clippy::should_implement_trait)]
-    pub fn from_str(input: &'de str) -> Self {
+    pub(crate) fn from_str(input: &'de str) -> Self {
         Self {
             input: Span::from(input),
             is_top_level: true,
@@ -65,6 +66,8 @@ impl<'de> Deserializer<'de> {
     }
 }
 
+/// Deserializes an SJSON string to a Rust value.
+#[inline]
 pub fn from_str<'a, T>(input: &'a str) -> Result<T>
 where
     T: Deserialize<'a>,

src/error.rs

@@ -2,8 +2,11 @@ use std::{fmt, io};
 
 use crate::parser::Token;
 
+/// An alias for a `Result` with `serde_sjson::Error`.
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// A type encapsulating the different errors that might occurr
+/// during serialization or deserialization.
 #[derive(PartialEq)]
 pub struct Error {
     inner: Box<ErrorImpl>,

src/lib.rs

@@ -1,3 +1,71 @@
+//! A **ser**ialization/**de**serialization library for Simplified JSON,
+//! the Bitsquid/Stingray flavor of JSON.
+//!
+//! # Usage
+//!
+//! ## Serializing
+//!
+//! ```
+//! use serde::Serialize;
+//! use serde_sjson::Result;
+//!
+//! #[derive(Serialize)]
+//! struct Person {
+//!     name: String,
+//!     age: u8,
+//!     friends: Vec<String>,
+//! }
+//!
+//! fn main() -> Result<()> {
+//!     let data = Person {
+//!         name: String::from("Marc"),
+//!         age: 21,
+//!         friends: vec![String::from("Jessica"), String::from("Paul")],
+//!     };
+//!
+//!     let s = serde_sjson::to_string(&data)?;
+//!
+//!     println!("{}", s);
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## Deserializing
+//!
+//! ```
+//! use serde::Deserialize;
+//! use serde_sjson::Result;
+//!
+//! #[derive(Deserialize)]
+//! struct Person {
+//!     name: String,
+//!     age: u8,
+//!     friends: Vec<String>,
+//! }
+//!
+//! fn main() -> Result<()> {
+//!     let sjson = r#"
+//!     name = Marc
+//!     age = 21
+//!     friends = [
+//!         Jessica
+//!         Paul
+//!     ]"#;
+//!
+//!     let data: Person = serde_sjson::from_str(sjson)?;
+//!
+//!     println!(
+//!         "{} is {} years old and has {} friends.",
+//!         data.name,
+//!         data.age,
+//!         data.friends.len()
+//!     );
+//!
+//!     Ok(())
+//! }
+//! ```
+
 mod de;
 mod error;
 mod parser;

src/ser.rs

@@ -7,12 +7,14 @@ use crate::error::{Error, ErrorCode, Result};
 // TODO: Make configurable
 const INDENT: [u8; 2] = [0x20, 0x20];
 
+/// A container for serializing Rust values into SJSON.
 pub struct Serializer<W> {
     // The current indentation level
     level: usize,
     writer: W,
 }
 
+/// Serializes a value into a generic `io::Write`.
 #[inline]
 pub fn to_writer<T, W>(writer: &mut W, value: &T) -> Result<()>
 where
@@ -23,6 +25,7 @@ where
     value.serialize(&mut serializer)
 }
 
+/// Serializes a value into a byte vector.
 #[inline]
 pub fn to_vec<T>(value: &T) -> Result<Vec<u8>>
 where
@@ -33,6 +36,7 @@ where
     Ok(vec)
 }
 
+/// Serializes a value into a string.
 #[inline]
 pub fn to_string<T>(value: &T) -> Result<String>
 where
@@ -51,6 +55,7 @@ impl<W> Serializer<W>
 where
     W: io::Write,
 {
+    /// Creates a new `Serializer`.
     pub fn new(writer: W) -> Self {
         Self { level: 0, writer }
     }

tests/serialize.rs

@@ -1,4 +1,4 @@
-use serde_sjson::{to_string, Error};
+use serde_sjson::to_string;
 
 #[test]
 fn serialize_null() {