jaina 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48fe47bcb5284c5750a92c39457d8554d18c4b4a68751495b2b4e980d0f6ab79
-  data.tar.gz: '08f0fca3c2d988a9468da5f8abad49c78915dd7192f189b28deb372a017fbaa7'
+  metadata.gz: 5b071350b636b4d475d51836639fa20c3b62f5518eddd4d0e71aa70cf9a9a1f9
+  data.tar.gz: eec63665a26dc9de484fd162795332e79762e2b4da24a637753468b06c5cfd8b
 SHA512:
-  metadata.gz: e0754eca5ffe832e586de80a9f50ba8dcd09feb4264be5da05da551ec5cd89a1bc79ccdec9c8920fcf927cbee32cb3ba64382fd8230fce5101a75e6abbd0f8e9
-  data.tar.gz: 55c67e22dcc1c857e61215843be9335538a993b477e2f4d6c2ee089a8ee11335865aaaaebadeb211f3aa9cc81eabde766d117f46034ffb55b16deb29e95e228d
+  metadata.gz: 56422133b95ab2bbfdcb720aea41a320d0c147e26ffca1de3fcf1a7cc013af2bb2cc9462634eee9dc4f1296584a6488b9fc63555aafc6bd37814e01d000c6f35
+  data.tar.gz: e5127b38022694809fd58644d86b9434bd4e368d1467b2a13d36ebe22103b5117a29bc2aaa11b6298dae0109f1ae6dea9f0d11983db52e45c3f1b447000ee54b

data/.gitignore

@@ -11,3 +11,4 @@ Gemfile.lock
 .ruby-version
 /.idea
 /.vscode
+*.gem

data/.travis.yml

@@ -0,0 +1,19 @@
+language: ruby
+matrix:
+  fast_finish: true
+  include:
+  - rvm: 2.3
+  - rvm: 2.4
+  - rvm: 2.5
+  - rvm: 2.6
+  - rvm: ruby-head
+  - rvm: jruby-head
+  allow_failures:
+  - rvm: ruby-head
+  - rvm: jruby-head
+sudo: false
+cache: bundler
+before_install: gem install bundler
+script:
+- bundke exec rubocop
+- bundle exec rspec

data/README.md

