First release of open-appsec source code

external/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