# Welcome to Yet Another JSON Library (YAJL)

## NOTE:  This is a variant of the original [YAJL][LLOYD] by Lloyd Hilaiel.

This variant started as a fork of Lloyd's original.  This YAJL uses
BSDMake for building, Cxref for documentation, and it includes a few
minor bug fixes and other enhancements.  See the Git history.  Further
fixes or enhancements are welcome.

This YAJL is maintained in [robohack's GitHub][GHRY] by Greg A. Woods.

Motto:  Write Portable C without complicating the build!

See, e.g.: https://nullprogram.com/blog/2017/03/30/

Also, and perhaps more importantly:

	https://queue.acm.org/detail.cfm?id=2349257

## 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 Plain Standard ANSI C (C99!)
1. i.e. 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
9. can use a custom memory allocator

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.  Now truly so with the elimination of CMake!

enjoy,
Lloyd - July, 2007
Greg - April, 2024

[GHRY]: https://github.com/robohack/yajl/
[LLOYD]: https://github.com/lloyd/yajl/