json 1.1.3 → 1.1.4

data/doc-templates/main.txt

@@ -0,0 +1,284 @@
+# = json - JSON for Ruby
+#
+# == Description
+#
+# This is a implementation of the JSON specification according to RFC 4627
+# (http://www.ietf.org/rfc/rfc4627.txt). Starting from version 1.0.0 on there
+# will be two variants available:
+#
+# * A pure ruby variant, that relies on the iconv and the stringscan
+#   extensions, which are both part of the ruby standard library.
+# * The quite a bit faster C extension variant, which is in parts implemented
+#   in C and comes with its own unicode conversion functions and a parser
+#   generated by the ragel state machine compiler
+#   (http://www.cs.queensu.ca/~thurston/ragel).
+#
+# Both variants of the JSON generator escape all non-ASCII an control
+# characters with \uXXXX escape sequences, and support UTF-16 surrogate pairs
+# in order to be able to generate the whole range of unicode code points. This
+# means that generated JSON text is encoded as UTF-8 (because ASCII is a subset
+# of UTF-8) and at the same time avoids decoding problems for receiving
+# endpoints, that don't expect UTF-8 encoded texts. On the negative side this
+# may lead to a bit longer strings than necessarry.
+#
+# All strings, that are to be encoded as JSON strings, should be UTF-8 byte
+# sequences on the Ruby side. To encode raw binary strings, that aren't UTF-8
+# encoded, please use the to_json_raw_object method of String (which produces
+# an object, that contains a byte array) and decode the result on the receiving
+# endpoint.
+#
+# == Author
+#
+# Florian Frank <mailto:flori@ping.de>
+#
+# == License
+#
+# This software is distributed under the same license as Ruby itself, see
+# http://www.ruby-lang.org/en/LICENSE.txt.
+#
+# == Download
+#
+# The latest version of this library can be downloaded at
+#
+# * http://rubyforge.org/frs?group_id=953
+#
+# Online Documentation should be located at
+#
+# * http://json.rubyforge.org
+#
+# == Usage
+# 
+# To use JSON you can
+#   require 'json'
+# to load the installed variant (either the extension 'json' or the pure
+# variant 'json_pure'). If you have installed the extension variant, you can
+# pick either the extension variant or the pure variant by typing
+#   require 'json/ext'
+# or
+#   require 'json/pure'
+#
+# You can choose to load a set of common additions to ruby core's objects if
+# you
+#   require 'json/add/core'
+#
+# After requiring this you can, e. g., serialise/deserialise Ruby ranges:
+#
+#   JSON JSON(1..10) # => 1..10
+#
+# To find out how to add JSON support to other or your own classes, read the
+# Examples section below.
+#
+# To get the best compatibility to rails' JSON implementation, you can
+#   require 'json/add/rails'
+#
+# Both of the additions attempt to require 'json' (like above) first, if it has
+# not been required yet.
+#
+# == Speed Comparisons
+#
+# I have created some benchmark results on on ruby 1.8.6 (2008-08-11
+# patchlevel 287) [i686-linux] (see the benchmarks/data-p4-3Ghz-ruby18
+# subdir of the package) for the JSON-parser to estimate the speed up in the C
+# extension:
+#
+#  Comparing times (call_time_mean):
+#   1 ParserBenchmarkExt#parser   900 repeats:
+#         553.922304770 (  real) ->   21.500x 
+#           0.001805307
+#   2 ParserBenchmarkYAML#parser  1000 repeats:
+#         224.513358139 (  real) ->    8.714x 
+#           0.004454078
+#   3 ParserBenchmarkPure#parser  1000 repeats:
+#          26.755020642 (  real) ->    1.038x 
+#           0.037376163
+#   4 ParserBenchmarkRails#parser 1000 repeats:
+#          25.763381731 (  real) ->    1.000x 
+#           0.038814780
+#             calls/sec (  time) ->    speed  covers
+#             secs/call
+#
+# In the table above 1 is JSON::Ext::Parser, 2 is YAML.load with YAML
+# compatbile JSON document, 3 is is JSON::Pure::Parser, and 4 is
+# ActiveSupport::JSON.decode. The ActiveSupport JSON-decoder converts the
+# input first to YAML and then uses the YAML-parser, the conversion seems to
+# slow it down so much that it is only as fast as the JSON::Pure::Parser!
+#
+# If you look at the benchmark data you can see that this is mostly caused by
+# the frequent high outliers - the median of the Rails-parser runs is still
+# overall smaller than the median of the JSON::Pure::Parser runs:
+#
+#  Comparing times (call_time_median):
+#   1 ParserBenchmarkExt#parser   900 repeats:
+#         800.592479481 (  real) ->   26.936x 
+#           0.001249075
+#   2 ParserBenchmarkYAML#parser  1000 repeats:
+#         271.002390644 (  real) ->    9.118x 
+#           0.003690004
+#   3 ParserBenchmarkRails#parser 1000 repeats:
+#          30.227910865 (  real) ->    1.017x 
+#           0.033082008
+#   4 ParserBenchmarkPure#parser  1000 repeats:
+#          29.722384421 (  real) ->    1.000x 
+#           0.033644676
+#             calls/sec (  time) ->    speed  covers
+#             secs/call
+#
+# I have benchmarked the JSON-Generator as well. This generated a few more
+# values, because there are different modes that also influence the achieved
+# speed:
+#
+#  Comparing times (call_time_mean):
+#   1 GeneratorBenchmarkExt#generator_fast    1000 repeats:
+#         547.354332608 (  real) ->   15.090x 
+#           0.001826970
+#   2 GeneratorBenchmarkExt#generator_safe    1000 repeats:
+#         443.968212317 (  real) ->   12.240x 
+#           0.002252414
+#   3 GeneratorBenchmarkExt#generator_pretty  900 repeats:
+#         375.104545883 (  real) ->   10.341x 
+#           0.002665923
+#   4 GeneratorBenchmarkPure#generator_fast   1000 repeats:
+#          49.978706968 (  real) ->    1.378x 
+#           0.020008521
+#   5 GeneratorBenchmarkRails#generator       1000 repeats:
+#          38.531868759 (  real) ->    1.062x 
+#           0.025952543
+#   6 GeneratorBenchmarkPure#generator_safe   1000 repeats:
+#          36.927649925 (  real) ->    1.018x 7 (>=3859)
+#           0.027079979
+#   7 GeneratorBenchmarkPure#generator_pretty 1000 repeats:
+#          36.272134441 (  real) ->    1.000x 6 (>=3859)
+#           0.027569373
+#             calls/sec (  time) ->    speed  covers
+#             secs/call
+#
+# In the table above 1-3 are JSON::Ext::Generator methods. 4, 6, and 7 are
+# JSON::Pure::Generator methods and 5 is the Rails JSON generator. It is now a
+# bit faster than the generator_safe and generator_pretty methods of the pure
+# variant but slower than the others.
+#
+# To achieve the fastest JSON text output, you can use the fast_generate
+# method. Beware, that this will disable the checking for circular Ruby data
+# structures, which may cause JSON to go into an infinite loop.
+#
+# Here are the median comparisons for completeness' sake:
+#
+#  Comparing times (call_time_median):
+#   1 GeneratorBenchmarkExt#generator_fast    1000 repeats:
+#         708.258020939 (  real) ->   16.547x 
+#           0.001411915
+#   2 GeneratorBenchmarkExt#generator_safe    1000 repeats:
+#         569.105020353 (  real) ->   13.296x 
+#           0.001757145
+#   3 GeneratorBenchmarkExt#generator_pretty  900 repeats:
+#         482.825371244 (  real) ->   11.280x 
+#           0.002071142
+#   4 GeneratorBenchmarkPure#generator_fast   1000 repeats:
+#          62.717626652 (  real) ->    1.465x 
+#           0.015944481
+#   5 GeneratorBenchmarkRails#generator       1000 repeats:
+#          43.965681162 (  real) ->    1.027x 
+#           0.022745013
+#   6 GeneratorBenchmarkPure#generator_safe   1000 repeats:
+#          43.929073409 (  real) ->    1.026x 7 (>=3859)
+#           0.022763968
+#   7 GeneratorBenchmarkPure#generator_pretty 1000 repeats:
+#          42.802514491 (  real) ->    1.000x 6 (>=3859)
+#           0.023363113
+#             calls/sec (  time) ->    speed  covers
+#             secs/call
+#
+# == Examples
+#
+# To create a JSON text from a ruby data structure, you can call JSON.generate
+# like that:
+#
+#  json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
+#  # => "[1,2,{\"a\":3.141},false,true,null,\"4..10\"]"
+#
+# To create a valid JSON text you have to make sure, that the output is
+# embedded in either a JSON array [] or a JSON object {}. The easiest way to do
+# this, is by putting your values in a Ruby Array or Hash instance.
+#
+# To get back a ruby data structure from a JSON text, you have to call
+# JSON.parse on it:
+#
+#  JSON.parse json
+#  # => [1, 2, {"a"=>3.141}, false, true, nil, "4..10"]
+# 
+# Note, that the range from the original data structure is a simple
+# string now. The reason for this is, that JSON doesn't support ranges
+# or arbitrary classes. In this case the json library falls back to call
+# Object#to_json, which is the same as #to_s.to_json.
+#
+# It's possible to add JSON support serialization to arbitrary classes by
+# simply implementing a more specialized version of the #to_json method, that
+# should return a JSON object (a hash converted to JSON with #to_json) like
+# this (don't forget the *a for all the arguments):
+#
+#  class Range
+#    def to_json(*a)
+#      {
+#        'json_class'   => self.class.name, # = 'Range'
+#        'data'         => [ first, last, exclude_end? ]
+#      }.to_json(*a)
+#    end
+#  end
+#
+# The hash key 'json_class' is the class, that will be asked to deserialise the
+# JSON representation later. In this case it's 'Range', but any namespace of
+# the form 'A::B' or '::A::B' will do. All other keys are arbitrary and can be
+# used to store the necessary data to configure the object to be deserialised.
+#
+# If a the key 'json_class' is found in a JSON object, the JSON parser checks
+# if the given class responds to the json_create class method. If so, it is
+# called with the JSON object converted to a Ruby hash. So a range can
+# be deserialised by implementing Range.json_create like this:
+# 
+#  class Range
+#    def self.json_create(o)
+#      new(*o['data'])
+#    end
+#  end
+#
+# Now it possible to serialise/deserialise ranges as well:
+#
+#  json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
+#  # => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]"
+#  JSON.parse json
+#  # => [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
+#
+# JSON.generate always creates the shortest possible string representation of a
+# ruby data structure in one line. This good for data storage or network
+# protocols, but not so good for humans to read. Fortunately there's also
+# JSON.pretty_generate (or JSON.pretty_generate) that creates a more
+# readable output:
+#
+#  puts JSON.pretty_generate([1, 2, {"a"=>3.141}, false, true, nil, 4..10])
+#  [
+#    1,
+#    2,
+#    {
+#      "a": 3.141
+#    },
+#    false,
+#    true,
+#    null,
+#    {
+#      "json_class": "Range",
+#      "data": [
+#        4,
+#        10,
+#        false
+#      ]
+#    }
+#  ]
+#
+# There are also the methods Kernel#j for generate, and Kernel#jj for
+# pretty_generate output to the console, that work analogous to Core Ruby's p
+# and the pp library's pp methods.
+#
+# The script tools/server.rb contains a small example if you want to test, how
+# receiving a JSON object from a webrick server in your browser with the
+# javasript prototype library (http://www.prototypejs.org) works.
+#

