RFC8259 8259

data/lib/RFC8259/false.rb

@@ -0,0 +1,79 @@
+#! /your/favourite/path/to/ruby
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2014 Urabe, Shyouhei.  All rights reserved.
+#
+# Redistribution  and  use  in  source   and  binary  forms,  with  or  without
+# modification, are  permitted provided that the following  conditions are met:
+#
+#     - Redistributions  of source  code must  retain the  above copyright
+#       notice, this list of conditions and the following disclaimer.
+#
+#     - Redistributions in binary form  must reproduce the above copyright
+#       notice, this  list of conditions  and the following  disclaimer in
+#       the  documentation  and/or   other  materials  provided  with  the
+#       distribution.
+#
+#     - Neither the name of Internet  Society, IETF or IETF Trust, nor the
+#       names of specific contributors, may  be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+# AND ANY  EXPRESS OR  IMPLIED WARRANTIES, INCLUDING,  BUT NOT LIMITED  TO, THE
+# IMPLIED WARRANTIES  OF MERCHANTABILITY AND  FITNESS FOR A  PARTICULAR PURPOSE
+# ARE  DISCLAIMED. IN NO  EVENT SHALL  THE COPYRIGHT  OWNER OR  CONTRIBUTORS BE
+# LIABLE  FOR   ANY  DIRECT,  INDIRECT,  INCIDENTAL,   SPECIAL,  EXEMPLARY,  OR
+# CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT   NOT  LIMITED  TO,  PROCUREMENT  OF
+# SUBSTITUTE  GOODS OR SERVICES;  LOSS OF  USE, DATA,  OR PROFITS;  OR BUSINESS
+# INTERRUPTION)  HOWEVER CAUSED  AND ON  ANY  THEORY OF  LIABILITY, WHETHER  IN
+# CONTRACT,  STRICT  LIABILITY, OR  TORT  (INCLUDING  NEGLIGENCE OR  OTHERWISE)
+# ARISING IN ANY  WAY OUT OF THE USE  OF THIS SOFTWARE, EVEN IF  ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+# The false, as defined in RFC8259 section 3.
+class RFC8259::False < RFC8259::Value
+
+	# Parse the AST from parser, and convert into corrsponding value.
+	# @param  [::Array] ast    the AST, generated by the parser
+	# @return [False]          evaluated instance
+	# @raise  [ArgumentError]  malformed input
+	def self.from_ast ast
+		raise ArgumentError "garbage included: #{ast.inspect}" if ast.length > 1
+		raise ArgumentError "not a false: #{ast.inspect}" if ast[0] != :false
+		return new
+	end
+
+	# convert to Ruby's false
+	# @return [false] the ruby counter part.
+	def plain_old_ruby_object
+		return false
+	end
+
+	# JSON gem compat
+	# @return [::String] JSONified string representation
+	def to_json
+		return 'false'
+	end
+
+	# Equality.  All  false instances  are equal each  other, plus  a FalseClass
+	# instance is also equal to this.
+	def == other
+		case other when FalseClass, self.class
+			true
+		else
+			false
+		end
+	end
+end
+
+# 
+# Local Variables:
+# mode: ruby
+# coding: utf-8-unix
+# indent-tabs-mode: t
+# tab-width: 3
+# ruby-indent-level: 3
+# fill-column: 79
+# default-justification: full
+# End:

data/lib/RFC8259/null.rb

