skydb 0.2.1 → 0.2.2

data/lib/skydb/property.rb

@@ -9,11 +9,11 @@ class SkyDB
     ##########################################################################
 
     # Initializes the property.
-    def initialize(id=0, type=nil, data_type="String", name=nil)
-      self.id = id
-      self.type = type
-      self.data_type = data_type
-      self.name = name
+    def initialize(options={})
+      self.id = options[:id]
+      self.type = options[:type]
+      self.data_type = options[:data_type]
+      self.name = options[:name]
     end
     
 

data/lib/skydb/query.rb

@@ -0,0 +1,198 @@
+require 'skydb/query/selection'
+require 'skydb/query/after'
+require 'skydb/query/validation_error'
+
+class SkyDB
+  # The Query object represents a high level abstraction of how data is
+  # processed and retrieved from the database. It is inspired by ActiveRecord
+  # in the sense that commands can be chained together.
+  #
+  # The query is not executed until the execute() method is called.
+  class Query
+    ##########################################################################
+    #
+    # Constructor
+    #
+    ##########################################################################
+
+    def initialize(options={})
+      self.client = options[:client]
+      self.selection = options[:selection] || SkyDB::Query::Selection.new()
+      self.conditions = options[:conditions] || []
+    end
+    
+
+    ##########################################################################
+    #
+    # Attributes
+    #
+    ##########################################################################
+
+    # The client that is used for executing the query.
+    attr_accessor :client
+
+    # The properties that should be selected from the database.
+    attr_accessor :selection
+
+    # A list of conditions that must be fulfilled before selection can occur.
+    attr_accessor :conditions
+
+    # The number of idle seconds that separates sessions. 
+    attr_accessor :session_idle_time
+
+
+    ##########################################################################
+    #
+    # Methods
+    #
+    ##########################################################################
+    
+    ####################################
+    # Helpers
+    ####################################
+
+    # Adds a list of fields to the selection.
+    #
+    # @param [String] fields  A list of fields to add to the selection.
+    #
+    # @return [Query]  The query object is returned.
+    def select(*fields)
+      selection.select(*fields)
+      return self
+    end
+
+    # Adds one or more grouping fields to the selection of the query.
+    #
+    # @param [String] groups  A list of groups to add to the selection.
+    #
+    # @return [Query]  The query object is returned.
+    def group_by(*groups)
+      selection.group_by(*groups)
+      return self
+    end
+
+    # Adds an 'after' condition to the query.
+    #
+    # @param [Hash] options  The options to pass to the 'after' condition.
+    #
+    # @return [Query]  The query object is returned.
+    def after(options={})
+      conditions << SkyDB::Query::After.new(options)
+      return self
+    end
+
+    # Sets the session idle seconds and returns the query object.
+    #
+    # @param [Fixnum] seconds  The number of idle seconds.
+    #
+    # @return [Query]  The query object is returned.
+    def session(seconds)
+      self.session_idle_time = seconds
+      return self
+    end
+
+
+    ####################################
+    # Execution
+    ####################################
+
+    # Executes the query and returns the resulting data.
+    def execute
+      # Generate the Lua code for this query.
+      code = codegen()
+      
+      # Send it to the server.
+      results = client.aggregate(code)
+      
+      # Return the results.
+      return results
+    end
+
+
+    ####################################
+    # Validation
+    ####################################
+
+    # Validates that all the elements of the query are valid.
+    def validate!
+      selection.validate!
+    end
+    
+    
+    ####################################
+    # Codegen
+    ####################################
+
+    # Generates the Lua code that represents the query.
+    def codegen
+      # Lookup all actions & properties.
+      lookup_identifiers()
+      
+      # Validate everything in query before proceeding.
+      validate!
+
+      # Generate selection.
+      code = []
+      code << selection.codegen_select()
+      
+      # Generate condition functions.
+      conditions.each_with_index do |condition, index|
+        condition.function_name ||= "__condition#{nextseq}"
+        code << condition.codegen
+      end
+
+      # Generate the invocation of the conditions.
+      conditionals = conditions.map {|condition| "#{condition.function_name}(cursor, data)"}.join(' and ')
+      conditionals = "true" if conditions.length == 0
+      
+      # Generate aggregate() function.
+      code << "function aggregate(cursor, data)"
+      code << "  cursor:set_session_idle(#{session_idle_time.to_i})" if session_idle_time.to_i > 0
+      code << "  while cursor:next_session() do"
+      code << "    while cursor:next() do"
+      code << "      if #{conditionals} then"
+      code << "        select(cursor, data)"
+      code << "      end"
+      code << "    end"
+      code << "  end"
+      code << "end"
+      code << ""
+
+      # Generate merge function.
+      code << selection.codegen_merge()
+      
+      return code.join("\n")
+    end
+
+
+    ####################################
+    # Utility
+    ####################################
+    
+    private
+    
+    # Generates a sequence number used for uniquely naming objects and
+    # functions in the query.
+    def nextseq
+      @sequence = (@sequence || 0) + 1
+    end
+
+    # Looks up all actions and properties that are missing an identifier.
+    def lookup_identifiers
+      # Find all the actions on conditions that are missing an id.
+      actions = []
+      conditions.each do |condition|
+        if condition.action.is_a?(SkyDB::Action) && condition.action.id.to_i == 0
+          actions << condition.action
+        end
+      end
+
+      # Lookup all the actions.
+      if actions.length > 0
+        client.lookup(:actions => actions)
+      end
+      
+      return nil
+    end
+  end
+end