data/ext/json/ext/generator/extconf.rb

@@ -6,4 +6,6 @@ if CONFIG['CC'] =~ /gcc/
   #$CFLAGS += ' -O0 -ggdb'
 end
 
+have_header("ruby/st.h") || have_header("st.h")
+have_header("ruby/encoding.h")
 create_makefile 'generator'

data/ext/json/ext/generator/generator.c

@@ -1,9 +1,33 @@
 #include <string.h>
 #include "ruby.h"
+#if HAVE_RUBY_ST_H
+#include "ruby/st.h"
+#endif
+#if HAVE_ST_H
 #include "st.h"
+#endif
 #include "unicode.h"
 #include <math.h>
 
+#ifndef RHASH_TBL
+#define RHASH_TBL(hsh) (RHASH(hsh)->tbl)
+#endif
+
+#ifndef RHASH_SIZE
+#define RHASH_SIZE(hsh) (RHASH(hsh)->tbl->num_entries)
+#endif
+
+#ifndef RFLOAT_VALUE
+#define RFLOAT_VALUE(val) (RFLOAT(val)->value)
+#endif
+
+#ifdef HAVE_RUBY_ENCODING_H
+#include "ruby/encoding.h"
+#define FORCE_UTF8(obj) rb_enc_associate((obj), rb_utf8_encoding())
+#else
+#define FORCE_UTF8(obj)
+#endif
+
 #define check_max_nesting(state, depth) do {                                   \
     long current_nesting = 1 + depth;                                          \
     if (state->max_nesting != 0 && current_nesting > state->max_nesting)       \
