ruby_json_parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 642bf9c4ccd18cfadf48b5ebfa77838c2b27f85e22f3ad87b800709b94697344
+  data.tar.gz: e56908db728c244bd31105f6feb8093d5f5f2b04f56d4d0d04d43c140fdc5077
+SHA512:
+  metadata.gz: 3488592ef9a18ab9e2dbc155c7e9f7c00fab7e523b41de5b9a0624c9462285a0d1b5239f2fc38b7d1723e2945ec4735731ffc52dae554d5146dcc09f54b76e56
+  data.tar.gz: 39da06576d98f82b3d4f023b10e815c4f2f79684b13264414ba62f762d184327dcc0eca7327e8523fa379a957dc275c22b1186ad87134955e4e3b9ce8a31e41c

data/.rubocop.yml

@@ -0,0 +1,35 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+inherit_gem:
+  rubocop-espago: rubocop.yml
+
+Lint/BooleanSymbol:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Style/YodaExpression:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Style/RaiseArgs:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-11-26
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mateusz Drewniak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,143 @@
+# RubyJsonParser
+
+This library implements a JSON lexer, parser and evaluator in pure Ruby 💎.
+
+It has been built for educational purposes, to serve as a simple example of what makes parsers tick.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add ruby_json_parser
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install ruby_json_parser
+
+## Usage
+
+### Lexer
+
+This library implements a streaming JSON lexer.
+You can use it by creating an instance of `RubyJsonParser::Lexer` passing in a string
+with JSON source.
+
+You can call the `next` method to receive the next token.
+Once the lexing is complete a token of type `:end_of_file` gets returned.
+
+```rb
+require 'ruby_json_parser'
+
+lexer = RubyJsonParser::Lexer.new('{ "some": ["json", 2e-29, "text"] }')
+lexer.next #=> Token(:lbrace)
+lexer.next #=> Token(:string, "some")
+lexer.next #=> Token(:colon)
+lexer.next #=> Token(:lbracket)
+lexer.next #=> Token(:string, "json")
+# ...
+lexer.next #=> Token(:end_of_file)
+```
+
+There is a simplified API that lets you generate an array of all tokens.
+
+```rb
+require 'ruby_json_parser'
+
+RubyJsonParser.lex('{ "some": ["json", 2e-29, "text"] }')
+#=> [Token(:lbrace), Token(:string, "some"), Token(:colon), Token(:lbracket), Token(:string, "json"), Token(:comma), Token(:number, "2e-29"), Token(:comma), Token(:string, "text"), Token(:rbracket), Token(:rbrace)]
+```
+
+### Parser
+
+This library implements a JSON parser.
+You can use it by calling `RubyJsonParser.parse` passing in a string
+with JSON source.
+
+It returns `RubyJsonParser::Result` which contains the produced AST (Abstract Syntax Tree) and the list of encountered errors.
+
+```rb
+require 'ruby_json_parser'
+
+RubyJsonParser.parse('{ "some": ["json", 2e-29, "text"] }')
+#=> <RubyJsonParser::Result>
+#  AST:
+#    (object
+#      (pair
+#        "some"
+#        (array
+#          "json"
+#          2e-29
+#          "text")))
+
+result = RubyJsonParser.parse('[1, 2')
+#=> <RubyJsonParser::Result>
+#  !Errors!
+#    - unexpected `END_OF_FILE`, expected `]`
+#
+#  AST:
+#    (array
+#      1
+#      2)
+
+result.ast # get the AST
+result.err? # check if there are any errors
+result.errors # get the list of errors
+```
+
+All AST nodes are implemented as classes under the `RubyJsonParser::AST` module.
+AST nodes have an `inspect` method that presents their structure in the [S-expression](https://en.wikipedia.org/wiki/S-expression) format.
+You can also use `#to_s` to convert them to a JSON-like human readable format.
+
+```rb
+result = RubyJsonParser.parse('{"some"   :[   "json",2e-29 ,  "text"  ]}')
+ast = result.ast
+
+puts ast.inspect # S-expression format
+# (object
+#   (pair
+#     "some"
+#     (array
+#       "json"
+#       2e-29
+#       "text")))
+
+puts ast.to_s # JSON-like format
+# {"some": ["json", 2e-29, "text"]}
+
+ast.class #=> RubyJsonParser::AST::ObjectLiteralNode
+
+ast.pairs[0].key #=> RubyJsonParser::AST::StringLiteralNode("some")
+ast.pairs[0].value.elements[2] #=> RubyJsonParser::AST::NumberLiteralNode("2e-29")
+```
+
+### Evaluator
+
+This library implements a JSON evaluator.
+It interprets a JSON source string as builtin Ruby data structures.
+
+You can use it by calling `RubyJsonParser.eval` passing in a string
+with JSON source.
+
+It throws `RubyJsonParser::SyntaxError` when the string cannot be parsed.
+
+```rb
+RubyJsonParser.eval('{ "some": ["json", 2e-29, "text"] }')
+#=> {"some"=>["json", 2.0e-29, "text"]}
+
+RubyJsonParser.eval('{ "some" }')
+#! RubyJsonParser::SyntaxError: missing key in object literal for value: `"some"`
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Verseth/ruby_json_parser.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/ruby_json_parser/ast.rb

@@ -0,0 +1,312 @@
+# typed: strong
+# frozen_string_literal: true
+
+class RubyJsonParser
+  # Contains the definitions of all AST (Abstract Syntax Tree) nodes.
+  # AST is the data structure that is returned by the parser.
+  module AST
+    # A string that represents a single level of indentation
+    # in S-expressions
+    INDENT_UNIT = '  '
+
+    # Abstract class representing an AST node.
+    class Node
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+
+      # Get the JSON-like representation of the AST
+      sig { abstract.returns(String) }
+      def to_s; end
+
+      # Inspect the AST in the S-expression format
+      sig { abstract.params(indent: Integer).returns(String) }
+      def inspect(indent = 0); end
+    end
+
+    # Represents an invalid node
+    class InvalidNode < Node
+      sig { returns(Token) }
+      attr_reader :token
+
+      sig { params(token: Token).void }
+      def initialize(token)
+        @token = token
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.is_a?(InvalidNode)
+
+        token == other.token
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        "<invalid: `#{token}`>"
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        "#{INDENT_UNIT * indent}(invalid `#{token}`)"
+      end
+    end
+
+    # Represents a false literal eg. `false`
+    class FalseLiteralNode < Node
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        other.is_a?(FalseLiteralNode)
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        'false'
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        "#{INDENT_UNIT * indent}false"
+      end
+    end
+
+    # Represents a true literal eg. `true`
+    class TrueLiteralNode < Node
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        other.is_a?(TrueLiteralNode)
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        'true'
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        "#{INDENT_UNIT * indent}true"
+      end
+    end
+
+    # Represents a true literal eg. `null`
+    class NullLiteralNode < Node
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        other.is_a?(NullLiteralNode)
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        'null'
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        "#{INDENT_UNIT * indent}null"
+      end
+    end
+
+    # Represents a number literal eg. `123.5`
+    class NumberLiteralNode < Node
+      sig { returns(String) }
+      attr_reader :value
+
+      sig { params(value: String).void }
+      def initialize(value)
+        @value = value
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.is_a?(NumberLiteralNode)
+
+        value == other.value
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        value
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        "#{INDENT_UNIT * indent}#{value}"
+      end
+    end
+
+    # Represents a string literal eg. `"foo"`
+    class StringLiteralNode < Node
+      sig { returns(String) }
+      attr_reader :value
+
+      sig { params(value: String).void }
+      def initialize(value)
+        @value = value
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.is_a?(StringLiteralNode)
+
+        value == other.value
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        value.inspect
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        "#{INDENT_UNIT * indent}#{value.inspect}"
+      end
+    end
+
+    # Represents an object literal eg. `{ "foo": 123 }`
+    class ObjectLiteralNode < Node
+      sig { returns(T::Array[KeyValuePairNode]) }
+      attr_reader :pairs
+
+      sig { params(pairs: T::Array[KeyValuePairNode]).void }
+      def initialize(pairs)
+        @pairs = pairs
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.is_a?(ObjectLiteralNode)
+
+        pairs == other.pairs
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        buff = String.new
+        buff << '{'
+
+        @pairs.each.with_index do |pair, i|
+          buff << ', ' if i > 0
+          buff << pair.to_s
+        end
+
+        buff << '}'
+        buff
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        buff = String.new
+
+        buff << "#{INDENT_UNIT * indent}(object"
+        @pairs.each do |pair|
+          buff << "\n"
+          buff << pair.inspect(indent + 1)
+        end
+        buff << ')'
+        buff
+      end
+    end
+
+    # Represents a key-value pair eg. `"foo": 123`
+    class KeyValuePairNode < Node
+      sig { returns(T.nilable(Node)) }
+      attr_reader :key
+
+      sig { returns(T.nilable(Node)) }
+      attr_reader :value
+
+      sig { params(key: T.nilable(Node), value: T.nilable(Node)).void }
+      def initialize(key, value)
+        @key = key
+        @value = value
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.is_a?(KeyValuePairNode)
+
+        key == other.key && value == other.value
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        return value.to_s unless key
+
+        "#{key}: #{value}"
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        buff = String.new
+        buff << "#{INDENT_UNIT * indent}(pair"
+
+        k = key
+        buff << "\n"
+        buff <<
+          if k
+            k.inspect(indent + 1)
+          else
+            "#{INDENT_UNIT * (indent + 1)}<nil>"
+          end
+
+        v = value
+        buff << "\n"
+        buff <<
+          if v
+            v.inspect(indent + 1)
+          else
+            "#{INDENT_UNIT * (indent + 1)}<nil>"
+          end
+
+        buff << ')'
+        buff
+      end
+    end
+
+    # Represents an object literal eg. `[1, "foo"]`
+    class ArrayLiteralNode < Node
+      sig { returns(T::Array[Node]) }
+      attr_reader :elements
+
+      sig { params(elements: T::Array[Node]).void }
+      def initialize(elements)
+        @elements = elements
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.is_a?(ArrayLiteralNode)
+
+        elements == other.elements
+      end
+
+      sig { override.returns(String) }
+      def to_s
+        buff = String.new
+        buff << '['
+
+        @elements.each.with_index do |element, i|
+          buff << ', ' if i > 0
+          buff << element.to_s
+        end
+
+        buff << ']'
+        buff
+      end
+
+      sig { override.params(indent: Integer).returns(String) }
+      def inspect(indent = 0)
+        buff = String.new
+
+        buff << "#{INDENT_UNIT * indent}(array"
+        @elements.each do |element|
+          buff << "\n"
+          buff << element.inspect(indent + 1)
+        end
+        buff << ')'
+        buff
+      end
+    end
+  end
+end

data/lib/ruby_json_parser/evaluator.rb

@@ -0,0 +1,81 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'token'
+
+class RubyJsonParser
+  # An evaluator for JSON.
+  # Creates Ruby structures based on an JSON AST.
+  module Evaluator
+    # Eval error
+    class Error < StandardError; end
+
+    class << self
+      extend T::Sig
+
+      sig { params(source: String).returns(Object) }
+      def eval(source)
+        result = RubyJsonParser.parse(source)
+        raise SyntaxError.new(result.errors) if result.err?
+
+        eval_node(result.ast)
+      end
+
+      sig { params(node: AST::Node).returns(Object) }
+      def eval_node(node)
+        case node
+        when AST::NullLiteralNode
+          nil
+        when AST::FalseLiteralNode
+          false
+        when AST::TrueLiteralNode
+          true
+        when AST::StringLiteralNode
+          eval_string(node)
+        when AST::NumberLiteralNode
+          eval_number(node)
+        when AST::ArrayLiteralNode
+          eval_array(node)
+        when AST::ObjectLiteralNode
+          eval_object(node)
+        else
+          raise Error, "invalid AST node: #{node.class}"
+        end
+      end
+
+      private
+
+      sig { params(node: AST::StringLiteralNode).returns(String) }
+      def eval_string(node)
+        node.value
+      end
+
+      sig { params(node: AST::NumberLiteralNode).returns(T.any(Integer, Float)) }
+      def eval_number(node)
+        Integer(node.value)
+      rescue ArgumentError
+        node.value.to_f
+      end
+
+      sig { params(node: AST::ArrayLiteralNode).returns(T::Array[Object]) }
+      def eval_array(node)
+        node.elements.map do |element|
+          eval_node(element)
+        end
+      end
+
+      sig { params(node: AST::ObjectLiteralNode).returns(T::Hash[String, Object]) }
+      def eval_object(node)
+        result = {}
+        node.pairs.each do |pair|
+          key = T.cast(pair.key, AST::StringLiteralNode)
+          val = T.must pair.value
+          result[eval_string(key)] = eval_node(val)
+        end
+
+        result
+      end
+    end
+
+  end
+end