1#@!#!123s

: / proc / self / root / proc / self / root / opt / alt / ruby32 / share / gems / doc / json-2.16.0 / ri /
Filename : page-README_md.ri
back
U:RDoc::TopLevel[	i�I"README.md:ETcRDoc::Parser::Markdowno:RDoc::Markup::Document:@parts[MS:RDoc::Markup::Heading:
leveli:	textI"!JSON implementation for Ruby;To:RDoc::Markup::Paragraph;[I"�{rdoc-image:https://github.com/ruby/json/actions/workflows/ci.yml/badge.svg}[https://github.com/ruby/json/actions/workflows/ci.yml];TS;	;
i;I"Description;To;;[I"tThis is an implementation of the JSON specification according to RFC 7159
http://www.ietf.org/rfc/rfc7159.txt .;To;;[I"0The JSON generator generate UTF-8 character sequences by default.
If an :ascii_only option with a true value is given, they escape all
non-ASCII and 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.;To;;[I"9All 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.;TS;	;
i;I"Installation;To;;[I"GInstall the gem and add to the application's Gemfile by executing:;To:RDoc::Markup::Verbatim;[I"$ bundle add json
;T:@format0o;;[I"WIf bundler is not being used to manage dependencies, install the gem by executing:;To;
;[I"$ gem install json
;T;0S;	;
i;I"Basic Usage;To;;[I"To use JSON you can;To;
;[I"require 'json'
;T;:	rubyo;;[I"LNow you can parse a JSON document into a ruby data structure by calling;To;
;[I"JSON.parse(document)
;T;;o;;[I"LIf you want to generate a JSON document from a ruby data structure call;To;
;[I"JSON.generate(data)
;T;;o;;[I"�You can also use the <code>pretty_generate</code> method (which formats the output more
verbosely and nicely) or <code>fast_generate</code> (which doesn't do any of the security
checks generate performs, e. g. nesting deepness checks).;TS;	;
i;I"Casting non native types;To;;[I"RJSON documents can only support Hashes, Arrays, Strings, Integers and Floats.;To;;[I"�By default if you attempt to serialize something else, <code>JSON.generate</code> will
search for a <code>#to_json</code> method on that object:;To;
;[I"�Position = Struct.new(:latitude, :longitude) do
  def to_json(state = nil, *)
    JSON::State.from_state(state).generate({
      latitude: latitude,
      longitude: longitude,
    })
  end
end

JSON.generate([
  Position.new(12323.234, 435345.233),
  Position.new(23434.676, 159435.324),
]) # => [{"latitude":12323.234,"longitude":435345.233},{"latitude":23434.676,"longitude":159435.324}]
;T;;o;;[I"�If a <code>#to_json</code> method isn't defined on the object, <code>JSON.generate</code> will fallback to call <code>#to_s</code>:;To;
;[I"CJSON.generate(Object.new) # => "#<Object:0x000000011e768b98>"
;T;;o;;[I"WBoth of these behavior can be disabled using the <code>strict: true</code> option:;To;
;[I"�JSON.generate(Object.new, strict: true) # => Object not allowed in JSON (JSON::GeneratorError)
JSON.generate(Position.new(1, 2)) # => Position not allowed in JSON (JSON::GeneratorError)
;T;;S;	;
i;I"JSON::Coder;To;;[I"�Since <code>#to_json</code> methods are global, it can sometimes be problematic if you need a given type to be
serialized in different ways in different locations.;To;;[I"MInstead it is recommended to use the newer <code>JSON::Coder</code> API:;To;
;[I"�module MyApp
  API_JSON_CODER = JSON::Coder.new do |object, is_object_key|
    case object
    when Time
      object.iso8601(3)
    else
      object
    end
  end
end

puts MyApp::API_JSON_CODER.dump(Time.now.utc) # => "2025-01-21T08:41:44.286Z"
;T;;o;;[I"�The provided block is called for all objects that don't have a native JSON equivalent, and
must return a Ruby object that has a native JSON equivalent.;To;;[I"�It is also called for objects that do have a JSON equivalent, but are used as Hash keys, for instance <code>{ 1 => 2}</code>,
as well as for strings that aren't valid UTF-8:;To;
;[I"�coder = JSON::Combining.new do |object, is_object_key|
  case object
  when String
    if !string.valid_encoding? || string.encoding != Encoding::UTF_8
      Base64.encode64(string)
    else
      string
    end
  else
    object
  end
end
;T;;S;	;
i;I"Combining JSON fragments;To;;[I"dTo combine JSON fragments into a bigger JSON document, you can use <code>JSON::Fragment</code>:;To;
;[I"�posts_json = cache.fetch_multi(post_ids) do |post_id|
  JSON.generate(Post.find(post_id))
end
posts_json.map! { |post_json| JSON::Fragment.new(post_json) }
JSON.generate({ posts: posts_json, count: posts_json.count })
;T;;S;	;
i;I"#Round-tripping arbitrary types;To:RDoc::Markup::BlockQuote;[o;;[I"�[!CAUTION]
You should never use <code>JSON.unsafe_load</code> nor <code>JSON.parse(str, create_additions: true)</code> to parse untrusted user input,
as it can lead to remote code execution vulnerabilities.;To;;[I"mTo create a JSON document from a ruby data structure, you can call
<code>JSON.generate</code> like that:;To;
;[I"}json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
# => "[1,2,{\"a\":3.141},false,true,null,\"4..10\"]"
;T;;o;;[I"_To get back a ruby data structure from a JSON document, you have to call
JSON.parse on it:;To;
;[I"JJSON.parse json
# => [1, 2, {"a"=>3.141}, false, true, nil, "4..10"]
;T;;o;;[I"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
<code>Object#to_json</code>, which is the same as <code>#to_s.to_json</code>.;To;;[I"6It's possible to add JSON support serialization to arbitrary classes by
simply implementing a more specialized version of the <code>#to_json method</code>, that
should return a JSON object (a hash converted to JSON with <code>#to_json</code>) like
this (don't forget the <code>*a</code> for all the arguments):;To;
;[I"�class Range
  def to_json(*a)
    {
      'json_class'   => self.class.name, # = 'Range'
      'data'         => [ first, last, exclude_end? ]
    }.to_json(*a)
  end
end
;T;;o;;[I"^The hash key <code>json_class</code> is the class, that will be asked to deserialise the
JSON representation later. In this case it's <code>Range</code>, but any namespace of
the form <code>A::B</code> or <code>::A::B</code> will do. All other keys are arbitrary and can be
used to store the necessary data to configure the object to be deserialised.;To;;[I":If the key <code>json_class</code> is found in a JSON object, the JSON parser checks
if the given class responds to the <code>json_create</code> class method. If so, it is
called with the JSON object converted to a Ruby hash. So a range can
be deserialised by implementing <code>Range.json_create</code> like this:;To;
;[I"Iclass Range
  def self.json_create(o)
    new(*o['data'])
  end
end
;T;;o;;[I"=Now it possible to serialise/deserialise ranges as well:;To;
;[I"�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 = 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.unsafe_load json
# => [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
;T;;o;;[I"Z<code>JSON.generate</code> always creates the shortest possible string representation of a
ruby data structure in one line. This is good for data storage or network
protocols, but not so good for humans to read. Fortunately there's also
<code>JSON.pretty_generate</code> (or <code>JSON.pretty_generate</code>) that creates a more readable
output:;To;
;[I"�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
     ]
   }
 ]
;T;;o;;[I"�There are also the methods <code>Kernel#j</code> for generate, and <code>Kernel#jj</code> for
<code>pretty_generate</code> output to the console, that work analogous to Core Ruby's <code>p</code> and
the <code>pp</code> library's <code>pp</code> methods.;TS;	;
i;I"Development;TS;	;
i;I"Prerequisites;To:RDoc::Markup::List:
@type:NUMBER:@items[o:RDoc::Markup::ListItem:@label0;[o;;[I"Clone the repository;To;;0;[o;;[I":Install dependencies with <code>bundle install</code>;TS;	;
i;I"Testing;To;;[I")The full test suite can be run with:;To;
;[I"bundle exec rake test
;T;:	bashS;	;
i;I"Release;To;;[I"6Update the <code>lib/json/version.rb</code> file.;To;
;[I"�rbenv shell 2.6.5
rake build
gem push pkg/json-2.3.0.gem

rbenv shell jruby-9.2.9.0
rake build
gem push pkg/json-2.3.0-java.gem
;T;0S;	;
i;I"Author;To;;[I"'Florian Frank mailto:flori@ping.de;TS;	;
i;I"License;To;;[I"FRuby License, see https://www.ruby-lang.org/en/about/license.txt.;TS;	;
i;I"
Download;To;;[I"<The latest version of this library can be downloaded at;To;;:BULLET;[o;;0;[o;;[I"#https://rubygems.org/gems/json;To;;[I".Online Documentation should be located at;To;;;;[o;;0;[o;;[I"'https://www.rubydoc.info/gems/json;T:
@file@:0@omit_headings_from_table_of_contents_below0