README
1**********************************************************************
2 This is YAJL 2. For the legacy version of YAJL see
3 https://github.com/lloyd/yajl/tree/1.x
4**********************************************************************
5
6Welcome to Yet Another JSON Library (YAJL)
7
8## Why does the world need another C library for parsing JSON?
9
10Good question. In a review of current C JSON parsing libraries I was
11unable to find one that satisfies my requirements. Those are,
120. written in C
131. portable
142. robust -- as close to "crash proof" as possible
153. data representation independent
164. fast
175. generates verbose, useful error messages including context of where
18 the error occurs in the input text.
196. can parse JSON data off a stream, incrementally
207. simple to use
218. tiny
22
23Numbers 3, 5, 6, and 7 were particularly hard to find, and were what
24caused me to ultimately create YAJL. This document is a tour of some
25of the more important aspects of YAJL.
26
27## YAJL is Free.
28
29Permissive licensing means you can use it in open source and
30commercial products alike without any fees. My request beyond the
31licensing is that if you find bugs drop me a email, or better yet,
32fork and fix.
33
34Porting YAJL should be trivial, the implementation is ANSI C. If you
35port to new systems I'd love to hear of it and integrate your patches.
36
37## YAJL is data representation independent.
38
39BYODR! Many JSON libraries impose a structure based data representation
40on you. This is a benefit in some cases and a drawback in others.
41YAJL uses callbacks to remain agnostic of the in-memory representation.
42So if you wish to build up an in-memory representation, you may do so
43using YAJL, but you must bring the code that defines and populates the
44in memory structure.
45
46This also means that YAJL can be used by other (higher level) JSON
47libraries if so desired.
48
49## YAJL supports stream parsing
50
51This means you do not need to hold the whole JSON representation in
52textual form in memory. This makes YAJL ideal for filtering projects,
53where you're converting YAJL from one form to another (i.e. XML). The
54included JSON pretty printer is an example of such a filter program.
55
56## YAJL is fast
57
58Minimal memory copying is performed. YAJL, when possible, returns
59pointers into the client provided text (i.e. for strings that have no
60embedded escape chars, hopefully the common case). I've put a lot of
61effort into profiling and tuning performance, but I have ignored a
62couple possible performance improvements to keep the interface clean,
63small, and flexible. My hope is that YAJL will perform comparably to
64the fastest JSON parser out there.
65
66YAJL should impose both minimal CPU and memory requirements on your
67application.
68
69## YAJL is tiny.
70
71Fat free. No whip.
72
73enjoy,
74Lloyd - July, 2007
75