@@ -1 +1,160 @@
-# Jaina
+# Jaina  · [![Gem Version](https://badge.fury.io/rb/jaina.svg)](https://badge.fury.io/rb/jaina) [![Build Status](https://travis-ci.org/0exp/jaina.svg?branch=master)](https://travis-ci.org/0exp/jaina) [![Coverage Status](https://coveralls.io/repos/github/0exp/jaina/badge.svg?branch=master)](https://coveralls.io/github/0exp/jaina?branch=master)
+
+Simple programming language builder inspired by interpreter pattern.
+
+## Installation
+
+```ruby
+gem 'jaina'
+```
+
+```shell
+$ bundle install
+# --- or ---
+$ gem install 'jaina'
+```
+
+```ruby
+require 'jaina'
+```
+
+## Usage
+
+- [Registered operators](#registered-operators)
+- [Register your own operator](#register-your-own-operator)
+- [Register your own operand](#register-your-own-operand)
+- [Context API](#context-api)
+- [Parse your code (build AST)](#parse-your-code-build-ast)
+- [Evaluate your code](#evaluate-your-code)
+- [List registered operands and operators](#list-and-fetch-registered-operands-and-operators)
+
+---
+
+### Registered operators
+
+- `AND`
+- `OR`
+- `NOT`
+- `(`, `)` (grouping operators)
+
+---
+
+### Register your own operator
+
+```ruby
+# step 1: define new operator
+class But < Jaina::NonTerminalExpr
+  token 'BUT' # use it in your program :)
+  associativity_direction :left # associativity (left or right)
+  acts_as_binary_term # binar or unary
+  precedence_level 4 # for example: AND > OR, NOT > AND, and etc...
+end
+
+# step 2: regsiter your operator
+Jaina.register_expression(But)
+```
+
+---
+
+### Register your own operand
+
+```ruby
+# step 1: define new operand
+class A < Jaina::TerminalExpr
+  token 'A'
+
+  # NOTE: context is a custom data holder that passed from expression to expression
+  def evaluate(context)
+    # your custom evaluation code
+  end
+end
+
+# step 2: regsiter your operand
+Jaina.register_expression(A)
+```
+
+---
+
+### Context API
+
+```ruby
+class A < Jaina::TerminalExpr
+  # ... some code
+
+  def evaluate(context)
+    ... your code ...
+    # ... context ???
+    ... your code ...
+  end
+end
+
+# NOTE: context api
+
+context.keys # => []
+context.set(:a, 1) # => 1
+context.get(:a) # => 1
+context.keys # => [:a]
+context.get(:b) # => Jaina::Parser::AST::Contex::UndefinedContextKeyError
+```
+
+---
+
+### Parse your code (build AST)
+
+```ruby
+Jaina.parse('A AND B AND (C OR D) OR A AND (C OR E)')
+# => #<Jaina::Parser::AST:0x00007fd6f424a2e8>
+```
+
+---
+
+### Evaluate your code
+
+```ruby
+ast = Jaina.parse('A AND B AND (C OR D) OR A AND (C OR E)')
+ast.evaluate
+
+# --- or ---
+Jaina.evaluate('A AND B AND (C OR D) OR A AND (C OR E)')
+```
+
+---
+
+### List and fetch registered operands and operators
+
+```ruby
+A = Class.new(Jaina::TerminalExpr) { token 'A' }
+B = Class.new(Jaina::TerminalExpr) { token 'B' }
+C = Class.new(Jaina::TerminalExpr) { token 'C' }
+
+Jaina.register_expression(A)
+Jaina.register_expression(B)
+Jaina.register_expression(C)
+
+Jaina.expressions
+# => ["AND", "OR", "NOT", "(", ")", "A", "B", "C"]
+
+Jaina.fetch_expression("AND") # => Jaina::Parser::Expression::Operator::And
+Jaina.fetch_expression("A") # => A
+
+Jaina.fetch_expression("KEK")
+# => raises Jaina::Parser::Expression::Registry::UnregisteredExpressionError
+```
+
+---
+
+## Contributing
+
+- Fork it ( https://github.com/0exp/jaina/fork )
+- Create your feature branch (`git checkout -b feature/my-new-feature`)
+- Commit your changes (`git commit -am 'Add some feature'`)
+- Push to the branch (`git push origin feature/my-new-feature`)
+- Create new Pull Request
+
+## License
+
+Released under MIT License.
+
+## Authors
+
+[Rustam Ibragimov](https://github.com/0exp)

data/jaina.gemspec

@@ -13,7 +13,8 @@ Gem::Specification.new do |spec|
 
   spec.homepage    = 'https://github.com/0exp/jaina'
   spec.summary     = 'Simple programming language builder inspired by interpreter pattern.'
-  spec.description = 'Simple programming language builder inspired by interpreter pattern.'
+  spec.description = 'Simple programming language builder inspired by interpreter pattern. ' \
+                     'You can build your own langs for any project purposes.'
 
   spec.bindir        = 'bin'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

data/lib/jaina/parser/ast/context.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 0.1.0
+class Jaina::Parser::AST::Context
+  # @since 0.1.0
+  Error = Class.new(StandardError)
+  # @since 0.1.0
+  UndefinedContextKeyError = Class.new(Error)
+
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def initialize
+    @data = {}
+    @access_lock = Mutex.new
+  end
+
+  # @param key [Any]
+  # @param value [Any]
+  # @return [Any]
+  #
+  # @api public
+  # @since 0.1.0
+  def set(key, value)
+    thread_safe { apply(key, value) }
+  end
+
+  # @param key [Any]
+  # @return [Any]
+  #
+  # @api public
+  # @since 0.1.0
+  def get(key)
+    thread_safe { get(key) }
+  end
+
+  # @return [Array<Any>]
+  #
+  # @api public
+  # @since 0.1.0
+  def keys
+    thread_safe { registered_data }
+  end
+
+  private
+
+  # @return [Hash<Any,Any>]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :data
+
+  # @return [Mutex]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :access_lock
+
+  # @param block [Proc]
+  # @return [Any]
+  #
+  # @api private
+  # @since 0.1.0
+  def thread_safe(&block)
+    access_lock.synchronize { yield }
+  end
+
+  # @param key [Any]
+  # @param value [Any]
+  # @return [Any]
+  #
+  # @api private
+  # @since 0.1.0
+  def apply(key, value)
+    value.tap { data[key] = value }
+  end
+
+  # @return [Array<Any>]
+  #
+  # @api private
+  # @since 0.1.0
+  def registered_data
+    data.keys
+  end
+
+  # @param key [String]
+  # @return [Any]
+  #
+  # @api private
+  # @since 0.1.0
+  def fetch(key)
+    data.fetch(key)
+  rescue KeyError
+    raise UndefinedContextKeyError, "Data with `#{key}` key does not exist"
+  end
+end

data/lib/jaina/parser/ast/evaluator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module Jaina::Parser::AST::Evaluator
+  class << self
+    # @param ast [Jaina::Parser::AST]
+    # @return [Any]
+    #
+    # @api private
+    # @since 0.1.0
+    def evaluate(ast)
+      context = Jaina::Parser::AST::Context.new
+      # TODO: traverse the abstract syntax tree
+    end
+  end
+end

data/lib/jaina/parser/ast/tree.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+class Jaina::Parser::AST::Tree
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :initial_program
+
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :ast_oriented_program
+
+  # @return [Jaina::Parser::Expression::Operator::Abstract]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :expression
+
+  # @param initial_program [String]
+  # @param expression [Jaina::Parser::Expression::Operator::Abstract]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def initialize(initial_program:, ast_oriented_program:, expression:)
+    @initial_program = initial_program
+    @ast_oriented_program = ast_oriented_program
+    @expression = expression
+  end
+end

data/lib/jaina/parser/ast/tree_builder.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+class Jaina::Parser::AST::TreeBuilder
+  # @since 0.1.0
+  extend Forwardable
+
+  class << self
+    # @param program [String]
+    # @return [Jaina::Parser::AST::Tree]
+    #
+    # @api private
+    # @since 0.1.0
+    def build(program)
+      new(program).build
+    end
+  end
+
+  # @since 0.1.0
+  def_delegators Jaina::Parser::Expression,
+                 :terminal?,
+                 :non_terminal?,
+                 :acts_as_unary_term?,
+                 :acts_as_binary_term?
+
+  # @param progrm [String]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def initialize(program)
+    @program = program.dup.tap(&:freeze)
+    @prefix_form = Jaina::Parser::CodeConverter.to_prefix_form(@program)
+    @tokens = Jaina::Parser::Tokenizer.tokenize(@prefix_form)
+  end
+
+  # @return [Jaina::Parser::AST:Tree]
+  #
+  # @api private
+  # @since 0.1.0
+  def build
+    token_series = tokens.map(&:dup)
+    expression_tree = build_expression_tree(token_series)
+
+    Jaina::Parser::AST::Tree.new(
+      initial_program: program,
+      ast_oriented_program: prefix_form,
+      expression: expression_tree
+    )
+  end
+
+  private
+
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :program
+
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :prefix_form
+
+  # @return [Array<String>]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :tokens
+
+  # @param token_series [Array<String>]
+  # @return [Array<Jaina::Parser::Expression::Operator::Abstract>]
+  #
+  # @api private
+  # @since 0.1.0
+  def build_expression_tree(token_series)
+    current_token = extract_second_token(token_series)
+    return if current_token.nil?
+
+    case
+    when terminal?(current_token)
+      build_terminal_expression(current_token)
+    when non_terminal?(current_token)
+      build_non_terminal_expression(current_token, token_series)
+    end
+  end
+
+  # @param token_series [Array<String>]
+  # @return [String, NilClass]
+  #
+  # @api private
+  # @since 0.1.0
+  def extract_second_token(token_series)
+    token_series.shift
+  end
+
+  # @param current_token [String]
+  # @return [Jaina::Parser::Expression::Operator::Abstract]
+  #
+  # @api private
+  # @since 0.1.0
+  def build_terminal_expression(current_token)
+    Jaina::Parser::Expression.build(current_token)
+  end
+
+  # @param current_token [String]
+  # @param token_series [Array<String>]
+  # @return [Jaina::Parser::Expression::Operator::Abstract]
+  #
+  # @api private
+  # @since 0.1.0
+  def build_non_terminal_expression(current_token, token_series)
+    case
+    when acts_as_unary_term?(current_token)
+      Jaina::Parser::Expression.build(
+        current_token,
+        build_expression_tree(token_series)
+      )
+    when acts_as_binary_term?(current_token)
+      Jaina::Parser::Expression.build(
+        current_token,
+        build_expression_tree(token_series),
+        build_expression_tree(token_series)
+      )
+    end
+  end
+end

data/lib/jaina/parser/ast.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+class Jaina::Parser::AST
+  require_relative './ast/tree'
+  require_relative './ast/tree_builder'
+  require_relative './ast/evaluator'
+  require_relative './ast/context'
+
+  class << self
+    # @param program [String] Program string in prefix form
+    # @return [Jaina::Parser::AST]
+    #
+    # @api private
+    # @since 0.1.0
+    def build(program)
+      ast_tree = Jaina::Parser::AST::TreeBuilder.build(program)
+      new(program, ast_tree)
+    end
+
+    # @param program [String] Program string in prefix form
+    # @return [Any]
+    #
+    # @api private
+    # @since 0.1.0
+    def evaluate(program)
+      build(program).evaluate
+    end
+  end
+
+  # @return [Jaina::Pasrer::AST::Tree]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :ast_tree
+
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :program
+
+  # @param program [String]
+  # @param ast_tree [Jaina::Parser::AST::Tree]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.1.0
+  def initialize(program, ast_tree)
+    @program  = program.dup.tap(&:freeze)
+    @ast_tree = ast_tree
+  end
+
+  # @return [Any]
+  #
+  # @api private
+  # @since 0.1.0
+  def evaluate
+    Jaina::Parser::AST::Evaluator.evaluate(self)
+  end
+end