Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 178 lines (123 sloc) 7.378 kB
6248665 ready for use with limitations
Peter Ohler authored
1 # Oj gem
2 A fast JSON parser and Object marshaller as a Ruby gem.
3
da3f12b @ohler55 added require bigdecimal to ruby file to work around rubinius bug
authored
4 ## Installation
25d9c78 @kookster A bit more editing
kookster authored
5 ```
6 gem install oj
7 ```
8 or in Bundler:
9 ```
10 gem 'oj'
11 ```
6248665 ready for use with limitations
Peter Ohler authored
12
da3f12b @ohler55 added require bigdecimal to ruby file to work around rubinius bug
authored
13 ## Documentation
6248665 ready for use with limitations
Peter Ohler authored
14
c8040bd @dchelimsky point to docs at rubydoc.info
dchelimsky authored
15 *Documentation*: http://www.ohler.com/oj, http://rubydoc.info/gems/oj
1ee8e1f updated readme
Peter Ohler authored
16
da3f12b @ohler55 added require bigdecimal to ruby file to work around rubinius bug
authored
17 ## Source
1ee8e1f updated readme
Peter Ohler authored
18
6248665 ready for use with limitations
Peter Ohler authored
19 *GitHub* *repo*: https://github.com/ohler55/oj
20
21 *RubyGems* *repo*: https://rubygems.org/gems/oj
22
11fd80a @ohler55 ready for release 2.1.0
authored
23 Follow [@peterohler on Twitter](http://twitter.com/#!/peterohler) for announcements and news about the Oj gem.
1ee8e1f updated readme
Peter Ohler authored
24
da3f12b @ohler55 added require bigdecimal to ruby file to work around rubinius bug
authored
25 ## Build Status
6248665 ready for use with limitations
Peter Ohler authored
26
da0330c getting the travis image to show status
Peter Ohler authored
27 [![Build Status](https://secure.travis-ci.org/ohler55/oj.png?branch=master)](http://travis-ci.org/ohler55/oj)
6248665 ready for use with limitations
Peter Ohler authored
28
c513991 @ohler55 Improved decimal conversions and added checking for non hash args in …
authored
29 ## Future Release 2.12.13
89c0da4 @ohler55 Cleaned up new test to work with 1.8.7. Also simplified new functions.
authored
30
c513991 @ohler55 Improved decimal conversions and added checking for non hash args in …
authored
31 - Added a check for the second argument to load() is a Hash.
89c0da4 @ohler55 Cleaned up new test to work with 1.8.7. Also simplified new functions.
authored
32
c513991 @ohler55 Improved decimal conversions and added checking for non hash args in …
authored
33 - Yet another attempt to make floating point numbers display better.
f6e2a40 @fxfilmxf use Oj::ParseError instead of SyntaxError if no callback and multiple…
fxfilmxf authored
34
1e499bb @ohler55 Updated readme
authored
35 - Thanks to mkillianey for getting the extconf.rb and gemspec file updated.
36
c513991 @ohler55 Improved decimal conversions and added checking for non hash args in …
authored
37 ## Current Release 2.12.12
38
39 - Thanks to asurin for adding support for arguments to to_json() that rails uses.
f6e2a40 @fxfilmxf use Oj::ParseError instead of SyntaxError if no callback and multiple…
fxfilmxf authored
40
11fd80a @ohler55 ready for release 2.1.0
authored
41 [Older release notes](http://www.ohler.com/dev/oj_misc/release_notes.html).
9061c07 @ohler55 enhanced mimic
authored
42
da3f12b @ohler55 added require bigdecimal to ruby file to work around rubinius bug
authored
43 ## Description
6248665 ready for use with limitations
Peter Ohler authored
44
1f08e57 @kookster Updated README
kookster authored
45 Optimized JSON (Oj), as the name implies, was written to provide speed optimized
46 JSON handling. It was designed as a faster alternative to Yajl and other
47 common Ruby JSON parsers. So far it has achieved that, and is about 2 times faster
48 than any other Ruby JSON parser, and 3 or more times faster at serializing JSON.
6248665 ready for use with limitations
Peter Ohler authored
49
25d9c78 @kookster A bit more editing
kookster authored
50 Oj has several `dump` or serialization modes which control how Ruby `Object`s are
1f08e57 @kookster Updated README
kookster authored
51 converted to JSON. These modes are set with the `:mode` option in either the
25d9c78 @kookster A bit more editing
kookster authored
52 default options or as one of the options to the `dump` method. The default mode
1f08e57 @kookster Updated README
kookster authored
53 is the `:object` mode.
e0fb1d3 updatings docs and notes
Peter Ohler authored
54
1f08e57 @kookster Updated README
kookster authored
55 - `:strict` mode will only allow the 7 basic JSON types to be serialized. Any
56 other `Object` will raise an `Exception`.
e0fb1d3 updatings docs and notes
Peter Ohler authored
57
1f08e57 @kookster Updated README
kookster authored
58 - `:null` mode replaces any `Object` that is not one of the JSON types with a JSON `null`.
e0fb1d3 updatings docs and notes
Peter Ohler authored
59
1f08e57 @kookster Updated README
kookster authored
60 - `:object` mode will dump any `Object` as a JSON `Object` with keys that match the
61 Ruby `Object`'s variable names without the '@' prefix character. This is the highest
11fd80a @ohler55 ready for release 2.1.0
authored
62 performance mode.
e0fb1d3 updatings docs and notes
Peter Ohler authored
63
1f08e57 @kookster Updated README
kookster authored
64 - `:compat` mode attempts to be compatible with other systems. It will serialize any
66262e3 @nyantani fixed README.md
nyantani authored
65 `Object`, but will check to see if the `Object` implements an `to_hash` or `to_json`
1f08e57 @kookster Updated README
kookster authored
66 method. If either exists, that method is used for serializing the `Object`.
25d9c78 @kookster A bit more editing
kookster authored
67 Since `as_json` is more flexible and produces more consistent output, it is
68 preferred over the `to_json` method. If neither the `to_json` or `to_hash`
1f08e57 @kookster Updated README
kookster authored
69 methods exists, then the Oj internal `Object` variable encoding is used.
70
75a27d7 @leschenko Add an example on how to change serialization mode
leschenko authored
71 To change default serialization mode:
72 ```ruby
7e9d5bc @ohler55 fixed readme
authored
73 Oj.default_options = {:mode => :compat }
75a27d7 @leschenko Add an example on how to change serialization mode
leschenko authored
74 ```
1f08e57 @kookster Updated README
kookster authored
75
76 ## Compatibility
8711c85 serializes any Object now. Tests added as well.
Peter Ohler authored
77
25d9c78 @kookster A bit more editing
kookster authored
78 ### Ruby
7020afc @igas Add ruby 2.2 to readme
igas authored
79 Oj is compatible with Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0, 2.1, 2.2 and RBX.
80 Support for JRuby has been removed as JRuby no longer supports C extensions and
81 there are bugs in the older versions that are not being fixed.
d4a2c32 updated readme
Peter Ohler authored
82
25d9c78 @kookster A bit more editing
kookster authored
83 ### Rails
9ac2e2e @kookster more edits top rails section
kookster authored
84 Although up until 4.1 Rails uses [multi_json](https://github.com/intridea/multi_json), an [issue in Rails](https://github.com/rails/rails/issues/9212) causes ActiveSupport to fail to make use Oj for JSON handling.
4f64aea @ohler55 added use_to_json option
authored
85 There is a
86 [gem to patch this](https://github.com/GoodLife/rails-patch-json-encode) for
87 Rails 3.2 and 4.0. As of the Oj 2.6.0 release the default behavior is to not use
88 the `to_json()` method unless the `:use_to_json` option is set. This provides
89 another work around to the rails older and newer behavior.
5b248cc added Bag class and auto_define flag
Peter Ohler authored
90
74af74c @ohler55 added rails note
authored
91 The latest ActiveRecord is able to work with Oj by simply using the line:
92 ```
93 serialize :my_attr, Oj
94 ```
95
9ac2e2e @kookster more edits top rails section
kookster authored
96 In version Rails 4.1, multi_json has been removed, and this patch is unnecessary and will no longer work.
97 Instead, use the `oj_mimic_json` [gem](https://github.com/ohler55/oj_mimic_json) along with `oj` in your `Gemfile` to have Oj mimic the JSON gem and be used in its place by `ActiveSupport` JSON handling:
1f08e57 @kookster Updated README
kookster authored
98 ```
99 gem 'oj'
100 gem 'oj_mimic_json'
101 ```
7c5f9b1 @ohler55 saj almost ready for release except for rbx
authored
102
da3f12b @ohler55 added require bigdecimal to ruby file to work around rubinius bug
authored
103 ## Proper Use
189a372 @ohler55 release 2.0.4
authored
104
1a6169c @igor-drozdov Fix a typo: vunerability -> vulnerability
igor-drozdov authored
105 Two settings in Oj are useful for parsing but do expose a vulnerability if used from an untrusted source. Symbolized
00b07f7 @gaurish Ruby 2.2 GC's collects Symbols as well
gaurish authored
106 keys can cause memory to be filled with previous versions of ruby. Ruby 2.1 and below does not garbage collect Symbols. The same is true for auto
107 defining classes in all versions of ruby; memory will also be exhausted if too many classes are automatically defined. Auto defining is a useful
25d9c78 @kookster A bit more editing
kookster authored
108 feature during development and from trusted sources but it allows too many classes to be created in the object load
109 mode and auto defined is used with an untrusted source. The `Oj.strict_load()` method sets and uses the most strict and safest options. It should be used by developers who find it difficult to understand the options available in Oj.
189a372 @ohler55 release 2.0.4
authored
110
111 The options in Oj are designed to provide flexibility to the developer. This flexibility allows Objects to be serialized
112 and deserialized. No methods are ever called on these created Objects but that does not stop the developer from calling
25d9c78 @kookster A bit more editing
kookster authored
113 methods on them. As in any system, check your inputs before working with them. Taking an arbitrary `String`
114 from a user and evaluating it is never a good idea from an unsecure source. The same is true for `Object` attributes as
115 they are not more than `String`s. Always check inputs from untrusted sources.
116
189a372 @ohler55 release 2.0.4
authored
117
25d9c78 @kookster A bit more editing
kookster authored
118 ## Simple JSON Writing and Parsing Example
6248665 ready for use with limitations
Peter Ohler authored
119
1d9b853 @ohler55 trying out different formats
authored
120 ```ruby
121 require 'oj'
7020afc @igas Add ruby 2.2 to readme
igas authored
122
1d9b853 @ohler55 trying out different formats
authored
123 h = { 'one' => 1, 'array' => [ true, false ] }
124 json = Oj.dump(h)
125
126 # json =
127 # {
128 # "one":1,
129 # "array":[
130 # true,
131 # false
132 # ]
133 # }
134
135 h2 = Oj.load(json)
136 puts "Same? #{h == h2}"
137 # true
138 ```
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
139
25d9c78 @kookster A bit more editing
kookster authored
140 ## Alternative JSON Processing APIs
1f08e57 @kookster Updated README
kookster authored
141
142 Oj offers a few alternative APIs for processing JSON. The fastest one is the `Oj::Doc` API. The `Oj::Doc` API takes a
143 completely different approach by opening a JSON document and providing calls to navigate around the JSON while it is
144 open. With this approach, JSON access can be well over 20 times faster than conventional JSON parsing.
145
146 The `Oj::Saj` and `Oj::ScHandler` APIs are callback parsers that
147 walk the JSON document depth first and makes callbacks for each element.
148 Both callback parser are useful when only portions of the JSON are of
149 interest. Performance up to 20 times faster than conventional JSON is
150 possible. The API is simple to use but does require a different approach than
151 the conventional parse followed by access approach used by conventional JSON
152 parsing.
153
154
11fd80a @ohler55 ready for release 2.1.0
authored
155 # Links
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
156
da3f12b @ohler55 added require bigdecimal to ruby file to work around rubinius bug
authored
157 ## Performance Comparisons
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
158
11fd80a @ohler55 ready for release 2.1.0
authored
159 [Oj Strict Mode Performance](http://www.ohler.com/dev/oj_misc/performance_strict.html) compares Oj strict mode parser performance to other JSON parsers.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
160
11fd80a @ohler55 ready for release 2.1.0
authored
161 [Oj Compat Mode Performance](http://www.ohler.com/dev/oj_misc/performance_compat.html) compares Oj compat mode parser performance to other JSON parsers.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
162
11fd80a @ohler55 ready for release 2.1.0
authored
163 [Oj Object Mode Performance](http://www.ohler.com/dev/oj_misc/performance_object.html) compares Oj object mode parser performance to other marshallers.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
164
11fd80a @ohler55 ready for release 2.1.0
authored
165 [Oj Callback Performance](http://www.ohler.com/dev/oj_misc/performance_callback.html) compares Oj callback parser performance to other JSON parsers.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
166
da3f12b @ohler55 added require bigdecimal to ruby file to work around rubinius bug
authored
167 ## Links of Interest
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
168
11fd80a @ohler55 ready for release 2.1.0
authored
169 *Fast XML parser and marshaller on RubyGems*: https://rubygems.org/gems/ox
4d28d2c updated readme with message format for object encoding
Peter Ohler authored
170
11fd80a @ohler55 ready for release 2.1.0
authored
171 *Fast XML parser and marshaller on GitHub*: https://github.com/ohler55/ox
6b22c57 finishing off circular reference implementation
Peter Ohler authored
172
11fd80a @ohler55 ready for release 2.1.0
authored
173 [Oj Object Encoding Format](http://www.ohler.com/dev/oj_misc/encoding_format.html) describes the OJ Object JSON encoding format.
fdacd8d added hash circular support
Peter Ohler authored
174
11fd80a @ohler55 ready for release 2.1.0
authored
175 [Need for Speed](http://www.ohler.com/dev/need_for_speed/need_for_speed.html) for an overview of how Oj::Doc was designed.
fdacd8d added hash circular support
Peter Ohler authored
176
447cf44 @ohler55 added JSON::ParserError alias
authored
177 *OjC, a C JSON parser*: https://www.ohler.com/ojc also at https://github.com/ohler55/ojc
Something went wrong with that request. Please try again.