mirror of https://github.com/Icinga/icinga2.git
75 lines
2.7 KiB
Plaintext
75 lines
2.7 KiB
Plaintext
|
**********************************************************************
|
||
|
|
This is YAJL 2. For the legacy version of YAJL see
|
||
|
|
https://github.com/lloyd/yajl/tree/1.x
|
||
|
|
**********************************************************************
|
||
|
|
|
||
|
|
Welcome to Yet Another JSON Library (YAJL)
|
||
|
|
|
||
|
|
## Why does the world need another C library for parsing JSON?
|
||
|
|
|
||
|
|
Good question. In a review of current C JSON parsing libraries I was
|
||
|
|
unable to find one that satisfies my requirements. Those are,
|
||
|
|
0. written in C
|
||
|
|
1. portable
|
||
|
|
2. robust -- as close to "crash proof" as possible
|
||
|
|
3. data representation independent
|
||
|
|
4. fast
|
||
|
|
5. generates verbose, useful error messages including context of where
|
||
|
|
the error occurs in the input text.
|
||
|
|
6. can parse JSON data off a stream, incrementally
|
||
|
|
7. simple to use
|
||
|
|
8. tiny
|
||
|
|
|
||
|
|
Numbers 3, 5, 6, and 7 were particularly hard to find, and were what
|
||
|
|
caused me to ultimately create YAJL. This document is a tour of some
|
||
|
|
of the more important aspects of YAJL.
|
||
|
|
|
||
|
|
## YAJL is Free.
|
||
|
|
|
||
|
|
Permissive licensing means you can use it in open source and
|
||
|
|
commercial products alike without any fees. My request beyond the
|
||
|
|
licensing is that if you find bugs drop me a email, or better yet,
|
||
|
|
fork and fix.
|
||
|
|
|
||
|
|
Porting YAJL should be trivial, the implementation is ANSI C. If you
|
||
|
|
port to new systems I'd love to hear of it and integrate your patches.
|
||
|
|
|
||
|
|
## YAJL is data representation independent.
|
||
|
|
|
||
|
|
BYODR! Many JSON libraries impose a structure based data representation
|
||
|
|
on you. This is a benefit in some cases and a drawback in others.
|
||
|
|
YAJL uses callbacks to remain agnostic of the in-memory representation.
|
||
|
|
So if you wish to build up an in-memory representation, you may do so
|
||
|
|
using YAJL, but you must bring the code that defines and populates the
|
||
|
|
in memory structure.
|
||
|
|
|
||
|
|
This also means that YAJL can be used by other (higher level) JSON
|
||
|
|
libraries if so desired.
|
||
|
|
|
||
|
|
## YAJL supports stream parsing
|
||
|
|
|
||
|
|
This means you do not need to hold the whole JSON representation in
|
||
|
|
textual form in memory. This makes YAJL ideal for filtering projects,
|
||
|
|
where you're converting YAJL from one form to another (i.e. XML). The
|
||
|
|
included JSON pretty printer is an example of such a filter program.
|
||
|
|
|
||
|
|
## YAJL is fast
|
||
|
|
|
||
|
|
Minimal memory copying is performed. YAJL, when possible, returns
|
||
|
|
pointers into the client provided text (i.e. for strings that have no
|
||
|
|
embedded escape chars, hopefully the common case). I've put a lot of
|
||
|
|
effort into profiling and tuning performance, but I have ignored a
|
||
|
|
couple possible performance improvements to keep the interface clean,
|
||
|
|
small, and flexible. My hope is that YAJL will perform comparably to
|
||
|
|
the fastest JSON parser out there.
|
||
|
|
|
||
|
|
YAJL should impose both minimal CPU and memory requirements on your
|
||
|
|
application.
|
||
|
|
|
||
|
|
## YAJL is tiny.
|
||
|
|
|
||
|
|
Fat free. No whip.
|
||
|
|
|
||
|
|
enjoy,
|
||
|
|
Lloyd - July, 2007
|