D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
proc
/
self
/
root
/
proc
/
self
/
root
/
opt
/
alt
/
ruby32
/
share
/
gems
/
doc
/
json-2.16.0
/
ri
/
Filename :
page-README_md.ri
back
Copy
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