data/lib/skydb/query/after.rb

@@ -0,0 +1,103 @@
+class SkyDB
+  class Query
+    # The 'after' condition filters out selection only after the condition
+    # has been fulfilled.
+    class After
+      ##########################################################################
+      #
+      # Constructor
+      #
+      ##########################################################################
+
+      def initialize(action=nil, options={})
+        options.merge!(action.is_a?(Hash) ? action : {:action => action})
+        self.action = options[:action]
+        self.function_name = options[:function_name]
+      end
+    
+
+      ##########################################################################
+      #
+      # Attributes
+      #
+      ##########################################################################
+
+      # The function name to use when generating the code.
+      attr_accessor :function_name
+
+      # The action to match. If set to a string or id then it is automatically
+      # wrapped in an Action object.
+      attr_reader :action
+      
+      def action=(value)
+        if value.is_a?(Symbol)
+          @action = :enter
+        elsif value.is_a?(String)
+          @action = SkyDB::Action.new(:name => value)
+        elsif value.is_a?(Fixnum)
+          @action = SkyDB::Action.new(:id => value)
+        elsif value.is_a?(SkyDB::Action)
+          @action = value
+        else
+          @action = nil
+        end
+      end
+
+
+      ##########################################################################
+      #
+      # Methods
+      #
+      ##########################################################################
+
+      ##################################
+      # Validation
+      ##################################
+
+      # Validates that the object is correct before executing a codegen.
+      def validate!
+        # Require the action identifier.
+        if action.nil? || action.id.to_i == 0
+          raise SkyDB::Query::ValidationError.new("Action with non-zero identifier required.")
+        end
+
+        # Require the function name. This should be set automatically by the
+        # query.
+        if function_name.to_s.index(/^\w+$/).nil?
+          raise SkyDB::Query::ValidationError.new("Invalid function name '#{function_name.to_s}'.")
+        end
+        
+        return nil
+      end
+      
+      
+      ##################################
+      # Codegen
+      ##################################
+
+      # Generates Lua code to match a given action.
+      def codegen(options={})
+        header, body, footer = "function #{function_name.to_s}(cursor, data)\n", [], "end\n"
+      
+        # If the action is :enter then just check for the beginning of a session.
+        if action == :enter
+          body << "return (cursor.session_event_index == 0)"
+        else
+          # Only move to the next event if directed to by the options.
+          body << "repeat"
+          body << "  if cursor.event.action_id == #{action.id.to_i} then"
+          body << "    cursor:next()"
+          body << "    return true"
+          body << "  end"
+          body << "until not cursor:next()"
+          body << "return false"
+        end
+
+        # Indent body and return.
+        body.map! {|line| "  " + line}
+        return header + body.join("\n") + "\n" + footer
+      end
+    end
+  end
+end
+

