grumlin 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f0edafd4d46b787eb3f8e0ec4032948bdb4de865e4de3199606fb470dc16ef3
-  data.tar.gz: f23ba59dfb18dabe70fc860c38ea4c1777214b4a37e04771b24210d90f449612
+  metadata.gz: b01ddca4a13e70f6ab86875cd635655ebec77e877f374b0df9c8021f61ae7753
+  data.tar.gz: c25ccd742c5c40ba797f92fe39176cf2605d485506e56a1a1e8852bbbc11ab0b
 SHA512:
-  metadata.gz: 4629a25995953c6617a45721d7082baee59b76425636f6a4536308220bae3e7cb72b571317102339b1888c0e430dbe73320c12f44518940f45c67db829a9a265
-  data.tar.gz: fae1a56f95150f82da47a886da5e4b4a7ab0f725f66e68af61f6456c9a2f1af2cefc580ebf793cba612f0ceeda0b782361476a38511019062cc1534ad98fdb3c
+  metadata.gz: '042067879c5ae297f5d3a06f2f0a7302cccb5dc0e362fcdb15820f74e8aec6b1d9f5cd085bcfdbfe3d2f671fe8cae24b8da38c03a89e4a645c42a31d60218005'
+  data.tar.gz: b740805e7ab51fc7d45aeb0a1cc11062778561439a51395de1cdf1bd771a8745768c17e4e0b2db4daf2382ba6008f898e469c3f474d4738775c72a99c47cdd75

data/Gemfile

@@ -14,5 +14,6 @@ gem "solargraph"
 gem "async-rspec"
 gem "factory_bot"
 gem "overcommit"
+gem "rake"
 gem "rspec"
 gem "simplecov"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    grumlin (0.11.0)
+    grumlin (0.12.0)
       async-pool (~> 0.3)
       async-websocket (~> 0.19)
       oj (~> 3.12)
@@ -83,6 +83,7 @@ GEM
       protocol-http1 (~> 0.2)
     racc (1.5.2)
     rainbow (3.0.0)
+    rake (13.0.3)
     regexp_parser (2.1.1)
     reverse_markdown (2.0.0)
       nokogiri
@@ -161,6 +162,7 @@ DEPENDENCIES
   grumlin!
   nokogiri
   overcommit
+  rake
   rspec
   rubocop
   rubocop-performance

data/README.md

@@ -1,10 +1,30 @@
 # Grumlin
 
