From 8c5f0ad7d1a723f59b138c44515dc89e7fc411cf Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski Date: Thu, 21 Mar 2024 13:38:50 +0100 Subject: [PATCH 1/3] Add documentation --- Justfile | 11 ++++++++ README.adoc | 13 --------- README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++ README.tpl | 3 ++ src/de.rs | 5 +++- src/error.rs | 3 ++ src/lib.rs | 68 +++++++++++++++++++++++++++++++++++++++++++++ src/ser.rs | 5 ++++ tests/serialize.rs | 2 +- 9 files changed, 164 insertions(+), 15 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md create mode 100644 README.tpl diff --git a/Justfile b/Justfile index c052f9a..6e40be1 100644 --- a/Justfile +++ b/Justfile @@ -1,12 +1,23 @@ 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 + coverage *ARGS: RUSTFLAGS="-C instrument-coverage" cargo test --tests {{ARGS}} || true cargo profdata -- merge -sparse default*.profraw -o {{project}}.profdata diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 56a9faf..0000000 --- a/README.adoc +++ /dev/null @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7b60d9e --- /dev/null +++ b/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, +} + +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, +} + +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(()) +} +``` diff --git a/README.tpl b/README.tpl new file mode 100644 index 0000000..0d9b104 --- /dev/null +++ b/README.tpl @@ -0,0 +1,3 @@ +# {{crate}} + +{{readme}} diff --git a/src/de.rs b/src/de.rs index 8d35613..b28e116 100644 --- a/src/de.rs +++ b/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 where T: Deserialize<'a>, diff --git a/src/error.rs b/src/error.rs index feee003..9673524 100644 --- a/src/error.rs +++ b/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 = std::result::Result; +/// A type encapsulating the different errors that might occurr +/// during serialization or deserialization. #[derive(PartialEq)] pub struct Error { inner: Box, diff --git a/src/lib.rs b/src/lib.rs index ea30715..afac0e7 100644 --- a/src/lib.rs +++ b/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, +//! } +//! +//! 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, +//! } +//! +//! 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; diff --git a/src/ser.rs b/src/ser.rs index 532f78f..7efd83b 100644 --- a/src/ser.rs +++ b/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 { // The current indentation level level: usize, writer: W, } +/// Serializes a value into a generic `io::Write`. #[inline] pub fn to_writer(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(value: &T) -> Result> where @@ -33,6 +36,7 @@ where Ok(vec) } +/// Serializes a value into a string. #[inline] pub fn to_string(value: &T) -> Result where @@ -51,6 +55,7 @@ impl Serializer where W: io::Write, { + /// Creates a new `Serializer`. pub fn new(writer: W) -> Self { Self { level: 0, writer } } diff --git a/tests/serialize.rs b/tests/serialize.rs index 7afb926..380fec0 100644 --- a/tests/serialize.rs +++ b/tests/serialize.rs @@ -1,4 +1,4 @@ -use serde_sjson::{to_string, Error}; +use serde_sjson::to_string; #[test] fn serialize_null() { From 5a2855f0aeb4a65b51bcf52113d8faabbc3a0e52 Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski Date: Thu, 21 Mar 2024 13:39:52 +0100 Subject: [PATCH 2/3] Improve package metadata --- Cargo.toml | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 3526b48..a394beb 100644 --- a/Cargo.toml +++ b/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" -categories = ["encoding", "parser-implementations"] +license-file = "LICENSE" +repository = "https://github.com/sclu1034/serde_sjson" +exclude = [ + ".github/", + ".ci/", + "Justfile" +] [dependencies] -nom = "7.1.3" -nom_locate = "4.1.0" -serde = { version = "1.0.154", default-features = false } +nom = "7" +nom_locate = "4.1" +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" } From 1b3d16c479ea1bee2b6ccbea072a1af2b63135ca Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski Date: Thu, 21 Mar 2024 13:41:09 +0100 Subject: [PATCH 3/3] Add publishing command --- CHANGELOG.adoc => CHANGELOG.md | 50 ++++++++++++++++++---------------- Justfile | 3 ++ release.toml | 5 ++++ 3 files changed, 34 insertions(+), 24 deletions(-) rename CHANGELOG.adoc => CHANGELOG.md (51%) create mode 100644 release.toml diff --git a/CHANGELOG.adoc b/CHANGELOG.md similarity index 51% rename from CHANGELOG.adoc rename to CHANGELOG.md index 364a378..3f72905 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.md @@ -1,65 +1,67 @@ -= Changelog -:toc: -:toclevels: 1 -:idprefix: -:idseparator: - +# Changelog -== [Unreleased] + -== [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 diff --git a/Justfile b/Justfile index 6e40be1..131d0e5 100644 --- a/Justfile +++ b/Justfile @@ -18,6 +18,9 @@ doc: 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 diff --git a/release.toml b/release.toml new file mode 100644 index 0000000..df0c8c9 --- /dev/null +++ b/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="", replace="\n\n## [Unreleased] - ReleaseDate", exactly=1}, +]