grumlin 0.16.1 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce713ebd08c676dfe38124e0286963ea18ee8d5d51f678096fd5f2ae8c28c51c
-  data.tar.gz: 6cd25c9ac701a2276fdb470b55b4ebaf123323521c6cd8d4d87365b68d604426
+  metadata.gz: 573e2c9cda13465c0560d36e9e10d8bcdda5e0ea01ea4bbf89cb8d6cb943f6de
+  data.tar.gz: 8dd6fa7264875f372c6117352f2e87c7984457ff3f94da57f8f19d91344c4dd2
 SHA512:
-  metadata.gz: 81b5b522b5d183240d27cb36285f448e4918386cd267ea84fcffb2cc763d156d272844a4ffab2e00999d5c5be129930d905220506e07702ff150c49ac7388d1b
-  data.tar.gz: f4d56b0a66d91f8f454964a8d42de46fa0b6b85595c48e67e09875e01bfdb96eb131e0c6cb5ec395ebeb7dda59c45ff67c445f88e75a12a03436689d9ba14279
+  metadata.gz: 2eea2219d92cd29ef311993dcd0bcd0e9d8906d39474d93733c8406952e93babf85d4468b6acd15ac1d114c940c49533603960fa496c8f757223d016b5619a03
+  data.tar.gz: 39c8821a89cb1194d973c7b2dee5e96ad90288e2a611ef42a080586987759949453a2c7bade5be56d500588a8655a485c6c415c075c1295534bbc8a419bf2d43

data/.rubocop.yml

@@ -44,6 +44,7 @@ Naming/MethodParameterName:
     - outV
     - inVLabel
     - outVLabel
+    - to
 
 RSpec/NamedSubject:
   Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    grumlin (0.16.1)
+    grumlin (0.18.1)
       async-pool (~> 0.3)
       async-websocket (~> 0.19)
       oj (~> 3.12)
@@ -44,7 +44,7 @@ GEM
     benchmark (0.1.1)
     childprocess (4.0.0)
     concurrent-ruby (1.1.8)
-    console (1.14.0)
+    console (1.15.0)
       fiber-local
     diff-lcs (1.4.4)
     docile (1.4.0)

data/README.md

@@ -77,8 +77,7 @@ end
 
 **Shortcuts** is a way to share and organize gremlin code. They let developers define their own steps consisting of
 sequences of standard gremlin steps, other shortcuts and even add new initially unsupported by Grumlin steps.
-Remember ActiveRecord scopes? Shortcuts are very similar. `Grumlin::Shortcuts#with_shortcuts` wraps a given object into
-a proxy object that simply proxies all methods existing in the wrapped object to it and handles shortcuts.
+Remember ActiveRecord scopes? Shortcuts are very similar.
 
 **Important**: if a shortcut's name matches a name of a method defined on the wrapped object, this shortcut will be
 be ignored because methods have higher priority. You cannot override supported by Grumlin steps with shortcuts, 
@@ -128,17 +127,18 @@ class MyRepository
 
   # Wrapping a traversal
   def red_triangles
-    with_shortcuts(g).V.hasLabel(:triangle)
-                       .hasColor("red")
-                       .toList
+    g(self.class.shortcuts).V.hasLabel(:triangle)
+       .hasColor("red")
+       .toList
   end
 
   # Wrapping _
   def something_else
-    with_shortcuts(g).V.hasColor("red")
-                       .repeat(with_shortcuts(__)
-                       .out(:has)
-                       .hasColor("blue")).toList
+    g(self.class.shortcuts).V.hasColor("red")
+       .repeat(__(self.class.shortcuts))
+       .out(:has)
+       .hasColor("blue")
+       .toList
   end
 end
 ```
@@ -150,7 +150,7 @@ shortcuts to make gremlin code more rubyish. Can be used as a drop in replacemen
 or `Grumlin::Shortcuts` can be inherited**, successors don't need to extend them again and have access to shortcuts 
 defined in the ancestor.
 
-**Using**:
+**Definition**
 
 ```ruby
 class MyRepository
@@ -167,15 +167,53 @@ class MyRepository
     hasAll(T.label => :triangle, color: color)
   end
 