-[Gremlin](https://tinkerpop.apache.org/gremlin.html) query language DSL for Ruby
+[![Ruby](https://github.com/zhulik/grumlin/actions/workflows/main.yml/badge.svg)](https://github.com/zhulik/grumlin/actions/workflows/main.yml)
+[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
+[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
 
-**In development. Nothing to write here yet. If you are really interested, check out the source code and the specs.**
+Grumlin is a [Gremlin](https://tinkerpop.apache.org/gremlin.html) graph traversal language DSL and client for Ruby. 
+Suitable for and tested with [gremlin-server](http://tinkerpop.apache.org/) and [AWS Neptune](https://aws.amazon.com/neptune/).
 
-## Installation
+**Important**: Grumlin and it's author are not affiliated with The Apache Software Foundation which develops gremlin
+and gremlin-server.
+
+**Important**: Grumlin is based on the [async stack](https://github.com/socketry/async) and utilizes 
+[async-websocket](https://github.com/socketry/async-websocket). Code using grumlin must be executed in an async
+event loop.
+
+**Warning:** Grumlin is in development, but ready for simple use cases
+
+## Table of contents
+- [Install](#install)
+- [Usage](#usage)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code Of Conduct](#code-of-conduct)
+
+## Install
 
 Add this line to your application's Gemfile:
 
@@ -22,17 +42,77 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Configuration
+```ruby
+Grumlin.configure do |config|
+  config.url = "ws://localhost:8182/gremlin"
+end
+```
+
+### Traversing graphs
+
+**Warning:** Not all steps and tools described in the standard are supported
+
+#### Sugar
+
+Grumlin provides an easy to use module called `Grumlin::Sugar`. Once included in your class it injects some useful
+constants and methods turning your class into an entrypoint for traversals.
+
+```ruby
+class MyRepository
+  include Grumlin::Sugar
+  
+  def nodes(property1:, property2:)
+    g.V()
+      .has(T.label, "node")
+      .has(:property1, property1)
+      .has(:property2, property2)
+      .order.by(:property3, Order.asc).limit(10)
+      .toList
+  end
+end
+```
+
+#### Testing
+
+Grumlin provides a couple of helpers to simplify testing code written with it.
+
+##### RSpec
+
+Make sure you have [async-rspec](https://github.com/socketry/async-rspec) installed.
+
+`spec_helper.rb` or `rails_helper.rb`:
+```ruby
+require 'async/rspec'
+require require "grumlin/test/rspec"
+...
+config.include_context(Async::RSpec::Reactor) # Runs async reactor
+config.include_context(Grumlin::Test::RSpec::GremlinContext) # Injects sugar and makes sure client is closed after every test
+config.include_context(Grumlin::Test::RSpec::DBCleanerContext) # Cleans the database before every test
+...
+```
+
+It is highly recommended to use `Grumlin::Sugar` and not trying to use lower level APIs as they are subject to change. 
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Before running tests make sure you have gremlin-server running on your computer. The simplest way to run it is using 
+[docker-compose](https://docs.docker.com/compose/) and provided `docker-compose.yml` and `gremlin_server/Dockerfile`:
+
+    $ docker-compose up -d gremlin_server
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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).
+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/[USERNAME]/grumlin. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/grumlin/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/zhulik/grumlin. This project is intended to 
+be a safe, welcoming space for collaboration, and contributors are expected to adhere to the 
+[code of conduct](https://github.com/zhulik/grumlin/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -19,5 +19,5 @@ Async do
 rescue StandardError
   raise
 ensure
-  Grumlin.config.default_pool.close
+  Grumlin.close
 end

data/grumlin.gemspec

@@ -8,8 +8,12 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Gleb Sinyavskiy"]
   spec.email         = ["zhulik.gleb@gmail.com"]
 
-  spec.summary       = "Gremlin query language DSL for Ruby."
-  spec.description   = "Gremlin query language DSL for Ruby."
+  spec.summary       = "Gremlin graph traversal language DSL and client for Ruby."
+
+  spec.description   = <<~DESCRIPTION
+    Gremlin graph traversal language DSL and client for Ruby. Suitable and tested with gremlin-server and AWS Neptune.
+  DESCRIPTION
+
   spec.homepage      = "https://github.com/zhulik/grumlin"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")

data/lib/async/channel.rb

@@ -3,7 +3,7 @@
 module Async
   # Channel is a wrapper around Async::Queue that provides
   # a protocol and handy tools for passing data, exceptions and closing.
-  # It is designed to be used with only one publisher and one subscriber
+  # It is designed to be used only with one publisher and one subscriber
   class Channel
     class ChannelError < StandardError; end
 

data/lib/grumlin/anonymous_step.rb

@@ -5,9 +5,9 @@ module Grumlin
     attr_reader :name, :args, :previous_step
 
     # TODO: add other steps
-    SUPPORTED_STEPS = %w[E V addE addV as by coalesce count dedup drop elementMap emit fold from group groupCount has
-                         hasId hasLabel hasNot in inV label limit not order out outE path project property repeat select
-                         to unfold union valueMap values where].freeze
+    SUPPORTED_STEPS = %i[E V addE addV as both by coalesce count dedup drop elementMap emit fold from group groupCount
+                         has hasId hasLabel hasNot id in inV label limit not order out outE path project property range
+                         repeat select skip tail to unfold union until valueMap values where with].freeze
 
     def initialize(name, *args, previous_step: nil)
       @name = name

data/lib/grumlin/bytecode.rb

@@ -38,10 +38,10 @@ module Grumlin
     # depending on the `serialization_method` parameter. I should be either `:to_readable_bytecode` for human readable
     # representation or `:to_bytecode` for query.
     def serialize_arg(arg, serialization_method: :to_bytecode)
-      return arg.send(serialization_method) if arg.respond_to?(:to_bytecode)
+      return arg.send(serialization_method) if arg.respond_to?(serialization_method)
       return arg unless arg.is_a?(AnonymousStep)
 
-      arg.args.flatten.each.with_object([arg.name]) do |a, res|
+      arg.args.flatten.each.with_object([arg.name.to_s]) do |a, res|
         res << if a.instance_of?(AnonymousStep)
                  a.bytecode.send(serialization_method)
                else

data/lib/grumlin/edge.rb

@@ -18,7 +18,7 @@ module Grumlin
     end
 
     def inspect
-      "e[#{@id}][#{@inV}-#{@label}->#{@outV}]"
+      "e[#{@id}][#{@outV}-#{@label}->#{@inV}]"
     end
     alias to_s inspect
   end

data/lib/grumlin/path.rb

@@ -2,6 +2,8 @@
 
 module Grumlin
   class Path
+    attr_reader :objects
+
     def initialize(path)
       @labels = Typing.cast(path[:labels])
       @objects = Typing.cast(path[:objects])

data/lib/grumlin/sugar.rb

@@ -3,11 +3,13 @@
 module Grumlin
   module Sugar
     HELPERS = [
-      Grumlin::U,
-      Grumlin::T,
-      Grumlin::P,
-      Grumlin::Pop,
-      Grumlin::Order
+      Grumlin::Tools::Order,
+      Grumlin::Tools::P,
+      Grumlin::Tools::Pop,
+      Grumlin::Tools::Scope,
+      Grumlin::Tools::T,
+      Grumlin::Tools::U,
+      Grumlin::Tools::WithOptions
     ].freeze
 
     def self.included(base)
@@ -18,7 +20,7 @@ module Grumlin
     end
 
     def __
-      Grumlin::U
+      Grumlin::Tools::U
     end
 
     def g

data/lib/grumlin/tools/order.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Tools
+    module Order
+      extend Tool
+
+      SUPPORTED_STEPS = %i[asc desc].freeze
+
+      define_steps(SUPPORTED_STEPS, "Order")
+    end
+  end
+end

data/lib/grumlin/tools/p.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Tools
+    module P
+      class << self
+        class Predicate < TypedValue
+          def initialize(name, args:, arg_type: nil)
+            super(type: "P")
+            @name = name
+            @args = args
+            @arg_type = arg_type
+          end
+
+          def value
+            @value ||= {
+              predicate: @name,
+              value: TypedValue.new(type: @arg_type, value: @args).to_bytecode
+            }
+          end
+        end
+
+        # TODO: support more predicates
+        %i[eq neq].each do |predicate|
+          define_method predicate do |*args|
+            Predicate.new(predicate, args: args[0])
+          end
+        end
+
+        %i[within without].each do |predicate|
+          define_method predicate do |*args|
+            args = if args.count == 1 && args[0].is_a?(Array)
+                     args[0]
+                   elsif args.count == 1 && args[0].is_a?(Set)
+                     args[0].to_a
+                   else
+                     args.to_a
+                   end
+            Predicate.new(predicate, args: args, arg_type: "List")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grumlin/tools/pop.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Tools
+    module Pop
+      extend Tool
+
+      SUPPORTED_STEPS = %i[all first last mixed].freeze
+
+      define_steps(SUPPORTED_STEPS, "Pop")
+    end
+  end
+end

data/lib/grumlin/tools/scope.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Tools
+    module Scope
+      extend Tool
+
+      SUPPORTED_STEPS = %i[local].freeze
+
+      define_steps(SUPPORTED_STEPS, "Scope")
+    end
+  end
+end

data/lib/grumlin/tools/t.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Tools
+    module T
+      extend Tool
+
+      SUPPORTED_STEPS = %i[id label].freeze
+
+      define_steps(SUPPORTED_STEPS, "T")
+    end
+  end
+end

data/lib/grumlin/tools/tool.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Tools
+    module Tool
+      def define_steps(steps, tool_name)
+        steps.each do |step|
+          self.class.define_method step do
+            name = "@#{step}"
+            return instance_variable_get(name) if instance_variable_defined?(name)
+
+            instance_variable_set(name, TypedValue.new(type: tool_name, value: step))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grumlin/tools/u.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Tools
+    module U
+      # TODO: add other start steps
+      SUPPORTED_STEPS = %i[V addV count fold has id inV label out outV project repeat timeLimit unfold valueMap
+                           values].freeze
+
+      class << self
+        SUPPORTED_STEPS.each do |step|
+          define_method step do |*args|
+            AnonymousStep.new(step, *args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grumlin/tools/with_options.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Tools
+    module WithOptions
+      WITH_OPTIONS = {
+        tokens: "~tinkerpop.valueMap.tokens",
+        none: 0,
+        ids: 1,
+        labels: 2,
+        keys: 4,
+        values: 8,
+        all: 15,
+        indexer: "~tinkerpop.index.indexer",
+        list: 0,
+        map: 1
+      }.freeze
+
+      class << self
+        WITH_OPTIONS.each do |k, v|
+          define_method k do
+            v
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grumlin/traversal.rb

@@ -2,16 +2,14 @@
 
 module Grumlin
   class Traversal
-    attr_reader :connection
-
     # TODO: add other start steps
-    SUPPORTED_START_STEPS = %w[E V addE addV].freeze
+    SUPPORTED_STEPS = %i[E V addE addV].freeze
 
     def initialize(pool = Grumlin.default_pool)
       @pool = pool
     end
 
-    SUPPORTED_START_STEPS.each do |step|
+    SUPPORTED_STEPS.each do |step|
       define_method step do |*args|
         Step.new(@pool, step, *args)
       end

data/lib/grumlin/typing.rb

@@ -13,6 +13,7 @@ module Grumlin
       "g:Int32" => ->(value) { cast_int(value) },
       "g:Double" => ->(value) { cast_double(value) },
       "g:Traverser" => ->(value) { cast(value[:value]) }, # TODO: wtf is bulk?
+      "g:Direction" => ->(value) { value },
       "g:T" => ->(value) { value.to_sym }
     }.freeze
 

data/lib/grumlin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Grumlin
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grumlin
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Gleb Sinyavskiy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-09-15 00:00:00.000000000 Z
+date: 2021-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-pool
@@ -66,7 +66,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.4'
-description: Gremlin query language DSL for Ruby.
+description: 'Gremlin graph traversal language DSL and client for Ruby. Suitable and
+  tested with gremlin-server and AWS Neptune.
+
+  '
 email:
 - zhulik.gleb@gmail.com
 executables: []
@@ -85,6 +88,7 @@ files:
 - Gemfile.lock
 - LICENSE.txt
 - README.md
+- Rakefile
 - bin/console
 - bin/setup
 - docker-compose.yml
@@ -97,22 +101,25 @@ files:
 - lib/grumlin/bytecode.rb
 - lib/grumlin/client.rb
 - lib/grumlin/edge.rb
-- lib/grumlin/order.rb
-- lib/grumlin/p.rb
 - lib/grumlin/path.rb
-- lib/grumlin/pop.rb
 - lib/grumlin/request_dispatcher.rb
 - lib/grumlin/step.rb
 - lib/grumlin/sugar.rb
-- lib/grumlin/t.rb
 - lib/grumlin/test/rspec.rb
 - lib/grumlin/test/rspec/db_cleaner_context.rb
 - lib/grumlin/test/rspec/gremlin_context.rb
+- lib/grumlin/tools/order.rb
+- lib/grumlin/tools/p.rb
+- lib/grumlin/tools/pop.rb
+- lib/grumlin/tools/scope.rb
+- lib/grumlin/tools/t.rb
+- lib/grumlin/tools/tool.rb
+- lib/grumlin/tools/u.rb
+- lib/grumlin/tools/with_options.rb
 - lib/grumlin/transport.rb
 - lib/grumlin/traversal.rb
 - lib/grumlin/typed_value.rb
 - lib/grumlin/typing.rb
-- lib/grumlin/u.rb
 - lib/grumlin/version.rb
 - lib/grumlin/vertex.rb
 homepage: https://github.com/zhulik/grumlin
@@ -140,5 +147,5 @@ requirements: []
 rubygems_version: 3.2.22
 signing_key: 
 specification_version: 4
-summary: Gremlin query language DSL for Ruby.
+summary: Gremlin graph traversal language DSL and client for Ruby.
 test_files: []

data/lib/grumlin/order.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Grumlin
-  module Order
-    # TODO: share the code?
-    class << self
-      %i[asc desc].each do |step|
-        define_method step do
-          name = "@#{step}"
-          return instance_variable_get(name) if instance_variable_defined?(name)
-
-          instance_variable_set(name, TypedValue.new(type: "Order", value: step))
-        end
-      end
-    end
-  end
-end

data/lib/grumlin/p.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Grumlin
-  module P
-    module P
-      class Predicate < TypedValue
-        def initialize(name, args:, arg_type: nil)
-          super(type: "P")
-          @name = name
-          @args = args
-          @arg_type = arg_type
-        end
-
-        def value
-          @value ||=
-            {
-              predicate: @name,
-              value: TypedValue.new(type: @arg_type, value: @args).to_bytecode
-            }
-        end
-      end
-
-      # TODO: support more predicates
-      %w[eq neq].each do |predicate|
-        define_method predicate do |*args|
-          Predicate.new(predicate, args: args[0])
-        end
-      end
-
-      %w[within without].each do |predicate|
-        define_method predicate do |*args|
-          args = if args.count == 1 && args[0].is_a?(Array)
-                   args[0]
-                 elsif args.count == 1 && args[0].is_a?(Set)
-                   args[0].to_a
-                 else
-                   args.to_a
-                 end
-          Predicate.new(predicate, args: args, arg_type: "List")
-        end
-      end
-    end
-
-    extend P
-  end
-end

data/lib/grumlin/pop.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Grumlin
-  module Pop
-    # TODO: share the code?
-    class << self
-      %i[first last all mixed].each do |step|
-        define_method step do
-          name = "@#{step}"
-          return instance_variable_get(name) if instance_variable_defined?(name)
-
-          instance_variable_set(name, TypedValue.new(type: "Pop", value: step))
-        end
-      end
-    end
-  end
-end

data/lib/grumlin/t.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Grumlin
-  module T
-    # TODO: share the code?
-    class << self
-      %i[id label].each do |step|
-        define_method step do
-          name = "@#{step}"
-          return instance_variable_get(name) if instance_variable_defined?(name)
-
-          instance_variable_set(name, TypedValue.new(type: "T", value: step))
-        end
-      end
-    end
-  end
-end

data/lib/grumlin/u.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Grumlin
-  module U
-    # TODO: add other start steps
-    SUPPORTED_START_STEPS = %w[V addV count fold has out repeat unfold values].freeze
-
-    class << self
-      SUPPORTED_START_STEPS.each do |step|
-        define_method step do |*args|
-          AnonymousStep.new(step, *args)
-        end
-      end
-    end
-  end
-end