feat: Refactored structure, handled missing comma error and added doc

Author: JulesGuesnon

Cargo.lock

@@ -1,6 +1,19 @@
-[workspace]
-members = ["crates/*"]
-resolver = "2"
+[package]
+name = "spanned_json_parser"
+version = "0.1.0"
+edition = "2021"
 
-[profile.release]
-debug = true
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+nom = "7"
+memchr = "2.6.4"
+serde = "1.0.190"
+bytecount = "0.6.7"
+
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "parsing"
+harness = false

Cargo.toml

@@ -0,0 +1,7 @@
+Copyright 2023 Jules Guesnon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

LICENSE

@@ -1,3 +1,79 @@
 # Spanned Json Parser
 
-WIP
+This crate is a json parser that will return span information for values, which mean lines and column number. It is also compatible with [serde](https://serde.rs/) so you can serialize it to any other struct that implements [Deserialize](https://docs.rs/serde/latest/serde/de/trait.Deserialize.html)
+
+## Why use it ?
+
+One of the main use case is to do validation after parsing. By having the line and col number, you can tell really precisely to user where a value is invalid
+
+## How to use it ?
+
+The crate expose a `Value` that is similar to [serde](https://docs.rs/serde_json/latest/serde_json/value/enum.Value.html), and wraps everything into this struct:
+
+```rust
+pub struct Position {
+    pub col: usize,
+    pub line: usize,
+}
+
+pub struct SpannedValue {
+    pub value: Value,
+    pub start: Position,
+    pub end: Position,
+}
+```
+
+### Parsing
+
+```rust
+use spanned_json_parse::parse;
+use std::fs;
+
+fn main() {
+    let json = fs::read_to_string(path).unwrap();
+
+    let parsed = parse(&json);
+
+    println!("Parsed: {:#?}", parsed);
+}
+```
+
+### Serializing in a struct
+
+```rust
+use serde::Deserialize;
+use spanned_json_parser::parse;
+
+#[derive(Deserialize)]
+struct Test {
+    pub hello: String,
+}
+
+fn main() {
+    let json = r#"{"hello": "world"}"#;
+
+    let parsed = parse(json).unwrap();
+
+    let test: Test = serde_json::from_value(serde_json::to_value(parsed).unwrap()).unwrap();
+
+    println!("Test hello: {}", test.hello);
+}
+```
+
+## Performance
+
+Here are the outputs of the benchmark. Everything was tested on a Macbook Pro M1, so keep in mind that this numbers are here to give you an idea of the performance, but might not be representative of the reality:
+
+```
+Parser ./benches/data/twitter.json
+time:   [10.220 ms 10.279 ms 10.334 ms]
+thrpt:  [58.280 MiB/s 58.589 MiB/s 58.932 MiB/s]
+
+Parser ./benches/data/citm_catalog.json
+time:   [18.204 ms 18.281 ms 18.353 ms]
+thrpt:  [89.752 MiB/s 90.102 MiB/s 90.486 MiB/s]
+
+Parser ./benches/data/canada.json
+time:   [42.026 ms 42.188 ms 42.341 ms]
+thrpt:  [50.702 MiB/s 50.886 MiB/s 51.082 MiB/s]
+```

README.md

@@ -6,6 +6,4 @@ edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-spanned_json_parser = { path = "../parser" }
-serde = "1.0.190"
-serde_json = "1.0"
+spanned_json_parser = { path = ".." }

crates/parser/benches/data/canada.json benches/data/canada.json

@@ -1,4 +1,4 @@
-use std::{env, fs, process, time::Instant};
+use std::{env, fs, process};
 
 fn main() {
     let args: Vec<String> = env::args().collect();
@@ -13,13 +13,8 @@ fn main() {
         }
     };
 
-    let start = Instant::now();
-    println!("Starting parsing: {:?}", start);
-
-    // let parsed = serde_json::from_str::<serde_json::Value>(&json);
     let parsed = spanned_json_parser::parse(&json);
 
-    println!("Ended parsing: {:?}", start.elapsed());
     match parsed {
         Ok(_) => process::exit(0),
         Err(_) => process::exit(1),

crates/parser/benches/data/citm_catalog.json benches/data/citm_catalog.json

@@ -1,15 +1,16 @@
 use crate::{parser::Span, value::Position};
 use nom::error::{ErrorKind, FromExternalError, ParseError};
-use std::num::IntErrorKind;
 use std::num::ParseFloatError;
 use std::num::ParseIntError;
 
 #[derive(Debug, PartialEq)]
 pub enum Kind {
     MissingQuote,
     MissingArrayBracket,
+    MissingComma,
     MissingObjectBracket,
     InvalidKey(String),
+    MissingChar(char),
     MissingColon,
     CharsAfterRoot(String),
     NotAnHex(String),
@@ -53,14 +54,14 @@ impl Default for Error {
 }
 
 impl From<ParseIntError> for Error {
-    fn from(value: ParseIntError) -> Self {
+    fn from(_value: ParseIntError) -> Self {
         let position = Position::default();
         Self::new(position.clone(), position, Kind::NotANumber)
     }
 }
 
 impl From<ParseFloatError> for Error {
-    fn from(value: ParseFloatError) -> Self {
+    fn from(_value: ParseFloatError) -> Self {
         let position = Position::default();
 
         Self::new(position.clone(), position, Kind::NotANumber)
@@ -78,7 +79,7 @@ impl<'a> ParseError<Span<'a>> for Error {
         }
     }
 
-    fn append(input: Span<'a>, kind: ErrorKind, other: Self) -> Self {
+    fn append(input: Span<'a>, kind: ErrorKind, _other: Self) -> Self {
         let pos = Position::from(input);
 
         Self {
@@ -90,7 +91,7 @@ impl<'a> ParseError<Span<'a>> for Error {
 }
 
 impl<'a, T> FromExternalError<Span<'a>, T> for Error {
-    fn from_external_error(input: Span<'a>, kind: ErrorKind, e: T) -> Self {
+    fn from_external_error(input: Span<'a>, _kind: ErrorKind, _e: T) -> Self {
         let position = Position::from(input);
 
         Self::new(position.clone(), position, Kind::ToBeDefined)

benches/data/largest.json

@@ -5,7 +5,7 @@ use nom::{
     InputTakeAtPosition, Offset, ParseTo, Slice,
 };
 use std::{
-    ops::{Range, RangeFrom, RangeFull, RangeTo},
+    ops::{Range, RangeFrom, RangeTo},
     str::{CharIndices, Chars, FromStr},
 };
 
@@ -149,7 +149,7 @@ impl<'a> InputTakeAtPosition for Input<'a> {
     fn split_at_position1<P, E: nom::error::ParseError<Self>>(
         &self,
         predicate: P,
-        e: nom::error::ErrorKind,
+        _e: nom::error::ErrorKind,
     ) -> nom::IResult<Self, Self, E>
     where
         P: Fn(Self::Item) -> bool,

crates/parser/benches/data/twitter.json benches/data/twitter.json

@@ -0,0 +1,94 @@
+#![forbid(unsafe_code)]
+#![warn(clippy::all)]
+#![allow(clippy::needless_doctest_main)]
+//! This crate is a json parser that will return span information for values, which mean lines and column number. It is also compatible with [serde](https://serde.rs/) so you can serialize it to any other struct that implements [Deserialize](https://docs.rs/serde/latest/serde/de/trait.Deserialize.html)
+//!
+//! ## Why use it ?
+//!
+//! One of the main use case is to do validation after parsing. By having the line and col number, you can tell really precisely to user where a value is invalid
+//!
+//! ## How to use it ?
+//!
+//! The crate expose a `Value` that is similar to [serde](https://docs.rs/serde_json/latest/serde_json/value/enum.Value.html), and wraps everything into this struct:
+//!
+//! ```rust
+//! pub struct Position {
+//!     pub col: usize,
+//!     pub line: usize,
+//! }
+//!
+//! pub struct SpannedValue {
+//!     pub value: Value,
+//!     pub start: Position,
+//!     pub end: Position,
+//! }
+//! ```
+//!
+//! ### Parsing
+//!
+//! ```rust
+//! use spanned_json_parse::parse;
+//! use std::fs;
+//!
+//! fn main() {
+//!     let json = fs::read_to_string("path").unwrap();
+//!
+//!     let parsed = parse(&json);
+//!
+//!     println!("Parsed: {:#?}", parsed);
+//! }
+//! ```
+//!
+//! ### Serializing in a struct
+//!
+//! ```rust
+//! use serde::Deserialize;
+//! use spanned_json_parser::parse;
+//!
+//! #[derive(Deserialize)]
+//! struct Test {
+//!     pub hello: String,
+//! }
+//!
+//! fn main() {
+//!     let json = r#"{"hello": "world"}"#;
+//!
+//!     let parsed = parse(json).unwrap();
+//!
+//!     let test: Test = serde_json::from_value(serde_json::to_value(parsed).unwrap()).unwrap();
+//!
+//!     println!("Test hello: {}", test.hello);
+//! }
+//! ```
+//!
+//! ## Performance
+//!
+//! Here are the outputs of the benchmark. Everything was tested on a Macbook Pro M1, so keep in mind that this numbers are here to give you an idea of the performance, but might not be representative of the reality:
+//!
+//! ```
+//! Parser ./benches/data/twitter.json
+//! time:   [10.220 ms 10.279 ms 10.334 ms]
+//! thrpt:  [58.280 MiB/s 58.589 MiB/s 58.932 MiB/s]
+//!
+//! Parser ./benches/data/citm_catalog.json
+//! time:   [18.204 ms 18.281 ms 18.353 ms]
+//! thrpt:  [89.752 MiB/s 90.102 MiB/s 90.486 MiB/s]
+//!
+//! Parser ./benches/data/canada.json
+//! time:   [42.026 ms 42.188 ms 42.341 ms]
+//! thrpt:  [50.702 MiB/s 50.886 MiB/s 51.082 MiB/s]
+//! ```
+
+extern crate bytecount;
+extern crate memchr;
+extern crate nom;
+extern crate serde;
+
+mod input;
+mod parser;
+mod ser;
+
+pub mod error;
+pub mod value;
+
+pub use parser::parse;