data/lib/skydb/query/ast/selection_field_syntax_node.rb

@@ -0,0 +1,26 @@
+class SkyDB
+  class Query
+    class Ast
+      module SelectionFieldSyntaxNode
+        # Generates the SelectionField object from the node.
+        def generate
+          field = SkyDB::Query::SelectionField.new()
+
+          # If there is an expression present then use it.
+          if respond_to?('expression')
+            field.expression = expression.text_value
+
+          # Otherwise we'll typically use the whole value unless there is an
+          # aggregation type mentioned. An example of this is: "count()".
+          elsif !respond_to?('aggregation_type')
+            field.expression = text_value
+          end
+
+          field.alias_name = alias_name.text_value if respond_to?('alias_name')
+          field.aggregation_type = aggregation_type.text_value.downcase.to_sym if respond_to?('aggregation_type')
+          return field
+        end
+      end
+    end
+  end
+end

data/lib/skydb/query/ast/selection_fields_syntax_node.rb

@@ -0,0 +1,16 @@
+class SkyDB
+  class Query
+    class Ast
+      module SelectionFieldsSyntaxNode
+        # Generates a list of selection fields.
+        def generate
+          fields = []
+          Treetop.search(self, SelectionFieldSyntaxNode).each do |field_node|
+            fields << field_node.generate()
+          end
+          return fields
+        end
+      end
+    end
+  end
+end

data/lib/skydb/query/ast/selection_group_syntax_node.rb

@@ -0,0 +1,16 @@
+class SkyDB
+  class Query
+    class Ast
+      module SelectionGroupSyntaxNode
+        # Generates the SelectionGroup object from the node.
+        def generate
+          group = SkyDB::Query::SelectionGroup.new(
+            :expression => (respond_to?('expression') ? expression.text_value : text_value)
+          )
+          group.alias_name = alias_name.text_value if respond_to?('alias_name')
+          return group
+        end
+      end
+    end
+  end
+end

data/lib/skydb/query/ast/selection_groups_syntax_node.rb

@@ -0,0 +1,16 @@
+class SkyDB
+  class Query
+    class Ast
+      module SelectionGroupsSyntaxNode
+        # Generates a list of selection groups.
+        def generate
+          groups = []
+          Treetop.search(self, SelectionGroupSyntaxNode).each do |group_node|
+            groups << group_node.generate()
+          end
+          return groups
+        end
+      end
+    end
+  end
+end

data/lib/skydb/query/selection.rb