-  # g and __ are already aware of shortcuts 
-  def red_triangles
+  # g and __ are already aware of shortcuts
+  query(:triangles_with_color, return_mode: :list) do |color| # :list is the default return mode, also possible: :none, :single, :traversal
     g.V.hasLabel(:triangle)
-       .hasColor("red")
-       .toList
+       .hasColor(color)
   end
+  # Note that when using the `query` one does not need to call a termination step like `next` or `toList`,
+  # repository does it automatically in according to the `return_mode` parameter. 
 end
 ```
 
+Each `return_mode` is mapped to a particular termination step:
+- `:list` - `toList`
+- `:single` - `next`
+- `:none` - `iterate`
+- `:traversal` - do not execute the query and return the traversal as is
+
+`Grumlin::Repository` also provides a set of generic CRUD operations:
+- `add_vertex(label, id = nil, **properties)`
+- `add_edge(label, id = nil, from:, to:, **properties)`
+- `drop_vertex(id)`
+- `drop_edge(id = nil, from: nil, to: nil, label: nil)`
+- `upsert_vertex(label, id, create_properties: {}, update_properties: {})`
+- `upsert_edge(label, from:, to:, create_properties: {}, update_properties: {})`
+
+**Usage**
+
+To execute the query defined in a query block one simply needs to call a method with the same name:
+
+`MyRepository.new.triangles_with_color(:red)`
+
+One can also override the `return_mode`:
+
+`MyRepository.new.triangles_with_color(:red, query_params: { return_mode: :single })`
+
+or even pass a block to the method and a raw traversal will be yielded:
+```ruby
+MyRepository.new.triangles_with_color(:red) do |t|
+  t.has(:other_property, :some_value).toList
+end
+```
+it may be useful for debugging. Note that one needs to call a termination step manually in this case.
+
+`query` also provides a helper for profiling requests:
+`MyRepository.new.triangles_with_color(:red, query_params: { profile: true })`
+
+method will return profiling data of the results.
+
 #### IRB
 
 An example of how to start an IRB session with support for executing gremlin queries:

data/lib/grumlin/action.rb

@@ -49,12 +49,6 @@ module Grumlin
       @shortcuts.key?(@name)
     end
 
-    def arguments
-      @arguments ||= [*@args].tap do |args|
-        args << @params if @params.any?
-      end
-    end
-
     def method_missing(name, *args, **params)
       return step(name, *args, **params) if @shortcuts.key?(name)
 

data/lib/grumlin/repository.rb

@@ -2,7 +2,16 @@
 
 module Grumlin
   module Repository
+    RETURN_MODES = {
+      list: :toList,
+      none: :iterate,
+      single: :next,
+      traversal: :nil
+    }.freeze
+
     module InstanceMethods
+      include Grumlin::Expressions
+
       def __
         TraversalStart.new(self.class.shortcuts)
       end
@@ -10,14 +19,130 @@ module Grumlin
       def g
         TraversalStart.new(self.class.shortcuts)
       end
+
+      def drop_vertex(id)
+        g.V(id).drop.iterate
+      end
+
+      def drop_edge(id = nil, from: nil, to: nil, label: nil) # rubocop:disable Metrics/AbcSize
+        raise ArgumentError, "either id or from:, to: and label: must be passed" if [id, from, to, label].all?(&:nil?)
+        return g.E(id).drop.iterate unless id.nil?
+
+        raise ArgumentError, "from:, to: and label: must be passed" if [from, to, label].any?(&:nil?)
+
+        g.V(from).outE(label).where(__.inV.hasId(to)).limit(1).drop.iterate
+      end
+
+      def add_vertex(label, id = nil, **properties)
+        id ||= properties[T.id]
+        properties = except(properties, T.id)
+
+        t = g.addV(label)
+        t = t.props(T.id => id) unless id.nil?
+        t.props(**properties).next
+      end
+
+      def add_edge(label, id = nil, from:, to:, **properties)
+        id ||= properties[T.id]
+        properties = except(properties, T.label)
+        properties[T.id] = id
+
+        g.addE(label).from(__.V(from)).to(__.V(to)).props(**properties).next
+      end
+
+      def upsert_vertex(label, id, create_properties: {}, update_properties: {}) # rubocop:disable Metrics/AbcSize
+        create_properties = except(create_properties, T.id, T.label)
+        update_properties = except(update_properties, T.id, T.label)
+        g.V(id)
+         .fold
+         .coalesce(
+           __.unfold,
+           __.addV(label).props(**create_properties.merge(T.id => id))
+         ).props(**update_properties)
+         .next
+      end
+
+      # Only from and to are used to find the existing edge, if one wants to assign an id to a created edge,
+      # it must be passed as T.id in via create_properties.
+      def upsert_edge(label, from:, to:, create_properties: {}, update_properties: {}) # rubocop:disable Metrics/AbcSize
+        create_properties = except(create_properties, T.label)
+        update_properties = except(update_properties, T.id, T.label)
+
+        g.V(from)
+         .outE(label).where(__.inV.hasId(to))
+         .fold
+         .coalesce(
+           __.unfold,
+           __.addE(label).from(__.V(from)).to(__.V(to)).props(**create_properties)
+         ).props(**update_properties).next
+      end
+
+      private
+
+      # A polyfill for Hash#except for ruby 2.x environments without ActiveSupport
+      # TODO: delete and use native Hash#except when after ruby 2.7 is deprecated.
+      def except(hash, *keys)
+        return hash.except(*keys) if hash.respond_to?(:except)
+
+        hash.each_with_object({}) do |(k, v), res|
+          res[k] = v unless keys.include?(k)
+        end
+      end
     end
 
     def self.extended(base)
       base.extend(Grumlin::Shortcuts)
-      base.include(Grumlin::Expressions)
       base.include(InstanceMethods)
 
       base.shortcuts_from(Grumlin::Shortcuts::Properties)
     end
+
+    def query(name, return_mode: :list, postprocess_with: nil, &query_block) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      return_mode = validate_return_mode!(return_mode)
+      postprocess_with = validate_postprocess_with!(postprocess_with)
+
+      define_method name do |*args, query_params: {}, **params, &block|
+        t = instance_exec(*args, **params, &query_block)
+        return t if self.class.empty_result?(t)
+
+        unless t.is_a?(Grumlin::Action)
+          raise WrongQueryResult,
+                "queries must return #{Grumlin::Action}, nil or an empty collection. Given: #{t.class}"
+        end
+
+        return block.call(t) unless block.nil?
+
+        return t.profile.next if query_params[:profile] == true
+
+        return_mode = self.class.validate_return_mode!(query_params[:return_mode] || return_mode)
+
+        return t if return_mode == :traversal
+
+        t.public_send(RETURN_MODES[return_mode]).tap do |result|
+          return postprocess_with.call(result) if postprocess_with.respond_to?(:call)
+          return send(postprocess_with, result) unless postprocess_with.nil?
+        end
+      end
+    end
+
+    def validate_return_mode!(return_mode)
+      return return_mode if RETURN_MODES.key?(return_mode)
+
+      raise ArgumentError, "unsupported return mode #{return_mode}. Supported modes: #{RETURN_MODES.keys}"
+    end
+
+    def validate_postprocess_with!(postprocess_with)
+      if postprocess_with.nil? || postprocess_with.is_a?(Symbol) ||
+         postprocess_with.is_a?(String) || postprocess_with.respond_to?(:call)
+        return postprocess_with
+      end
+
+      raise ArgumentError,
+            "postprocess_with must be a String, Symbol or a callable object, given: #{postprocess_with.class}"
+    end
+
+    def empty_result?(result)
+      result.nil? || (result.respond_to?(:empty?) && result.empty?)
+    end
   end
 end

data/lib/grumlin/shortcuts/properties.rb

@@ -5,17 +5,13 @@ module Grumlin
     module Properties
       extend Grumlin::Shortcuts
 
-      shortcut :props do |props|
-        next if props.nil? # TODO: fixme, add proper support for **params
-
-        props.reduce(self) do |tt, (prop, value)|
+      shortcut :props do |**props|
+        props.compact.reduce(self) do |tt, (prop, value)|
           tt.property(prop, value)
         end
       end
 
-      shortcut :hasAll do |props|
-        next if props.nil? # TODO: fixme, add proper support for **params
-
+      shortcut :hasAll do |**props|
         props.reduce(self) do |tt, (prop, value)|
           tt.has(prop, value)
         end

data/lib/grumlin/shortcuts_applyer.rb

@@ -18,7 +18,7 @@ module Grumlin
 
       Steps.new(shortcuts).tap do |processed_steps|
         (configuration_steps + regular_steps).each do |step|
-          processed_steps.add(step.name, step.arguments)
+          processed_steps.add(step.name, args: step.args, params: step.params)
         end
       end
     end
@@ -27,20 +27,20 @@ module Grumlin
 
     def process_steps(steps, shortcuts) # rubocop:disable Metrics/AbcSize
       steps.each_with_object([]) do |step, result|
-        arguments = step.arguments.map do |arg|
+        args = step.args.map do |arg|
           arg.is_a?(Steps) ? ShortcutsApplyer.call(arg) : arg
         end
 
         if shortcuts.include?(step.name)
           t = TraversalStart.new(shortcuts)
-          action = shortcuts[step.name].apply(t, *arguments)
+          action = shortcuts[step.name].apply(t, *args, **step.params)
           next if action.nil? || action == t # Shortcut did not add any steps
 
           new_steps = ShortcutsApplyer.call(Steps.from(action))
           result.concat(new_steps.configuration_steps)
           result.concat(new_steps.steps)
         else
-          result << StepData.new(step.name, arguments)
+          result << StepData.new(step.name, args: args, params: step.params)
         end
       end
     end

data/lib/grumlin/step_data.rb

@@ -2,17 +2,19 @@
 
 module Grumlin
   class StepData
-    attr_reader :name, :arguments
+    attr_reader :name, :args, :params
 
-    def initialize(name, arguments)
+    def initialize(name, args: [], params: {})
       @name = name
-      @arguments = arguments
+      @args = args
+      @params = params
     end
 
     def ==(other)
       self.class == other.class &&
         @name == other.name &&
-        @arguments == other.arguments
+        @args == other.args &&
+        @params == other.params
     end
   end
 end

data/lib/grumlin/steps.rb

@@ -18,7 +18,7 @@ module Grumlin
 
       new(shortcuts).tap do |chain|
         actions.each do |act|
-          chain.add(act.name, act.arguments)
+          chain.add(act.name, args: act.args, params: act.params)
         end
       end
     end
@@ -31,10 +31,10 @@ module Grumlin
       @steps = steps
     end
 
-    def add(name, arguments)
-      return add_configuration_step(name, arguments) if CONFIGURATION_STEPS.include?(name)
+    def add(name, args: [], params: {})
+      return add_configuration_step(name, args: args, params: params) if CONFIGURATION_STEPS.include?(name)
 
-      StepData.new(name, cast_arguments(arguments)).tap do |step|
+      StepData.new(name, args: cast_arguments(args), params: params).tap do |step|
         @steps << step
       end
     end
@@ -56,16 +56,16 @@ module Grumlin
 
     def shortcuts?(steps_ary)
       steps_ary.any? do |step|
-        @shortcuts.include?(step.name) || step.arguments.any? do |arg|
+        @shortcuts.include?(step.name) || step.args.any? do |arg|
           arg.is_a?(Steps) ? arg.uses_shortcuts? : false
         end
       end
     end
 
-    def add_configuration_step(name, arguments)
+    def add_configuration_step(name, args: [], params: {})
       raise ArgumentError, "cannot use configuration steps after start step was used" unless @steps.empty?
 
-      StepData.new(name, cast_arguments(arguments)).tap do |step|
+      StepData.new(name, args: cast_arguments(args), params: params).tap do |step|
         @configuration_steps << step
       end
     end

data/lib/grumlin/steps_serializers/bytecode.rb

@@ -6,7 +6,7 @@ module Grumlin
       # constructor params: no_return: true|false, default false
       # TODO: add pretty
 
-      NONE_STEP = StepData.new("none", [])
+      NONE_STEP = StepData.new("none")
 
       def serialize
         steps = ShortcutsApplyer.call(@steps)
@@ -22,7 +22,7 @@ module Grumlin
       private
 
       def serialize_step(step)
-        [step.name, *step.arguments.map { |arg| serialize_arg(arg) }]
+        [step.name, *step.args.map { |arg| serialize_arg(arg) }, step.params.any? ? step.params : nil].compact
       end
 
       def serialize_arg(arg)

data/lib/grumlin/steps_serializers/human_readable_bytecode.rb

@@ -2,22 +2,16 @@
 
 module Grumlin
   module StepsSerializers
-    class HumanReadableBytecode < Serializer
+    class HumanReadableBytecode < Bytecode
       def serialize
         steps = ShortcutsApplyer.call(@steps)
-        [serialize_steps(steps.configuration_steps), serialize_steps(steps.steps)]
-      end
-
-      def serialize_steps(steps)
-        steps.map { |s| serialize_step(s) }
+        [steps.configuration_steps, steps.steps].map do |stps|
+          stps.map { |s| serialize_step(s) }
+        end
       end
 
       private
 
-      def serialize_step(step)
-        [step.name, *step.arguments.map { |arg| serialize_arg(arg) }]
-      end
-
       def serialize_arg(arg)
         return arg.to_s if arg.is_a?(TypedValue)
         return serialize_predicate(arg) if arg.is_a?(Expressions::P::Predicate)

data/lib/grumlin/steps_serializers/string.rb

@@ -10,14 +10,21 @@ module Grumlin
       def serialize
         steps = @params[:apply_shortcuts] ? ShortcutsApplyer.call(@steps) : @steps
 
-        configuration_steps = serialize_steps(steps.configuration_steps)
-        regular_steps = serialize_steps(steps.steps)
+        steps = [steps.configuration_steps, steps.steps].map do |stps|
+          stps.map { |step| serialize_step(step) }
+        end
 
-        "#{prefix}.#{(configuration_steps + regular_steps).join(".")}"
+        "#{prefix}.#{(steps[0] + steps[1]).join(".")}"
       end
 
       private
 
+      def serialize_step(step)
+        "#{step.name}(#{(step.args + [step.params.any? ? step.params : nil].compact).map do |a|
+          serialize_arg(a)
+        end.join(", ")})"
+      end
+
       def prefix
         @prefix ||= @params[:anonymous] ? "__" : "g"
       end
@@ -31,12 +38,6 @@ module Grumlin
 
         StepsSerializers::String.new(arg, anonymous: true, **@params).serialize
       end
-
-      def serialize_steps(steps)
-        steps.map do |step|
-          "#{step.name}(#{step.arguments.map { |a| serialize_arg(a) }.join(", ")})"
-        end
-      end
     end
   end
 end

data/lib/grumlin/typing.rb

@@ -18,7 +18,7 @@ module Grumlin
       # "g:VertexProperty"=> ->(value) { value }, # TODO: implement me
       "g:TraversalMetrics" => ->(value) { cast_map(value[:@value]) },
       "g:Metrics" => ->(value) { cast_map(value[:@value]) },
-      "g:T" => ->(value) { value.to_sym }
+      "g:T" => ->(value) { Grumlin::Expressions::T.public_send(value) }
     }.freeze
 
     CASTABLE_TYPES = [Hash, String, Integer, TrueClass, FalseClass].freeze
@@ -69,7 +69,7 @@ module Grumlin
       def cast_map(value)
         Hash[*value].transform_keys do |key|
           next key.to_sym if key.respond_to?(:to_sym)
-          next cast(key) if key[:@type]
+          next cast(key) if key[:@type] # TODO: g.V.group.by(:none_existing_property).next
 
           raise UnknownMapKey, key, value
         end.transform_values { |v| cast(v) }

data/lib/grumlin/version.rb

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

data/lib/grumlin.rb

@@ -100,6 +100,10 @@ module Grumlin
     end
   end
 
+  class RepositoryError < Error; end
+
+  class WrongQueryResult < RepositoryError; end
+
   class Config
     attr_accessor :url, :pool_size, :client_concurrency, :client_factory
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grumlin
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.18.1
 platform: ruby
 authors:
 - Gleb Sinyavskiy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-03-15 00:00:00.000000000 Z
+date: 2022-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-pool
@@ -155,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: Gremlin graph traversal language DSL and client for Ruby.