https://github.com/gulpf/samson
A JSON5 implementation for Nim.
https://github.com/gulpf/samson
json json5 nim
Last synced: about 1 month ago
JSON representation
A JSON5 implementation for Nim.
- Host: GitHub
- URL: https://github.com/gulpf/samson
- Owner: GULPF
- License: mit
- Created: 2019-02-23T22:17:38.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2020-04-28T18:54:26.000Z (about 5 years ago)
- Last Synced: 2025-03-23T18:50:56.240Z (2 months ago)
- Topics: json, json5, nim
- Language: Nim
- Homepage:
- Size: 107 KB
- Stars: 20
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Samson
Samson is a library for serializing and deserializing [JSON5](https://github.com/json5/json5), a superset of JSON. This library is still a work in progress and some features are missing.
## Usage
The main API consists of only two procs: `toJson5` and `fromJson5`.
### Simple example
```nim
import samson
type User = object
name: string
age: range[0..high(int)]
timezone: Option[string]
let input = """
[
{"name": "John Doe", age: 25},
{"name": "Jane Doe", age: 22, timezone: "Europe/Stockholm"}
]
"""
let parsed = fromJson5(input, seq[User])
echo parsed
# => @[(name: "John Doe", age: 25, timezone: None[string]), (name: "Jane Doe", age: 22, timezone: Some("Europe/Stockholm"))]
echo toJson5(parsed)
# => [{"name": "John Doe", age: 25, timezone: null}, {"name": "Jane Doe", age: 22, timezone: "Europe/Stockholm"}]
```
### Advanced example
Pragma annotations can be used to control how an object type is serialized and deserialized. These are defined and documented in the `samson / pragmas` module.
```nim
import std/times, samson, samson/pragmas
type Advanced = object
nimField {.jsonFieldName: "jsonField".}: int
hidden {.jsonExclude.}: int
date {.jsonDateTimeFormat: "yyyy-MM-dd".}: DateTime
let x = Advanced(
nimField: 1,
hidden: 2,
date: initDateTime(1, mJan, 2010, 12, 00, 00, utc())
)
echo toJson5(x)
# => {"jsonField": 1, date: "2010-01-01"}
```
### Supported types
The following types in the standard library have special support in Samson:
- `int8`, `int16`, `int32`, `int`, and `int64`
- `uint8`, `uint16`, and `uint32` (note: `uint` and `uint64` are not supported for now)
- `float32` and `float64`
- `string`
- `char`
- `enum`
- `seq`
- `array`
- `bool`
- `range` (with range checking)
- `options.Option` (maps to `null` when empty)
- `times.Time`
- `times.DateTime`
- `tables.Table` and `tables.OrderedTable` (maps to object)
- `set`, `sets.HashSet`, and `sets.OrderedSet`
Samson also supports custom `object` (mapped to objects in JSON5) and `tuple` (mapped to arrays in JSON5) types.
## Generated docs
- [samson module](https://gulpf.github.io/samson/samson.html)
- [samson/errors module](https://gulpf.github.io/samson/errors.html)
- [samson/pragmas module](https://gulpf.github.io/samson/pragmas.html)
## Planned features
- Stream based API.
- Support for type variants.
- Support for pretty printing.
- Support for dynamic JSON.
- A strict JSON mode which doesn't support JSON5 features.