@@ -0,0 +1,268 @@
+require 'skydb/query/selection_fields_parse_error'
+require 'skydb/query/selection_field'
+
+require 'skydb/query/selection_groups_parse_error'
+require 'skydb/query/selection_group'
+
+require 'skydb/query/ast/selection_fields_syntax_node'
+require 'skydb/query/ast/selection_field_syntax_node'
+require 'skydb/query/ast/selection_groups_syntax_node'
+require 'skydb/query/ast/selection_group_syntax_node'
+require 'skydb/query/selection_fields_grammar'
+require 'skydb/query/selection_groups_grammar'
+
+class SkyDB
+  class Query
+    # The selection object contains a list of all fields and their aliases.
+    # Selection fields can include simple properties as well as aggregation
+    # functions.
+    class Selection
+      ##########################################################################
+      #
+      # Static Methods
+      #
+      ##########################################################################
+
+      # Parses a string into a list of selection fields.
+      #
+      # @param [String] str  A formatted list of fields to select.
+      #
+      # @return [Array]  An array of selection fields.
+      def self.parse_fields(str)
+        # Parse the selection fields string.
+        parser = SelectionFieldsGrammarParser.new()
+        ast = parser.parse(str)
+
+        # If there was a problem then throw a parse error.
+        if ast.nil?
+          raise SkyDB::Query::SelectionFieldsParseError.new(parser.failure_reason,
+            :line => parser.failure_line,
+            :column => parser.failure_column
+          )
+        end
+        
+        return ast.generate
+      end
+
+      # Parses a string into a list of selection groups.
+      #
+      # @param [String] str  A formatted list of fields to group by.
+      #
+      # @return [Array]  An array of selection groups.
+      def self.parse_groups(str)
+        # Parse the selection groups string.
+        parser = SelectionGroupsGrammarParser.new()
+        ast = parser.parse(str)
+
+        # If there was a problem then throw a parse error.
+        if ast.nil?
+          raise SkyDB::Query::SelectionGroupsParseError.new(parser.failure_reason,
+            :line => parser.failure_line,
+            :column => parser.failure_column
+          )
+        end
+        
+        return ast.generate
+      end
+      
+
+      ##########################################################################
+      #
+      # Constructor
+      #
+      ##########################################################################
+
+      def initialize(options={})
+        self.fields = options[:fields] || []
+        self.groups = options[:groups] || []
+      end
+    
+
+      ##########################################################################
+      #
+      # Attributes
+      #
+      ##########################################################################
+
+      # A list of fields that will be returned from the server.
+      attr_accessor :fields
+
+      # A list of expressions to group the returned data by.
+      attr_accessor :groups
+
+
+      ##########################################################################
+      #
+      # Methods
+      #
+      ##########################################################################
+    
+      ####################################
+      # Helpers
+      ####################################
+
+      # Adds a list of fields to the selection.
+      #
+      # @param [String] args  A list of fields to add to the selection.
+      #
+      # @return [Selection]  The selection object is returned.
+      def select(*args)
+        args.each do |arg|
+          if arg.is_a?(String)
+            self.fields = self.fields.concat(SkyDB::Query::Selection.parse_fields(arg))
+          elsif arg.is_a?(Symbol)
+            self.fields << SelectionField.new(:expression => arg.to_s)
+          else
+            raise "Invalid selection argument: #{arg} (#{arg.class})"
+          end
+        end
+        
+        return self
+      end
+
+      # Adds one or more grouping fields to the selection of the query.
+      #
+      # @param [String] args  A list of groups to add to the selection.
+      #
+      # @return [Selection]  The selection object is returned.
+      def group_by(*args)
+        args.each do |arg|
+          if arg.is_a?(String)
+            self.groups = self.groups.concat(SkyDB::Query::Selection.parse_groups(arg))
+          elsif arg.is_a?(Symbol)
+            self.groups << SelectionGroup.new(:expression => arg.to_s)
+          else
+            raise "Invalid group by argument: #{arg} (#{arg.class})"
+          end
+        end
+        
+        return self
+      end
+
+
+      ####################################
+      # Validation
+      ####################################
+
+      # Validates that all the elements of the query are valid.
+      def validate!
+        # Require that at least one field exist.
+        if fields.length == 0
+          raise SkyDB::Query::ValidationError.new("At least one selection field is required for #{self.inspect}.")
+        end
+
+        fields.each do |field|
+          field.validate!
+        end
+
+        groups.each do |group|
+          group.validate!
+        end
+      end
+
+
+      ####################################
+      # Codegen
+      ####################################
+
+      # Generates Lua code for the aggregation based on the selection.
+      def codegen_select
+        header, body, footer = "function select(cursor, data)\n", [], "end\n"
+      
+        # Setup target object.
+        body << "target = data"
+        body << "" if groups.length > 0
+
+        # Initialize groups.
+        groups.each do |group|
+          body << "group_value = #{group.accessor}"
+          body << "if cursor:eos() or cursor:eof() then group_value = -1 end" if group.expression == 'action_id'
+          body << "if target[group_value] == nil then"
+          body << "  target[group_value] = {}"
+          body << "end"
+          body << "target = target[group_value]"
+          body << ""
+        end
+
+        # Generate the assignment for each field.
+        fields.each do |field|
+          alias_name = field.target_name
+          
+          case field.aggregation_type
+          when nil
+            body << "target.#{alias_name} = #{field.accessor}"
+          when :count
+            body << "target.#{alias_name} = (target.#{alias_name} or 0) + 1"
+          when :sum
+            body << "target.#{alias_name} = (target.#{alias_name} or 0) + #{field.accessor}"
+          when :min
+            body << "if(target.#{alias_name} == nil or target.#{alias_name} > #{field.accessor}) then"
+            body << "  target.#{alias_name} = #{field.accessor}"
+            body << "end"
+          when :max
+            body << "if(target.#{alias_name} == nil or target.#{alias_name} < #{field.accessor}) then"
+            body << "  target.#{alias_name} = #{field.accessor}"
+            body << "end"
+          else
+            raise StandardError.new("Invalid aggregation type: #{field.aggregation_type}")
+          end
+        end
+        
+        # Indent body and return.
+        body.map! {|line| "  " + line}
+        return header + body.join("\n") + "\n" + footer
+      end
+
+      # Generates Lua code for the merge function.
+      def codegen_merge
+        header, body, footer = "function merge(results, data)\n", [], "end\n"
+
+        # Open group loops.
+        groups.each_with_index do |group, index|
+          data_item = "data" + (0...index).to_a.map {|i| "[k#{i}]"}.join('')
+          results_item = "results" + (0..index).to_a.map {|i| "[k#{i}]"}.join('')
+          body << "#{'  ' * index}for k#{index},v#{index} in pairs(#{data_item}) do"
+          body << "#{'  ' * index}  if #{results_item} == nil then #{results_item} = {} end"
+        end
+
+        indent = '  ' * groups.length
+        body << "#{indent}a = results" + (0...groups.length).to_a.map {|i| "[k#{i}]"}.join('')
+        body << "#{indent}b = data" + (0...groups.length).to_a.map {|i| "[k#{i}]"}.join('')
+
+        # Generate the merge for each field.
+        fields.each do |field|
+          alias_name = field.target_name
+          
+          case field.aggregation_type
+          when nil
+            body << "#{indent}a.#{alias_name} = b.#{alias_name}"
+          when :count
+            body << "#{indent}a.#{alias_name} = (a.#{alias_name} or 0) + (b.#{alias_name} or 0)"
+          when :sum
+            body << "#{indent}a.#{alias_name} = (a.#{alias_name} or 0) + (b.#{alias_name} or 0)"
+          when :min
+            body << "#{indent}if(a.#{alias_name} == nil or a.#{alias_name} > b.#{alias_name}) then"
+            body << "#{indent}  a.#{alias_name} = b.#{alias_name}"
+            body << "#{indent}end"
+          when :max
+            body << "#{indent}if(a.#{alias_name} == nil or a.#{alias_name} < b.#{alias_name}) then"
+            body << "#{indent}  a.#{alias_name} = b.#{alias_name}"
+            body << "#{indent}end"
+          else
+            raise StandardError.new("Invalid aggregation type: #{field.aggregation_type}")
+          end
+        end
+
+        # Close group loops.
+        groups.reverse.each_with_index do |group, index|
+          body << "#{'  ' * (groups.length-index-1)}end"
+        end
+
+        # Indent body and return.
+        body.map! {|line| "  " + line}
+        return header + body.join("\n") + "\n" + footer
+      end
+    end
+  end
+end
+