@@ -86,7 +110,7 @@ static int hash_to_json_state_i(VALUE key, VALUE value, VALUE Vstate)
 }
 
 inline static VALUE mHash_json_transfrom(VALUE self, VALUE Vstate, VALUE Vdepth) {
-    long depth, len = RHASH(self)->tbl->num_entries;
+    long depth, len = RHASH_SIZE(self);
     VALUE result;
     GET_STATE(Vstate);
 
@@ -142,7 +166,7 @@ static VALUE mHash_to_json(int argc, VALUE *argv, VALUE self)
     rb_scan_args(argc, argv, "02", &Vstate, &Vdepth);
     depth = NIL_P(Vdepth) ? 0 : FIX2LONG(Vdepth);
     if (NIL_P(Vstate)) {
-        long len = RHASH(self)->tbl->num_entries;
+        long len = RHASH_SIZE(self);
         result = rb_str_buf_new(len);
         rb_str_buf_cat2(result, "{");
         rb_hash_foreach(self, hash_to_json_i, result);
@@ -164,6 +188,7 @@ static VALUE mHash_to_json(int argc, VALUE *argv, VALUE self)
         }
     }
     OBJ_INFECT(result, self);
+    FORCE_UTF8(result);
     return result;
 }
 
@@ -261,6 +286,7 @@ static VALUE mArray_to_json(int argc, VALUE *argv, VALUE self) {
         result = mArray_json_transfrom(self, Vstate, Vdepth);
     }
     OBJ_INFECT(result, self);