@@ -0,0 +1,79 @@
+#! /your/favourite/path/to/ruby
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2014 Urabe, Shyouhei.  All rights reserved.
+#
+# Redistribution  and  use  in  source   and  binary  forms,  with  or  without
+# modification, are  permitted provided that the following  conditions are met:
+#
+#     - Redistributions  of source  code must  retain the  above copyright
+#       notice, this list of conditions and the following disclaimer.
+#
+#     - Redistributions in binary form  must reproduce the above copyright
+#       notice, this  list of conditions  and the following  disclaimer in
+#       the  documentation  and/or   other  materials  provided  with  the
+#       distribution.
+#
+#     - Neither the name of Internet  Society, IETF or IETF Trust, nor the
+#       names of specific contributors, may  be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+# AND ANY  EXPRESS OR  IMPLIED WARRANTIES, INCLUDING,  BUT NOT LIMITED  TO, THE
+# IMPLIED WARRANTIES  OF MERCHANTABILITY AND  FITNESS FOR A  PARTICULAR PURPOSE
+# ARE  DISCLAIMED. IN NO  EVENT SHALL  THE COPYRIGHT  OWNER OR  CONTRIBUTORS BE
+# LIABLE  FOR   ANY  DIRECT,  INDIRECT,  INCIDENTAL,   SPECIAL,  EXEMPLARY,  OR
+# CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT   NOT  LIMITED  TO,  PROCUREMENT  OF
+# SUBSTITUTE  GOODS OR SERVICES;  LOSS OF  USE, DATA,  OR PROFITS;  OR BUSINESS
+# INTERRUPTION)  HOWEVER CAUSED  AND ON  ANY  THEORY OF  LIABILITY, WHETHER  IN
+# CONTRACT,  STRICT  LIABILITY, OR  TORT  (INCLUDING  NEGLIGENCE OR  OTHERWISE)
+# ARISING IN ANY  WAY OUT OF THE USE  OF THIS SOFTWARE, EVEN IF  ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+# The null, as defined in RFC8259 section 3.
+class RFC8259::Null < RFC8259::Value
+
+	# Parse the AST from parser, and convert into corrsponding value.
+	# @param  [::Array] ast    the AST, generated by the parser
+	# @return [Null]           evaluated instance
+	# @raise  [ArgumentError]  malformed input
+	def self.from_ast ast
+		raise ArgumentError "garbage included: #{ast.inspect}" if ast.length > 1
+		raise ArgumentError "not a false: #{ast.inspect}" if ast[0] != :null
+		return new
+	end
+
+	# convert to Ruby's nil
+	# @return [nil] the ruby counter part.
+	def plain_old_ruby_object
+		return nil
+	end
+
+	# JSON gem compat
+	# @return [::String] JSONified string representation
+	def to_json
+		return 'null'
+	end
+
+	# Equality.   All null  instances  are  equal each  other,  plus a  NilClass
+	# instance is also equal to this.
+	def == other
+		case other when NilClass, self.class
+			true
+		else
+			false
+		end
+	end
+end
+
+# 
+# Local Variables:
+# mode: ruby
+# coding: utf-8-unix
+# indent-tabs-mode: t
+# tab-width: 3
+# ruby-indent-level: 3
+# fill-column: 79
+# default-justification: full
+# End:

data/lib/RFC8259/number.rb

