diff options
author | Lamont Granquist <lamont@scriptkiddie.org> | 2015-01-27 10:38:17 -0800 |
---|---|---|
committer | Lamont Granquist <lamont@scriptkiddie.org> | 2015-01-27 10:38:17 -0800 |
commit | 05d80b836cf5846841f13477e43dc7ec348f7718 (patch) | |
tree | cfbe78411356078a56ac5085cff42942ca078dd8 /README.md | |
parent | 8915463e6b17553215645d22b008f5d176261c10 (diff) | |
parent | 094321eb4f4d851f58fc26e557fe42edabdaf2bb (diff) | |
download | ffi-yajl-05d80b836cf5846841f13477e43dc7ec348f7718.tar.gz |
Merge pull request #39 from chef/readme-level-up
Update README w/ basic use and "why this"
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 42 |
1 files changed, 34 insertions, 8 deletions
@@ -1,14 +1,40 @@ [![Build Status](https://travis-ci.org/opscode/ffi-yajl.png)](https://travis-ci.org/opscode/ffi-yajl) [![Code Climate](https://codeclimate.com/github/opscode/ffi-yajl.png)](https://codeclimate.com/github/opscode/ffi-yajl) -## TODO - - -## BUILD NOTES - - -## KNOWN BUGS - +# FFI YAJL + +ffi-yajl is a Ruby adapter for the [yajl](http://lloyd.github.io/yajl/) +JSON parser/generator library. ffi-yajl supports multiple Ruby C +extension mechanisms, including both MRI native extensions and FFI in +order to be compatible with as many Ruby implementations as possible +while providing good performance where possible. + +## Basic Usage + +```ruby +require 'ffi-yajl' +json_out = FFI_Yajl::Encoder.encode( { "foo" => [ "bar", "baz" ] } ) +# => "{\"foo\":[\"bar\",\"baz\"]}" +data_in = FFI_Yajl::Parser.parse( json_out ) +# => {"foo"=>["bar", "baz"]} +``` + +## Why This Instead of X? + +yajl is the only JSON library we've found that has error messages that +meet our requirements. The stdlib json gem and oj (at the time we +started this project) have error messages like "invalid token at byte +1234," which are probably fine for server use, but in +[chef](https://github.com/chef/chef) we frequently deal with +user-written JSON documents, which means we need a good user experience +when encountering malformed JSON. + +We previously used brianmario's +[yajl-ruby](https://github.com/brianmario/yajl-ruby) project, but we +wanted to be able to fallback to using FFI bindings to the C code (so we +could support non-MRI rubies) and we also needed some bug fixes in +yajl2, but the maintainer wasn't able to devote enough time to the +project to make these updates in a timeframe that worked for us. ## Thanks |