diff options
author | Florian Frank <flori@ping.de> | 2015-11-06 16:40:46 +0100 |
---|---|---|
committer | Florian Frank <flori@ping.de> | 2015-11-06 16:44:27 +0100 |
commit | 5ec2b17a06275726770bb8f7bf38659e07125172 (patch) | |
tree | 725ad25e43021b11bbeb9889b55df31a73b83cfe | |
parent | 5f1c9589fadf07ca8bd86ff42b491fcb6332e0ff (diff) | |
download | json-5ec2b17a06275726770bb8f7bf38659e07125172.tar.gz |
Convert README to markdown
-rw-r--r-- | README.md (renamed from README.rdoc) | 52 | ||||
-rw-r--r-- | Rakefile | 8 | ||||
-rw-r--r-- | json.gemspec | bin | 4736 -> 4730 bytes | |||
-rw-r--r-- | json_pure.gemspec | 10 |
4 files changed, 35 insertions, 35 deletions
@@ -1,6 +1,6 @@ -= JSON implementation for Ruby {<img src="https://secure.travis-ci.org/flori/json.png" />}[http://travis-ci.org/flori/json] +# JSON implementation for Ruby {<img src="https://secure.travis-ci.org/flori/json.png" />}[http://travis-ci.org/flori/json] -== Description +## 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 @@ -14,14 +14,14 @@ will be two variants available: http://www.complang.org/ragel/ . Both variants of the JSON generator generate UTF-8 character sequences by -default. If an :ascii_only option with a true value is given, they escape all +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. 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 +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. @@ -32,7 +32,7 @@ String#encoding set. If a document string has ASCII-8BIT as an encoding the parser attempts to figure out which of the UTF encodings from above it is and trys to parse it. -== Installation +## Installation It's recommended to use the extension variant of JSON, because it's faster than the pure ruby variant. If you cannot build it on your system, you can settle @@ -63,18 +63,18 @@ with: # gem install json_pure -== Compiling the extensions yourself +## Compiling the extensions yourself If you want to create the parser.c file from its parser.rl file or draw nice graphviz images of the state machines, you need ragel from: http://www.complang.org/ragel/ -== Usage +## 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 +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 @@ -87,8 +87,8 @@ Now you can parse a JSON document into a ruby data structure by calling If you want to generate a JSON document from a ruby data structure call JSON.generate(data) -You can also use the pretty_generate method (which formats the output more -verbosely and nicely) or fast_generate (which doesn't do any of the security +You can also use the pretty\_generate method (which formats the output more +verbosely and nicely) or fast\_generate (which doesn't do any of the security checks generate performs, e. g. nesting deepness checks). To create a valid JSON document you have to make sure, that the output is @@ -123,7 +123,7 @@ To get the best compatibility to rails' JSON implementation, you can Both of the additions attempt to require 'json' (like above) first, if it has not been required yet. -== More Examples +## More Examples To create a JSON document from a ruby data structure, you can call JSON.generate like that: @@ -140,11 +140,11 @@ JSON.parse on it: 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. +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 +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 @@ -156,15 +156,15 @@ this (don't forget the *a for all the arguments): end end -The hash key 'json_class' is the class, that will be asked to deserialise the +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 +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: +be deserialised by implementing Range.json\_create like this: class Range def self.json_create(o) @@ -182,7 +182,7 @@ Now it possible to serialise/deserialise ranges as well: JSON.generate 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 -JSON.pretty_generate (or JSON.pretty_generate) that creates a more readable +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]) @@ -206,14 +206,14 @@ output: ] 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 +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. -== Speed Comparisons +## Speed Comparisons I have created some benchmark results (see the benchmarks/data-p4-3Ghz subdir of the package) for the JSON-parser to estimate the speed up in the C @@ -292,10 +292,10 @@ speed: 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 +bit faster than the generator\_safe and generator\_pretty methods of the pure variant but slower than the others. -To achieve the fastest JSON document output, you can use the fast_generate +To achieve the fastest JSON document 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. @@ -326,15 +326,15 @@ Here are the median comparisons for completeness' sake: calls/sec ( time) -> speed covers secs/call -== Author +## Author Florian Frank <mailto:flori@ping.de> -== License +## License Ruby License, see https://www.ruby-lang.org/en/about/license.txt. -== Download +## Download The latest version of this library can be downloaded at @@ -86,9 +86,9 @@ if defined?(Gem) and defined?(Gem::PackageTask) s.add_development_dependency 'permutation' s.add_development_dependency 'rake' - s.extra_rdoc_files << 'README.rdoc' + s.extra_rdoc_files << 'README.md' s.rdoc_options << - '--title' << 'JSON implemention for ruby' << '--main' << 'README.rdoc' + '--title' << 'JSON implemention for ruby' << '--main' << 'README.md' s.test_files.concat Dir['./tests/test_*.rb'] s.author = "Florian Frank" @@ -122,9 +122,9 @@ if defined?(Gem) and defined?(Gem::PackageTask) s.require_path = 'lib' s.add_development_dependency 'permutation' - s.extra_rdoc_files << 'README.rdoc' + s.extra_rdoc_files << 'README.md' s.rdoc_options << - '--title' << 'JSON implemention for Ruby' << '--main' << 'README.rdoc' + '--title' << 'JSON implemention for Ruby' << '--main' << 'README.md' s.test_files.concat Dir['./tests/test_*.rb'] s.author = "Florian Frank" diff --git a/json.gemspec b/json.gemspec Binary files differindex 35efb0e..2865776 100644 --- a/json.gemspec +++ b/json.gemspec diff --git a/json_pure.gemspec b/json_pure.gemspec index 3020176..0ac2236 100644 --- a/json_pure.gemspec +++ b/json_pure.gemspec @@ -8,15 +8,15 @@ Gem::Specification.new do |s| s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version= s.require_paths = ["lib"] s.authors = ["Florian Frank"] - s.date = "2015-10-20" + s.date = "2015-11-06" s.description = "This is a JSON implementation in pure Ruby." s.email = "flori@ping.de" - s.extra_rdoc_files = ["README.rdoc"] - s.files = ["./tests/test_json.rb", "./tests/test_json_addition.rb", "./tests/test_json_encoding.rb", "./tests/test_json_fixtures.rb", "./tests/test_json_generate.rb", "./tests/test_json_generic_object.rb", "./tests/test_json_string_matching.rb", "./tests/test_json_unicode.rb", ".gitignore", ".travis.yml", "CHANGES", "Gemfile", "README-json-jruby.markdown", "README.rdoc", "Rakefile", "TODO", "VERSION", "data/example.json", "data/index.html", "data/prototype.js", "diagrams/.keep", "ext/json/ext/fbuffer/fbuffer.h", "ext/json/ext/generator/depend", "ext/json/ext/generator/extconf.rb", "ext/json/ext/generator/generator.c", "ext/json/ext/generator/generator.h", "ext/json/ext/parser/depend", "ext/json/ext/parser/extconf.rb", "ext/json/ext/parser/parser.c", "ext/json/ext/parser/parser.h", "ext/json/ext/parser/parser.rl", "ext/json/extconf.rb", "install.rb", "java/src/json/ext/ByteListTranscoder.java", "java/src/json/ext/Generator.java", "java/src/json/ext/GeneratorMethods.java", "java/src/json/ext/GeneratorService.java", "java/src/json/ext/GeneratorState.java", "java/src/json/ext/OptionsReader.java", "java/src/json/ext/Parser.java", "java/src/json/ext/Parser.rl", "java/src/json/ext/ParserService.java", "java/src/json/ext/RuntimeInfo.java", "java/src/json/ext/StringDecoder.java", "java/src/json/ext/StringEncoder.java", "java/src/json/ext/Utils.java", "json-java.gemspec", "json.gemspec", "json_pure.gemspec", "lib/json.rb", "lib/json/add/bigdecimal.rb", "lib/json/add/complex.rb", "lib/json/add/core.rb", "lib/json/add/date.rb", "lib/json/add/date_time.rb", "lib/json/add/exception.rb", "lib/json/add/ostruct.rb", "lib/json/add/range.rb", "lib/json/add/rational.rb", "lib/json/add/regexp.rb", "lib/json/add/struct.rb", "lib/json/add/symbol.rb", "lib/json/add/time.rb", "lib/json/common.rb", "lib/json/ext.rb", "lib/json/ext/.keep", "lib/json/generic_object.rb", "lib/json/pure.rb", "lib/json/pure/generator.rb", "lib/json/pure/parser.rb", "lib/json/version.rb", "tests/fixtures/fail1.json", "tests/fixtures/fail10.json", "tests/fixtures/fail11.json", "tests/fixtures/fail12.json", "tests/fixtures/fail13.json", "tests/fixtures/fail14.json", "tests/fixtures/fail18.json", "tests/fixtures/fail19.json", "tests/fixtures/fail2.json", "tests/fixtures/fail20.json", "tests/fixtures/fail21.json", "tests/fixtures/fail22.json", "tests/fixtures/fail23.json", "tests/fixtures/fail24.json", "tests/fixtures/fail25.json", "tests/fixtures/fail27.json", "tests/fixtures/fail28.json", "tests/fixtures/fail3.json", "tests/fixtures/fail4.json", "tests/fixtures/fail5.json", "tests/fixtures/fail6.json", "tests/fixtures/fail7.json", "tests/fixtures/fail8.json", "tests/fixtures/fail9.json", "tests/fixtures/pass1.json", "tests/fixtures/pass15.json", "tests/fixtures/pass16.json", "tests/fixtures/pass17.json", "tests/fixtures/pass2.json", "tests/fixtures/pass26.json", "tests/fixtures/pass3.json", "tests/setup_variant.rb", "tests/test_json.rb", "tests/test_json_addition.rb", "tests/test_json_encoding.rb", "tests/test_json_fixtures.rb", "tests/test_json_generate.rb", "tests/test_json_generic_object.rb", "tests/test_json_string_matching.rb", "tests/test_json_unicode.rb", "tools/fuzz.rb", "tools/server.rb"] + s.extra_rdoc_files = ["README.md"] + s.files = ["./tests/test_json.rb", "./tests/test_json_addition.rb", "./tests/test_json_encoding.rb", "./tests/test_json_fixtures.rb", "./tests/test_json_generate.rb", "./tests/test_json_generic_object.rb", "./tests/test_json_string_matching.rb", "./tests/test_json_unicode.rb", ".gitignore", ".travis.yml", "CHANGES", "Gemfile", "README-json-jruby.markdown", "README.md", "Rakefile", "TODO", "VERSION", "data/example.json", "data/index.html", "data/prototype.js", "diagrams/.keep", "ext/json/ext/fbuffer/fbuffer.h", "ext/json/ext/generator/depend", "ext/json/ext/generator/extconf.rb", "ext/json/ext/generator/generator.c", "ext/json/ext/generator/generator.h", "ext/json/ext/parser/depend", "ext/json/ext/parser/extconf.rb", "ext/json/ext/parser/parser.c", "ext/json/ext/parser/parser.h", "ext/json/ext/parser/parser.rl", "ext/json/extconf.rb", "install.rb", "java/src/json/ext/ByteListTranscoder.java", "java/src/json/ext/Generator.java", "java/src/json/ext/GeneratorMethods.java", "java/src/json/ext/GeneratorService.java", "java/src/json/ext/GeneratorState.java", "java/src/json/ext/OptionsReader.java", "java/src/json/ext/Parser.java", "java/src/json/ext/Parser.rl", "java/src/json/ext/ParserService.java", "java/src/json/ext/RuntimeInfo.java", "java/src/json/ext/StringDecoder.java", "java/src/json/ext/StringEncoder.java", "java/src/json/ext/Utils.java", "json-java.gemspec", "json.gemspec", "json_pure.gemspec", "lib/json.rb", "lib/json/add/bigdecimal.rb", "lib/json/add/complex.rb", "lib/json/add/core.rb", "lib/json/add/date.rb", "lib/json/add/date_time.rb", "lib/json/add/exception.rb", "lib/json/add/ostruct.rb", "lib/json/add/range.rb", "lib/json/add/rational.rb", "lib/json/add/regexp.rb", "lib/json/add/struct.rb", "lib/json/add/symbol.rb", "lib/json/add/time.rb", "lib/json/common.rb", "lib/json/ext.rb", "lib/json/ext/.keep", "lib/json/generic_object.rb", "lib/json/pure.rb", "lib/json/pure/generator.rb", "lib/json/pure/parser.rb", "lib/json/version.rb", "tests/fixtures/fail1.json", "tests/fixtures/fail10.json", "tests/fixtures/fail11.json", "tests/fixtures/fail12.json", "tests/fixtures/fail13.json", "tests/fixtures/fail14.json", "tests/fixtures/fail18.json", "tests/fixtures/fail19.json", "tests/fixtures/fail2.json", "tests/fixtures/fail20.json", "tests/fixtures/fail21.json", "tests/fixtures/fail22.json", "tests/fixtures/fail23.json", "tests/fixtures/fail24.json", "tests/fixtures/fail25.json", "tests/fixtures/fail27.json", "tests/fixtures/fail28.json", "tests/fixtures/fail3.json", "tests/fixtures/fail4.json", "tests/fixtures/fail5.json", "tests/fixtures/fail6.json", "tests/fixtures/fail7.json", "tests/fixtures/fail8.json", "tests/fixtures/fail9.json", "tests/fixtures/pass1.json", "tests/fixtures/pass15.json", "tests/fixtures/pass16.json", "tests/fixtures/pass17.json", "tests/fixtures/pass2.json", "tests/fixtures/pass26.json", "tests/fixtures/pass3.json", "tests/setup_variant.rb", "tests/test_json.rb", "tests/test_json_addition.rb", "tests/test_json_encoding.rb", "tests/test_json_fixtures.rb", "tests/test_json_generate.rb", "tests/test_json_generic_object.rb", "tests/test_json_string_matching.rb", "tests/test_json_unicode.rb", "tools/fuzz.rb", "tools/server.rb"] s.homepage = "http://flori.github.com/json" s.licenses = ["Ruby"] - s.rdoc_options = ["--title", "JSON implemention for ruby", "--main", "README.rdoc"] - s.rubygems_version = "2.4.8" + s.rdoc_options = ["--title", "JSON implemention for ruby", "--main", "README.md"] + s.rubygems_version = "2.5.0" s.summary = "JSON Implementation for Ruby" s.test_files = ["./tests/test_json.rb", "./tests/test_json_addition.rb", "./tests/test_json_encoding.rb", "./tests/test_json_fixtures.rb", "./tests/test_json_generate.rb", "./tests/test_json_generic_object.rb", "./tests/test_json_string_matching.rb", "./tests/test_json_unicode.rb"] |