@@ -0,0 +1,149 @@
+#! /your/favourite/path/to/ruby
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2014 Urabe, Shyouhei.  All rights reserved.
+#
+# Redistribution  and  use  in  source   and  binary  forms,  with  or  without
+# modification, are  permitted provided that the following  conditions are met:
+#
+#     - Redistributions  of source  code must  retain the  above copyright
+#       notice, this list of conditions and the following disclaimer.
+#
+#     - Redistributions in binary form  must reproduce the above copyright
+#       notice, this  list of conditions  and the following  disclaimer in
+#       the  documentation  and/or   other  materials  provided  with  the
+#       distribution.
+#
+#     - Neither the name of Internet  Society, IETF or IETF Trust, nor the
+#       names of specific contributors, may  be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+# AND ANY  EXPRESS OR  IMPLIED WARRANTIES, INCLUDING,  BUT NOT LIMITED  TO, THE
+# IMPLIED WARRANTIES  OF MERCHANTABILITY AND  FITNESS FOR A  PARTICULAR PURPOSE
+# ARE  DISCLAIMED. IN NO  EVENT SHALL  THE COPYRIGHT  OWNER OR  CONTRIBUTORS BE
+# LIABLE  FOR   ANY  DIRECT,  INDIRECT,  INCIDENTAL,   SPECIAL,  EXEMPLARY,  OR
+# CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT   NOT  LIMITED  TO,  PROCUREMENT  OF
+# SUBSTITUTE  GOODS OR SERVICES;  LOSS OF  USE, DATA,  OR PROFITS;  OR BUSINESS
+# INTERRUPTION)  HOWEVER CAUSED  AND ON  ANY  THEORY OF  LIABILITY, WHETHER  IN
+# CONTRACT,  STRICT  LIABILITY, OR  TORT  (INCLUDING  NEGLIGENCE OR  OTHERWISE)
+# ARISING IN ANY  WAY OUT OF THE USE  OF THIS SOFTWARE, EVEN IF  ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'bigdecimal'
+
+# The Numbers, as described in RFC8259 section 6.
+class RFC8259::Number < RFC8259::Value
+
+	# Notie  about technical  design: this  class  _could_ have  been made  much
+	# faster if we implement the whole  type-conversion thing by hand.  But that
+	# is very  bug-prone.  So to  avoid unnecessary  complexity here we  took an
+	# approach to  first let  everything be BigDecimal,  then convert  to others
+	# like Float.
+
+	# Parse the AST from parser, and convert into corrsponding values.
+	# @param  [::Array] ast    the AST, generated by the parser
+	# @return [Number]         evaluated instance
+	# @raise  [ArgumentError]  malformed input
+	def self.from_ast ast
+		type, sign, int, frac, exp = *ast
+		raise ArgumentError, "not an object: #{ast.inspect}" if type != :number
+		raise ArgumentError, "not a number: #{ast.inspect}" if int.nil?
+		new sign, int, frac, exp
+	end
+
+	# @return [Numeric] converted numeric
+	# @note  this conversion  might  lose  precision.  Use  `to_d`  if you  want
+	#   something that fully represents this number.
+	def plain_old_ruby_object
+		if /\A[+-]?\d+\z/ =~ @to_s
+			return to_i
+		else
+			return to_f
+		end
+	end
+
+	# @return [BigDecimal] lossless conversion to numeric
+	def to_d
+		return @to_d
+	end
+
+	# @return [::String] the original string
+	def to_s
+		return @to_s.dup # dup just in case.
+	end
+
+	# JSON gem compat
+	# @return [::String] the original string
+	def to_json *;
+		return to_s
+	end
+
+	# @return [Float] conversion to float
+	def to_f
+		# This method must be ideoponent so the result is cached
+		unless @to_f
+			num = to_d.to_f
+			@to_f ||= num # ||= to avoid race
+		end
+		return @to_f
+	end
+
+	# @return [Integer] conversion to integer
+	def to_i
+		# This method must be ideoponent so the result is cached
+		unless @to_i
+			num = to_d.to_i
+			@to_i ||= num # ||= to avoid race
+		end
+		return @to_i
+	end
+
+	# @return [::String] the value in string
+	def inspect
+		sprintf "#<%p:%p>", self.class, plain_old_ruby_object
+	end
+
+	# For pretty print (require 'pp' beforehand)
+	# @param [PP] pp the pp
+	def pretty_print pp
+		pp.object_group self do
+			pp.text ':'
+			plain_old_ruby_object.pretty_print pp
+		end
+	end
+
+	# Number equality is _not_ defined in the RFC so we take liberty of defining
+	# that to be mathematical comparison
+	def == other
+		other == @to_d
+	end
+
+	private
+
+	private_class_method:new
+	# @private
+	def initialize sign, int, frac, exp
+		@sign = sign              # nil, '-', or '+'
+		@int  = int.join
+		@frac = frac && frac.join # nil, or '.dddd..'
+		@exp  = exp  && exp.join  # nil, or 'e+ddd..'
+
+		# pre-cache common computations
+		@to_s = [@sign, @int, @frac, @exp].join.encode(Encoding::US_ASCII) # this must be OK
+		@to_s.freeze # just in case
+		@to_d = BigDecimal.new @to_s
+	end
+end
+
+# 
+# Local Variables:
+# mode: ruby
+# coding: utf-8-unix
+# indent-tabs-mode: t
+# tab-width: 3
+# ruby-indent-level: 3
+# fill-column: 79
+# default-justification: full
+# End:

data/lib/RFC8259/object.rb