+    FORCE_UTF8(result);
     return result;
 }
 
@@ -271,7 +297,9 @@ static VALUE mArray_to_json(int argc, VALUE *argv, VALUE self) {
  */
 static VALUE mInteger_to_json(int argc, VALUE *argv, VALUE self)
 {
-    return rb_funcall(self, i_to_s, 0);
+    VALUE result = rb_funcall(self, i_to_s, 0);
+    FORCE_UTF8(result);
+    return result;
 }
 
 /*
@@ -282,27 +310,29 @@ static VALUE mInteger_to_json(int argc, VALUE *argv, VALUE self)
 static VALUE mFloat_to_json(int argc, VALUE *argv, VALUE self)
 {
     JSON_Generator_State *state = NULL;
-    VALUE Vstate, rest, tmp;
-    double value = RFLOAT(self)->value;
+    VALUE Vstate, rest, tmp, result;
+    double value = RFLOAT_VALUE(self);
     rb_scan_args(argc, argv, "01*", &Vstate, &rest);
     if (!NIL_P(Vstate)) Data_Get_Struct(Vstate, JSON_Generator_State, state);
     if (isinf(value)) {
         if (!state || state->allow_nan) {
-            return rb_funcall(self, i_to_s, 0);
+            result = rb_funcall(self, i_to_s, 0);
         } else {
             tmp = rb_funcall(self, i_to_s, 0);
             rb_raise(eGeneratorError, "%u: %s not allowed in JSON", __LINE__, StringValueCStr(tmp));
         }
     } else if (isnan(value)) {
         if (!state || state->allow_nan) {
-            return rb_funcall(self, i_to_s, 0);
+            result = rb_funcall(self, i_to_s, 0);
         } else {
             tmp = rb_funcall(self, i_to_s, 0);
             rb_raise(eGeneratorError, "%u: %s not allowed in JSON", __LINE__, StringValueCStr(tmp));
         }
     } else {
-        return rb_funcall(self, i_to_s, 0);
+        result = rb_funcall(self, i_to_s, 0);
     }
+    FORCE_UTF8(result);
+    return result;
 }
 
 /*
@@ -311,7 +341,9 @@ static VALUE mFloat_to_json(int argc, VALUE *argv, VALUE self)
  * Extends _modul_ with the String::Extend module.
  */
 static VALUE mString_included_s(VALUE self, VALUE modul) {
-    return rb_funcall(modul, i_extend, 1, mString_Extend);
+    VALUE result = rb_funcall(modul, i_extend, 1, mString_Extend);
+    FORCE_UTF8(result);
+    return result;
 }
 
 /*
@@ -327,6 +359,7 @@ static VALUE mString_to_json(int argc, VALUE *argv, VALUE self)
     rb_str_buf_cat2(result, "\"");
     JSON_convert_UTF8_to_JSON(result, self, strictConversion);
     rb_str_buf_cat2(result, "\"");
+    FORCE_UTF8(result);
     return result;
 }
 
@@ -344,6 +377,7 @@ static VALUE mString_to_json_raw_object(VALUE self) {
     rb_hash_aset(result, rb_funcall(mJSON, i_create_id, 0), rb_class_name(rb_obj_class(self)));
     ary = rb_funcall(self, i_unpack, 1, rb_str_new2("C*"));
     rb_hash_aset(result, rb_str_new2("raw"), ary);
+    FORCE_UTF8(result);
     return result;
 }
 
@@ -354,9 +388,11 @@ static VALUE mString_to_json_raw_object(VALUE self) {
  * to_json_raw_object of this String.
  */
 static VALUE mString_to_json_raw(int argc, VALUE *argv, VALUE self) {
-    VALUE obj = mString_to_json_raw_object(self);
+    VALUE result, obj = mString_to_json_raw_object(self);
     Check_Type(obj, T_HASH);
-    return mHash_to_json(argc, argv, obj);
+    result = mHash_to_json(argc, argv, obj);
+    FORCE_UTF8(result);
+    return result;
 }
 
 /*
@@ -379,7 +415,9 @@ static VALUE mString_Extend_json_create(VALUE self, VALUE o) {
  */
 static VALUE mTrueClass_to_json(int argc, VALUE *argv, VALUE self)
 {
-    return rb_str_new2("true");
+    VALUE result = rb_str_new2("true");
+    FORCE_UTF8(result);
+    return result;
 }
 
 /*
@@ -389,7 +427,9 @@ static VALUE mTrueClass_to_json(int argc, VALUE *argv, VALUE self)
  */
 static VALUE mFalseClass_to_json(int argc, VALUE *argv, VALUE self)
 {
-    return rb_str_new2("false");
+    VALUE result = rb_str_new2("false");
+    FORCE_UTF8(result);
+    return result;
 }
 
 /*
@@ -398,7 +438,9 @@ static VALUE mFalseClass_to_json(int argc, VALUE *argv, VALUE self)
  */
 static VALUE mNilClass_to_json(int argc, VALUE *argv, VALUE self)
 {
-    return rb_str_new2("null");
+    VALUE result = rb_str_new2("null");
+    FORCE_UTF8(result);
+    return result;
 }
 
 /*
@@ -410,9 +452,11 @@ static VALUE mNilClass_to_json(int argc, VALUE *argv, VALUE self)
  */
 static VALUE mObject_to_json(int argc, VALUE *argv, VALUE self)
 {
-    VALUE string = rb_funcall(self, i_to_s, 0);
+    VALUE result, string = rb_funcall(self, i_to_s, 0);
     Check_Type(string, T_STRING);
-    return mString_to_json(argc, argv, string);
+    result = mString_to_json(argc, argv, string);
+    FORCE_UTF8(result);
+    return result;
 }
 
 /* 
@@ -488,7 +532,7 @@ static inline VALUE cState_configure(VALUE self, VALUE opts)
         state->object_nl = tmp;
     }
     tmp = ID2SYM(i_check_circular);
-    if (st_lookup(RHASH(opts)->tbl, tmp, 0)) {
+    if (st_lookup(RHASH_TBL(opts), tmp, 0)) {
         tmp = rb_hash_aref(opts, ID2SYM(i_check_circular));
         state->check_circular = RTEST(tmp);
     } else {
@@ -496,7 +540,7 @@ static inline VALUE cState_configure(VALUE self, VALUE opts)
     }
     tmp = ID2SYM(i_max_nesting);
     state->max_nesting = 19;
-    if (st_lookup(RHASH(opts)->tbl, tmp, 0)) {
+    if (st_lookup(RHASH_TBL(opts), tmp, 0)) {
         VALUE max_nesting = rb_hash_aref(opts, tmp);
         if (RTEST(max_nesting)) {
             Check_Type(max_nesting, T_FIXNUM);