jhn_stdlib [(γ)][5]
==========
A few thought experiments solidified as code.
* [Introduction](#introduction)
* [Behaviours](#behaviours)
* [Features/Modules](#features)
* [Deprecated Features/Modules](#deprecated)
* [Build](#build)
* [Install](#install)
* [Contribute](#contribute) - Read if you're planning to submit patches
<a name='introduction'>
Introduction
------------
This library consists mainly of code that arose out of my curiosity, either
about Erlang and coding in general or concerning a pericular protocol or
technique. So there is little of cohesion in purposes between the different
library modules. But having published these I will continue to support these
since the road to enlightenment is one without terminus.
Behaviours
--------
* jhn_server -- A generic server
* jhn_fsm -- A FSM with the ability to defer acting on events until
a later state
<a name='features'>
Features/Modules
--------
* String Processing Functions for binary encoded strings
* blist -- drop in replacement for the lists module in stdlib
* bstring -- drop in replacement for the string module in stdlib
* mustache -- Mustache template rendering
* Protocols
* Encoding/decoding JSON/Erlang -- jhn_json [rfc8259][30]
* Encoding/decoding/evaluation JSON Pointer/Erlang -- jhn_json [rfc6901][8]
* Patch JSON -- jhn_json [rfc6902][31]
* Merge patch JSON -- jhn_json [rfc7396][32]
* Validation JSON schema -- json [draft-zyp-json-schema-04][10],
[draft-fge-json-schema-validation-00][11]
* MessagePack -- msgpack [MessagePack][12]/Erlang
* Bencoding -- bencoding
* Encoding/decoding Syslog/Erlang -- syslog [rfc5424][13],
[rfc5427][14],
[rfc6012][29]
* Consistent Hashing -- jhn_chash [J. Lamping, Eric Veach][28]
* Standards
* Encoding/decoding URI/Erlang -- uri [rfc3986][15]
* Encoding/decoding IP addresses/Erlang -- ip_addr [rfc4291][16],
[rfc5952][17],
[rfc4632][18]
* Generating/encoding/decoding Timestamps Posix/Erlang -- timestamp
[rfc3339][19],
[rfc7231][21]
* Clients
* A simple HTTP client -- shttpc [rfc7230][20], [rfc7231][21],
[rfc7538][22], [rfc5789][23],
[rfc2818][24]
* Server/client for Syslog -- syslog [rfc5425][25], [rfc5426][26],
[rfc6587][27]
* Pull oriented data source abstraction
* lazy -- abstracts different data sources as uniform lazy data
* Data structures
* Bloom filters -- bloom
* Property lists -- plist
* Prefix trees -- p_tree
* Binary(UTF-8) Prefix trees -- pb_tree
* Range trees -- r_tree
* T-trees -- t_tree
* Algorithms
* Levenshtein distance -- levenshtein
* CRC32-C checksum -- jhn_hash [rfc9260][33]
* xxHash-32 checksum -- jhn_hash [xxHash][34]
<a name='deprecated'>
Deprecated Features/Modules
--------
* json -- use jhn_json instead, with the exception of validation
* jstream -- use jhn_json instead
<a name='build'>
Build
-----
jhn_stdlib requires [rebar3][1] to build, but provides make support to download
and install rebar. To build jhn_stdlib, go to the jhn_stdlib directory and type:
```sh
make
```
To make sure jhn_stdlib works on your platform, run the tests:
```sh
make test
```
Two things might seem alarming when running the tests:
1. Warnings emitted by cover
2. En exception printed by SASL
Both are expected due to the way Erlang currently prints errors. The
important line you should look for is `All XX tests passed`, if that
appears all is correct.
<a name='install'>
Install
-------
If you want to install your own built version of jhn_stdlib add the ebin
directory to your Erlang code path or move the jhn_stdlib folder into your
release folder and make sure that folder is in your `ERL_LIBS`
environment variable.
<a name='contribute'>
Contribute
----------
Should you find yourself using jhn_stdlib and have issues, comments or
feedback please [create an issue here on GitHub.] [2]
Patches are greatly appreciated, but since these libraries reflect my
learning process and I have rather peculiar notions of code hygiene
I may do extensive rewrites that does not in any way diminish the
appreciation I feel or indeed express
For a much nicer history, please [write good commit messages][4].
I know I really should.
[1]: https://github.com/erlang/rebar3
"Rebar3 - A build tool for Erlang"
[2]: http://github.com/JanHenryNystrom/jhn_stdlib/issues
"jhn_stdlib issues"
[4]: http://github.com/erlang/otp/wiki/Writing-good-commit-messages
"Erlang/OTP commit messages"
[5]: http://en.wikipedia.org/wiki/Software_release_life_cycle
"Software release life cycle"
[6]: http://www.ietf.org/rfc/rfc4627.txt
"The application/json Media Type for JavaScript Object Notation (JSON)"
[7]: http://www.ietf.org/rfc/rfc7159.txt
"The JavaScript Object Notation (JSON) Data Interchange Format"
[8]: http://www.ietf.org/rfc/rfc6901.txt
"JavaScript Object Notation (JSON) Pointer"
[10]: http://tools.ietf.org/id/draft-zyp-json-schema-04.txt
"JSON Schema: core definitions and terminology"
[11]: http://tools.ietf.org/id/draft-fge-json-schema-validation-00.txt
"JSON Schema: interactive and non interactive validation"
[12]: http://msgpack.org/
"An efficient binary serialization format"
[13]: http://www.ietf.org/rfc/rfc5424.txt
"The Syslog Protocol"
[14]: http://www.ietf.org/rfc/rfc5427.txt
"Textual Conventions for Syslog Management"
[15]: http://www.ietf.org/rfc/rfc3986.txt
"Uniform Resource Identifier (URI): Generic Syntax"
[16]: http://www.ietf.org/rfc/rfc4291.txt
"IP Version 6 Addressing Architecture"
[17]: http://www.ietf.org/rfc/rfc5952.txt
"A Recommendation for IPv6 Address Text Representation"
[18]: http://www.ietf.org/rfc/rfc4632.txt
"Classless Inter-domain Routing (CIDR): The Internet Address Assignment and Aggregation Plan"
[19]: http://www.ietf.org/rfc/rfc3339.txt
"Date and Time on the Internet: Timestamps"
[20]: http://www.ietf.org/rfc/rfc7230.txt
"Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing"
[21]: http://www.ietf.org/rfc/rfc7231.txt
"Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content"
[22]: http://www.ietf.org/rfc/rfc7538.txt
"The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)"
[23]: http://www.ietf.org/rfc/rfc5789.txt
"PATCH Method for HTTP"
[24]: http://www.ietf.org/rfc/rfc2818.txt
"HTTP Over TLS (rfc2818)"
[25]: http://www.ietf.org/rfc/rfc5425.txt
"Transport Layer Security (TLS) Transport Mapping for Syslog"
[26]: http://www.ietf.org/rfc/rfc5426.txt
"Transmission of Syslog Messages over UDP"
[27]: http://www.ietf.org/rfc/rfc6587.txt
"Transmission of Syslog Messages over TCP"
[28]: https://arxiv.org/ftp/arxiv/papers/1406/1406.2294.pdf
"A Fast, Minimal Memory, Consistent Hash Algorithm, John Lamping, Eric Veach"
[29]: http://www.ietf.org/rfc/rfc6012.txt
"Datagram Transport Layer Security (DTLS) Transport Mapping for Syslog"
[30]: http://www.ietf.org/rfc/rfc8259.txt
"The JavaScript Object Notation (JSON) Data Interchange Format"
[31]: http://www.ietf.org/rfc/rfc6902.txt
"JavaScript Object Notation (JSON) Patch"
[32]: http://www.ietf.org/rfc/rfc7396.txt
"JSON Merge Patch"
[33]: http://www.ietf.org/rfc/rfc9260.txt
"[Castagnoli93] G. Castagnoli, S. Braeuer and M. Herrman \"Optimization
of Cyclic Redundancy-Check Codes with 24 and 32 Parity
Bits\", IEEE Transact. on Communications, Vol. 41, No.
6, June 1993."
[34]: http://github.com/Cyan4973/xxHash
"xxHash - Extremely fast hash algorithm"