@@ -0,0 +1,137 @@
+#! /your/favourite/path/to/ruby
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2014 Urabe, Shyouhei.  All rights reserved.
+#
+# Redistribution  and  use  in  source   and  binary  forms,  with  or  without
+# modification, are  permitted provided that the following  conditions are met:
+#
+#     - Redistributions  of source  code must  retain the  above copyright
+#       notice, this list of conditions and the following disclaimer.
+#
+#     - Redistributions in binary form  must reproduce the above copyright
+#       notice, this  list of conditions  and the following  disclaimer in
+#       the  documentation  and/or   other  materials  provided  with  the
+#       distribution.
+#
+#     - Neither the name of Internet  Society, IETF or IETF Trust, nor the
+#       names of specific contributors, may  be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+# AND ANY  EXPRESS OR  IMPLIED WARRANTIES, INCLUDING,  BUT NOT LIMITED  TO, THE
+# IMPLIED WARRANTIES  OF MERCHANTABILITY AND  FITNESS FOR A  PARTICULAR PURPOSE
+# ARE  DISCLAIMED. IN NO  EVENT SHALL  THE COPYRIGHT  OWNER OR  CONTRIBUTORS BE
+# LIABLE  FOR   ANY  DIRECT,  INDIRECT,  INCIDENTAL,   SPECIAL,  EXEMPLARY,  OR
+# CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT   NOT  LIMITED  TO,  PROCUREMENT  OF
+# SUBSTITUTE  GOODS OR SERVICES;  LOSS OF  USE, DATA,  OR PROFITS;  OR BUSINESS
+# INTERRUPTION)  HOWEVER CAUSED  AND ON  ANY  THEORY OF  LIABILITY, WHETHER  IN
+# CONTRACT,  STRICT  LIABILITY, OR  TORT  (INCLUDING  NEGLIGENCE OR  OTHERWISE)
+# ARISING IN ANY  WAY OUT OF THE USE  OF THIS SOFTWARE, EVEN IF  ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+# The Objects, as described in RFC8259 section 4.
+class RFC8259::Object < RFC8259::Value
+
+	# Parse the AST from parser, and convert into corrsponding values.
+	# @param  [::Array] ast    the AST, generated by the parser
+	# @return [Object]         evaluated instance
+	# @raise  [ArgumentError]  malformed input
+	def self.from_ast ast
+		type, *assoc = *ast
+		raise ArgumentError, "not an object: #{ast.inspect}" if type != :object
+		assoc.map! do |a|
+			a.map! do |b|
+				RFC8259::Value.from_ast b
+			end
+		end
+		new assoc
+	end
+
+	# fetch the key.
+	# @note   RFC8259 allows identical key to appear multiple times in an object.
+	# @note   This is O(1)
+	# @param  [::String, String]  key  key to look at
+	# @return [ [Value] ]              corresponding value(s)
+	def [] key
+		ret = @assoc.select do |(k, _)| k == key end
+		ret.map! do |(_, v)| v end
+		return ret
+	end
+
+	# iterates over the pairs.
+	# @yield [key, value] the pair.
+	def each_pair &b
+		e = Enumerator.new do |y|
+			@assoc.each do |a|
+				y << a
+			end
+		end
+		return block_given? ? e.each(&b) : e
+	end
+
+	alias each each_pair
+
+	# @raise  [RuntimeError]  keys conflict
+	# @return [::Hash]        converted object
+	def plain_old_ruby_object
+		ret = Hash.new
+		@assoc.each do |(k, v)|
+			kk = k.plain_old_ruby_object
+			if ret.include? kk
+				raise RuntimeError, "key #{kk} conflict."
+			else
+				vv = v.plain_old_ruby_object
+				ret.store kk, vv
+			end
+		end
+		return ret
+	end
+
+	alias to_h    plain_old_ruby_object
+	alias to_hash plain_old_ruby_object
+
+	# @return [::String] the object in string
+	def inspect
+		hdr = sprintf "#<%p:%#016x {", self.class, self.object_id << 1
+		map = @assoc.map do |(k, v)|
+			sprintf '%p: %p', k.to_s, v
+		end.join ', '
+		hdr << map << '}>'
+	end
+
+	# For pretty print
+	# @param [PP] pp the pp
+	def pretty_print pp
+		hdr = sprintf '#<%p:%#016x', self.class, self.object_id << 1
+		pp.group 1, hdr, '>' do
+			pp.text ' '
+			RFC8259::Dumper.kandr pp, 1, @assoc.each, '{', '}' do |(i, j)|
+				i.pretty_print pp
+				pp.text ': '
+				j.pretty_print pp
+			end
+		end
+	end
+
+	private
+	private_class_method:new
+	# @private
+	def initialize assoc
+		@assoc = assoc
+		@assoc.each {|i| i.freeze }
+		@assoc.freeze
+	end
+end
+
+# 
+# Local Variables:
+# mode: ruby
+# coding: utf-8-unix
+# indent-tabs-mode: t
+# tab-width: 3
+# ruby-indent-level: 3
+# fill-column: 79
+# default-justification: full
+# End:

data/lib/RFC8259/parser.ry

@@ -0,0 +1,275 @@
+#! /your/favourite/path/to/racc
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2014 Urabe, Shyouhei.  All rights reserved.
+#
+# Redistribution  and  use  in  source   and  binary  forms,  with  or  without
+# modification, are  permitted provided that the following  conditions are met:
+#
+#     - Redistributions  of source  code must  retain the  above copyright
+#       notice, this list of conditions and the following disclaimer.
+#
+#     - Redistributions in binary form  must reproduce the above copyright
+#       notice, this  list of conditions  and the following  disclaimer in
+#       the  documentation  and/or   other  materials  provided  with  the
+#       distribution.
+#
+#     - Neither the name of Internet  Society, IETF or IETF Trust, nor the
+#       names of specific contributors, may  be used to endorse or promote
+#       products derived from this software without specific prior written
+#       permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+# AND ANY  EXPRESS OR  IMPLIED WARRANTIES, INCLUDING,  BUT NOT LIMITED  TO, THE
+# IMPLIED WARRANTIES  OF MERCHANTABILITY AND  FITNESS FOR A  PARTICULAR PURPOSE
+# ARE  DISCLAIMED. IN NO  EVENT SHALL  THE COPYRIGHT  OWNER OR  CONTRIBUTORS BE
+# LIABLE  FOR   ANY  DIRECT,  INDIRECT,  INCIDENTAL,   SPECIAL,  EXEMPLARY,  OR
+# CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT   NOT  LIMITED  TO,  PROCUREMENT  OF
+# SUBSTITUTE  GOODS OR SERVICES;  LOSS OF  USE, DATA,  OR PROFITS;  OR BUSINESS
+# INTERRUPTION)  HOWEVER CAUSED  AND ON  ANY  THEORY OF  LIABILITY, WHETHER  IN
+# CONTRACT,  STRICT  LIABILITY, OR  TORT  (INCLUDING  NEGLIGENCE OR  OTHERWISE)
+# ARISING IN ANY  WAY OUT OF THE USE  OF THIS SOFTWARE, EVEN IF  ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+# This is  almost one-to-one translation of  RFC8259 section 2 through  7, from
+# Augmented BNF  to Racc BNF.  Should  be the easiest to  verify implementation
+# against the spec.
+#
+# @note This  parser has several  shift/reduct conflicts.  They are  all around
+#   handling of white spaces (called "ws"), so can silently be ignored.  I also
+#   checked the parser internal and made sure they are OK.
+class RFC8259::Parser
+
+	options no_result_var
+	expect 28
+	rule
+
+	# Notes  about nonterminal's  names: in  order to  make manual  verification
+	# easy, all the nonterminals that appear in the RFC are named as such.  ABNF
+	# is  much  concise  than  plain  BNF,  so  here  we  added  several  helper
+	# nonterminals; they  are prefixed  with "__"  so you  can distinguish  if a
+	# nonterminal is RFC-origin or not.
+
+	# RFC8259 section 2
+
+	JSON_text       : ws value  ws                              { val[1] }
+	begin_array     : ws "\x5B" ws # [ left square bracket
+	begin_object    : ws "\x7B" ws # { left curly bracket
+	end_array       : ws "\x5D" ws # ] right square bracket
+	end_object      : ws "\x7D" ws # } right curly bracket
+	name_separator  : ws "\x3A" ws # : colon
+	value_separator : ws "\x2C" ws # , comma
+	ws              :              # <- this is the '*' in the ABNF
+	                | ws "\x20"    # Space
+	                | ws "\x09"    # Horizontal tab
+	                | ws "\x0A"    # Line feed or New line
+	                | ws "\x0D"    # Carriage return
+
+	# RFC8259 section 3
+
+	value           : false | null | true | object | array | number | string
+	false           : "\x66" "\x61" "\x6c" "\x73" "\x65"        { [ :false ] } # false
+	null            : "\x6e" "\x75" "\x6c" "\x6c"               { [ :null  ] } # null
+	true            : "\x74" "\x72" "\x75" "\x65"               { [ :true  ] } # true
+
+	# RFC8259 section 4
+
+	object          : begin_object             end_object       { [ :object ] }
+	                | begin_object __members__ end_object       { [ :object, *val[1] ] }
+	__members__     : member                                    { val }
+	                | __members__ value_separator member        { [ *val[0],  val[2] ] }
+	member          : string name_separator value               { [  val[0],  val[2] ] }
+
+	# RFC8259 section 5
+
+	array           : begin_array          end_array            { [ :array ] }
+	                | begin_array __list__ end_array            { [ :array, *val[1] ] }
+	__list__        : value                                     { val }
+	                | __list__ value_separator value            { [ *val[0], val[2] ] }
+
+	# RFC8259 section 6
+
+	number          : __minus_p__ int __frac_p__ __exp_p__      { [ :number, *val ] }
+	__minus_p__     : | minus
+	__frac_p__      : | frac
+	__exp_p__       : | exp
+	decimal_point   : "\x2E" # .
+	digit1_9        : "\x31" | "\x32" | "\x33" | "\x34" | "\x35"
+	                | "\x36" | "\x37" | "\x38" | "\x39"
+	e               : "\x65" | "\x45"    # e E
+	exp             : e __sign__ __digit_plus__                 { val }
+	frac            : decimal_point __digit_plus__              { val }
+	int             : zero                                      { val }
+	                | digit1_9                                  { val }
+	                | digit1_9 __digit_plus__                   { [ val[0], *val[1] ] }
+	minus           : "\x2D" # -
+	plus            : "\x2B" # +
+	zero            : "\x30" # 0
+	DIGIT           : zero  | digit1_9
+	__sign__        : | plus  | minus
+	__digit_plus__  : DIGIT                                     { val }
+	                | __digit_plus__ DIGIT                      { [ *val[0], val[1] ] }
+
+	# RFC8259 section 7
+
+	string          : quotation_mark           quotation_mark   { [ :string ] }
+	                | quotation_mark __chars__ quotation_mark   { [ :string, *val[1] ] }
+	__chars__       : char                                      { val }
+	                | __chars__ char                            { [ *val[0],  val[1] ] }
+	char            : unescaped | escape __ctrl__               { val.flatten }
+	__ctrl__        : "\x22" # "    quotation mark  U+0022
+	                | "\x5C" # \    reverse solidus U+005C
+	                | "\x2F" # /    solidus         U+002F
+	                | "\x62" # b    backspace       U+0008
+	                | "\x66" # f    form feed       U+000C
+	                | "\x6E" # n    line feed       U+000A
+	                | "\x72" # r    carriage return U+000D
+	                | "\x74" # t    tab             U+0009
+	                | "\x75" # uXXXX                U+XXXX
+	                         HEXDIG HEXDIG HEXDIG HEXDIG        { val }
+	escape          : "\x5C" # \
+	quotation_mark  : "\x22" # "
+	HEXDIG          : DIGIT
+	                | "\x61" | "\x62" | "\x63" | "\x64" | "\x65" | "\x66"
+	                | "\x41" | "\x42" | "\x43" | "\x44" | "\x45" | "\x46"
+
+	# "unescaped" is too much to list up here; use lexer instead.
+	# unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
+end
+
+---- inner
+
+	# @param [true, false] accept_bom  Whether to accept BOMs
+	# @param [true, false] yydebug     Whether to enable debug mode
+	def initialize accept_bom: false, yydebug: false
+		@accept_bom = accept_bom
+		@yydebug    = yydebug
+	end
+
+	# Parses str  and generates  AST.  The  str must consist  of _a_  valid JSON
+	# text, otherwise an exception shall raise.
+	#
+	# @param  [#each_char] str    IO or String or something to parse
+	# @return [::Array]           Parsed AST
+	# @raise  [Racc::ParseError]  The input is invalid
+	# @raise  [Encoding::CompatibilityError] The input is invalid
+	def parse str
+		@state      = :init
+		@enum       = str.enum_for:each_char
+		firstchar   = @enum.peek
+		@lineno     = 1
+		@column     = 1
+
+		case @enc = firstchar.encoding
+		when Encoding::UTF_8,
+		     Encoding::US_ASCII, # true subset of UTF-8
+		     Encoding::UTF8_MAC  # true subset of UTF-8
+			# RFC8259 sectoin 8.1 explicitly states  that the input string must be
+			# UTF-8  encoded.  That  point  is as  clear as  the  sky.  All  other
+			# encodings are NG.   However, what we call the ASCII  encoding is the
+			# true  subset of  UTF-8.  A  string of  ASCII must  also be  valid as
+			# UTF-8.  So we allow this.
+			#
+			# There are disucssions about parsing BOMs.  The original RFC4627 said
+			# nothing about  BOMs, however  its section  3 ("Encoding")  cannot be
+			# read  as  if  it  expected BOMs.   Current  RFC8259  _prohibits_  to
+			# generate JSON texts with BOMs but _allows_ to accept.
+			#
+			# This parser can control whether to accept BOMs.
+			if @accept_bom and firstchar == "\u{feff}".encode(@enc)
+				@enum.next # consume
+			end
+			return do_parse
+		else
+			raise Encoding::CompatibilityError, <<-"end".gsub(/[\n\s]+/, ' ')
+				``JSON text exchanged between systems that are not part of a closed
+				ecosystem MUST be encoded using	UTF-8'', said RFC8259 section 8.1.
+				The given string is NOT in the encoding (but #{@enc.inspect}).
+			end
+		end
+	end
+
+	private
+	def nl
+		@nl ||= Regexp.new('[\r\n]'.encode(@enc))
+	end
+
+	def sp
+		@nl ||= Regexp.new('\s'.encode(@enc))
+	end
+
+	def nm
+		@nl ||= Regexp.new('\d'.encode(@enc))
+	end
+
+	def next_token
+		chr = @enum.next
+		tok = chr.encode(Encoding::UTF_8) # dfault
+		newline, @newline = @newline, nl.match(chr)
+		if newline
+			@lineno += 1
+			@column = 1
+		else
+			@column += 1
+		end
+		case @state
+		when :string  then # recap: unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
+			case chr.ord
+			when 0x20..0x21     then    tok = :unescaped
+			when 0x22           then @state = :init      # "
+			when 0x23..0x5B     then    tok = :unescaped
+			when 0x5C           then @state = :escaped   # \
+			when 0x5D..0x10FFFF then    tok = :unescaped
+			else                     @state = :string    # NG unicode
+			end
+		when :init    then @state = (chr.ord == '"'.ord) ? :string : :init
+		when :escaped then @state = (chr.ord == 'u'.ord) ? :u1     : :string
+		when :u1      then @state = :u2
+		when :u2      then @state = :u3
+		when :u3      then @state = :u4
+		when :u4      then @state = :string
+		end
+		return tok, chr
+	rescue StopIteration
+		return false, @enum
+	end
+
+	def on_error id, val, stack
+		reason = case @state
+		when :string
+			'this character is not allowed in a string; escape it.'
+		when :u1, :u2, :u3, :u4
+			'\uXXXX must exactly be a four-letter hexadecimal sequence.'
+		else
+			case val
+			when "'"
+				'you must use " to quote strings'
+			when '}', ']', ','
+				'possible extra (dangling) comma?'
+			when ':'
+				'possible confusion of {} vs []?'
+			when sp
+				'possible space inside of a number?'
+			when nm
+				'possible lack of +/- in exponent?'
+			else
+				'unexpected character'
+			end
+		end
+		msg = sprintf 'Syntax error near line %d, char %d (%p) @ %p: %s',
+			@lineno, @column, val, @enum, reason
+		raise Racc::ParseError, msg
+	end
+
+---- footer
+
+# 
+# Local Variables:
+# mode: ruby
+# coding: utf-8-unix
+# indent-tabs-mode: t
+# tab-width: 3
+# ruby-indent-level: 3
+# fill-column: 79
+# default-justification: full
+# End: