summaryrefslogtreecommitdiff
path: root/yajl/README
diff options
context:
space:
mode:
Diffstat (limited to 'yajl/README')
-rw-r--r--yajl/README74
1 files changed, 74 insertions, 0 deletions
diff --git a/yajl/README b/yajl/README
new file mode 100644
index 0000000..ad61759
--- /dev/null
+++ b/yajl/README
@@ -0,0 +1,74 @@
+**********************************************************************
+ 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