card 1.99.6 → 1.100.0

data/lib/card/query/card_query/normalization.rb

@@ -18,8 +18,8 @@ class Card
         def clause_to_hash clause
           case clause
           when Hash              then clause
-          when String            then { key: clause.to_name.key }
           when Integer           then { id: clause }
+          when String            then { id: (Card::Lexicon.id(clause) || -2) }
           when Symbol            then { id: Card::Codename.id(clause) }
           else raise Error::BadQuery, "Invalid clause: #{clause.inspect}"
           end
@@ -27,9 +27,9 @@ class Card
 
         def normalize_value val
           case val
-          when Integer, Float, Hash, Symbol then val
-          when String                       then normalize_string_value val
-          when Array                        then normalize_array_value val
+          when Integer, Float, Hash, Symbol, NilClass then val
+          when String                                 then normalize_string_value val
+          when Array                                  then normalize_array_value val
           else raise Error::BadQuery, "Invalid value type: #{val.class} (#{val.inspect})"
           end
         end

data/lib/card/query/card_query/run.rb

@@ -33,6 +33,7 @@ class Card
           when respond_to?(:"#{retrn}_result") then :"#{retrn}_result"
           when (retrn =~ /id$/)                then :id_result
           when (retrn =~ /_\w+/)               then :name_result
+          when (retrn == "key")                then :key_result
           else                                      :default_result
           end
         end
@@ -53,20 +54,26 @@ class Card
           record
         end
 
-        def name_result record, pattern
-          process_name record["name"], pattern
+        def key_result record, pattern=""
+          name_result(record, pattern).to_name.key
+        end
+
+        def name_result record, pattern=""
+          name = record["name"]&.to_name
+          name ||= Card::Lexicon.lex_to_name [record["left_id"], record["right_id"]]
+          process_name name, pattern
         end
 
         def card_result record, _field
           if alter_results?
-            Card.fetch alter_result(record["name"]), new: {}
+            Card.fetch name_result(record), new: {}
           else
             fetch_or_instantiate record
           end
         end
 
         def fetch_or_instantiate record
-          card = Card.retrieve_from_cache record["key"]
+          card = Card.retrieve_from_cache_by_id record["id"]
           unless card
             card = Card.instantiate record
             Card.write_to_cache card
@@ -76,11 +83,11 @@ class Card
         end
 
         def run_sql
-          # puts "\nstatement = #{@statement}"
-          ActiveRecord::Base.connection.select_all(sql)
+          # puts "\nSQL = #{sql}"
+          ActiveRecord::Base.connection.select_all sql
         end
 
-        def process_name name, pattern
+        def process_name name, pattern=""
           name = pattern.to_name.absolute(name) if pattern =~ /_\w+/
           return name unless alter_results?
 

data/lib/card/query/card_query/sorting.rb

@@ -47,7 +47,7 @@ class Card
 
         def sort_by_count val, item
           method_name = "sort_by_count_#{item}"
-          sort_by_count_not_implemented :count, item unless respond_to? method_name
+          sort_method_not_implemented :count, item unless respond_to? method_name
           send method_name, val
         end
 

data/lib/card/query/sql_statement.rb

@@ -69,17 +69,20 @@ class Card
 
       def full_field table, field
         case field
-        when :raw      then "#{table}.*"
-        when :card     then "#{table}.*"
-        when :content  then "#{table}.db_content"
-        when :count
-          "coalesce(count( distinct #{table}.id),0) as count"
+        when :card, :raw then "#{table}.*"
+        when :content    then "#{table}.db_content"
+        when :name, :key then "#{table}.name, #{table}.left_id, #{table}.right_id"
+        when :count      then "coalesce(count( distinct #{table}.id),0) as count"
         else
-          if ATTRIBUTES[field.to_sym] == :basic
-            "#{table}.#{field}"
-          else
-            safe_sql field
-          end
+          standard_full_field table, field
+        end
+      end
+
+      def standard_full_field table, field
+        if ATTRIBUTES[field.to_sym] == :basic
+          "#{table}.#{field}"
+        else
+          safe_sql field
         end
       end
 

data/lib/card/query/value.rb

@@ -1,7 +1,10 @@
 class Card
   module Query
+    # handling for CQL value clauses, eg [operator, value]
     class Value
       include Clause
+      include MatchValue
+
       SQL_FIELD = { name: "key", content: "db_content" }.freeze
 
       attr_reader :query, :operator, :value
@@ -12,18 +15,41 @@ class Card
         canonicalize_operator
       end
 
-      def parse_value rawvalue
-        case rawvalue
-        when String, Integer then ["=", rawvalue]
-        when Symbol          then ["=", rawvalue.to_s]
-        when Array           then parse_array_value rawvalue
-        else raise Error::BadQuery, "Invalid property value: #{rawvalue.inspect}"
+      def to_sql field
+        if @operator == "~"
+          match_sql field
+        else
+          standard_sql field
+        end
+      end
+
+      private
+
+      def standard_sql field
+        @value = Array.wrap(@value).map { |v| v.to_name.key } if field.to_sym == :name
+        "#{field_sql field} #{@operator} #{sqlize @value}"
+      end
+
+      def parse_value value
+        case value
+        when Array           then parse_array_value value.clone
+        when nil             then ["is", nil]
+        else                      ["=", parse_simple_value(value)]
         end
       end
 
       def parse_array_value array
         operator = operator?(array.first) ? array.shift : :in
-        [operator, array]
+        [operator, array.flatten.map { |i| parse_simple_value i }]
+      end
+
+      def parse_simple_value value
+        case value
+        when String, Integer then value
+        when Symbol          then value.to_s
+        when nil             then nil
+        else raise Error::BadQuery, "Invalid property value: #{value.inspect}"
+        end
       end
 
       def canonicalize_operator
@@ -40,33 +66,28 @@ class Card
 
       def sqlize v
         case v
-        when Query then  v.to_sql
-        when Array then  "(" + v.flatten.map { |x| sqlize(x) }.join(",") + ")"
+        when Query then v.to_sql
+        when Array then sqlize_array v
+        when nil   then "NULL"
         else quote(v.to_s)
         end
       end
 
-      def to_sql field
-        value = value_sql field, @value
-        "#{field_sql field} #{operational_sql value}"
-      end
-
-      def operational_sql value
-        if @operator == "~"
-          connection.match value
+      def sqlize_array array
+        array.flatten!
+        if array.size == 1 && !@operator.in?(["in", "not in"])
+          sqlize array.first
         else
-          "#{@operator} #{value}"
+          "(#{array.map { |x| sqlize(x) }.join(',')})"
         end
       end
 
       def field_sql field
-        db_field = SQL_FIELD[field.to_sym] || safe_sql(field.to_s)
-        "#{@query.table_alias}.#{db_field}"
+        "#{@query.table_alias}.#{standardize_field field}"
       end
 
-      def value_sql field, value
-        value = [value].flatten.map(&:to_name).map(&:key) if field.to_sym == :name
-        sqlize value
+      def standardize_field field
+        SQL_FIELD[field.to_sym] || safe_sql(field.to_s)
       end
     end
   end

data/lib/card/query/value/match_value.rb

@@ -0,0 +1,65 @@
+class Card
+  module Query
+    class Value
+      class << self
+        def match_prefices
+          @match_prefices ||= %w[= ~]
+        end
+
+        def match_term_and_prefix_re
+          @match_term_and_prefix_re ||=
+            /^(?<prefix>[#{Regexp.escape match_prefices.join}]*)\s*(?<term>.*)$/
+        end
+      end
+
+      # handling for match operator
+      module MatchValue
+        def match_sql field
+          exact_name_match(field) ||
+            "#{match_field field} #{connection.match match_value}"
+        end
+
+        def exact_name_match field
+          return false unless match_prefix == "=" && field.to_sym == :name
+          "#{field_sql field} = #{quote match_term.to_name.key}"
+        end
+
+        def match_field field
+          fld = field.to_sym == :name ? "name" : standardize_field(field)
+          "#{@query.table_alias}.#{fld}"
+        end
+
+        def match_value
+          escape_regexp_characters unless match_prefix == "~~"
+          quote match_term
+        end
+
+        def match_term
+          @match_term || (parse_match_term_and_prefix && @match_term)
+        end
+
+        def match_prefix
+          @match_prefix || (parse_match_term_and_prefix && @match_prefix)
+        end
+
+        # if search val is prefixed with "~~", it is a MYSQL regexp
+        # (and will be passed through)
+        #
+        # Otherwise, all non-alphanumeric characters are escaped.
+        #
+        # A "~" prefix is ignored.
+
+        def parse_match_term_and_prefix
+          raw_term = Array.wrap(@value).join(" ")
+          matches = raw_term.match self.class.match_term_and_prefix_re
+          @match_prefix = matches[:prefix] || ""
+          @match_term = matches[:term] || ""
+        end
+
+        def escape_regexp_characters
+          match_term.gsub!(/(\W)/, '\\\\\1')
+        end
+      end
+    end
+  end
+end

data/lib/card/set.rb

@@ -80,6 +80,6 @@ class Card
     # SET MODULE API
     #
     # The most important parts of the set module API are views (see
-    # Card::Set::Format) and events (see Card::Set::Event)
+    # Card::Set::Format) and events (see Card::Set::Event:Api)
   end
 end

data/lib/card/set/event.rb

@@ -1,35 +1,80 @@
 class Card
   module Set
-    # Events are the building blocks of the three transformative card actions: _create_,
-    # _update_, and _delete_.
-    #
-    # (The fourth kind of action, _read_, does not transform cards, and is associated
-    # with {Card::Format views}, not events).
-    #
-    # Whenever you create, update, or delete a card, the card goes through three phases:
-    #   * __validate__ makes sure all the data is in order
-    #   * __store__ puts the data in the database
-    #   * __integrate__ deals with any ramifications of those changes
-    #
-    # Events can be defined on each of these stages
-    #
+    # Supports the definition of events via the {Api Events API}
     class Event
+      # Events are the building blocks of the three transformative card actions: _create_,
+      # _update_, and _delete_.
+      #
+      # (The fourth kind of action, _read_, does not transform cards, and is associated
+      # with {Card::Format views}, not events).
+      #
+      # As described in detail in {Card::Director}, each act can have many actions, each
+      # action has three phases, each phase has three stages, and each stage has many
+      # events.
+      #
+      # Events are defined in set modules in {Card::Mod **mods**}. Learn more about
+      # {Card::Mod set modules}.
+      #
+      # A simple event definition looks something like this:
+      #
+      #     event :append_you_know, :prepare_to_validate, on: :create do
+      #       self.content = content + ", you know?"
+      #     end
+      #
+      # Note:
+      #
+      # - `:append_you_know` is a unique event name.
+      # - `:prepare_to_validate` is a {Card::Director stage}.
+      # - `on: :create` specifies the action to which the event applies
+      # - `self`, within the event card, is a card object.
+      #
+      # Any card within the {Card::Set set} on which this event is defined will
+      # run this event during the `prepare_to_validate` stage when it is created.
+      #
+      # Events are not format-specific and should not be defined within
+      # format blocks.
       module Api
+        OPTIONS = {
+          on: %i[create update delete save read],
+          changed: Card::Dirty.dirty_options,
+          changing: Card::Dirty.dirty_options,
+          skip: [:allowed],
+          trigger: [:required],
+          when: nil
+        }.freeze
+
+        # Define an event for a set of cards.
+        #
+        # @param event [Symbol] unique event name
+        # @param stage_or_opts [Symbol, Hash] if a Symbol, defines event's
+        #   {Card::Director stage}. If a Hash, it's treated as the opts param.
+        # @param opts [Hash] event options
+        # @option opts [Symbol, Array] :on one or more actions in which the event
+        #   should be executed. :save is shorthand for [:create, :update]. If no value
+        #   is specified, event will fire on create, update, and delete.
+        # @option opts [Symbol, Array] :changed fire event only if field has changed.
+        #   valid values: name, content, db_content, type, type_id, left_id, right_id,
+        #   codename, trash.
+        # @option opts [Symbol, Array] :changing alias for :changed
+        # @option opts [Symbol] :skip allow actions to skip this event.
+        #   (eg. `skip: :allowed`)
+        # @option opts [Symbol] :trigger allow actions to trigger this event
+        #   explicitly. If `trigger: :required`, then event will not run unless explicitly
+        #   triggered.
+        # @option opts [Symbol, Proc] :when method (Symbol) or code (Proc) to execute
+        #   to determine whether to fire event. Proc is given card as argument.
+        # @option opts [Symbol] :before fire this event before the event specified.
+        # @option opts [Symbol] :after fire this event after the event specified.
+        # @option opts [Symbol] :around fire this event before the event specified. This
+        #   event will receive a block and will need to call it for the specified
+        #   event to fire.
+        # @option opts [Symbol] :in alternate representation for specifying stage
         def event event, stage_or_opts={}, opts={}, &final
           Event.new(event, stage_or_opts, opts, self, &final).register
         end
       end
 
-      CONDITION_OPTIONS = {
-        on: %i[create update delete save read],
-        changed: %i[name content db_content type type_id codename key],
-        changing: %i[name content db_content type type_id codename key],
-        skip: :allowed,
-        trigger: :required  # the event is only executed if triggered explicitly with
-        # trigger: [event_name]
-      }.freeze
-
-      CONDITIONS = ::Set.new(%i[on changed changing when skip trigger]).freeze
+      CONDITIONS = ::Set.new(Api::OPTIONS.keys).freeze
 
       include DelayedEvent
       include Options
@@ -127,6 +172,6 @@ class Card
   def log_event_call event
     Rails.logger.debug "#{name}: #{event}"
     # puts "#{name}: #{event}"
-    # puts "#{Card::ActManager.to_s}".green
+    # puts "#{Card::Director.to_s}".green
   end
 end

data/lib/card/set/event/delayed_event.rb

@@ -51,7 +51,7 @@ class Card
           def perform act_id, card, card_attribs, env, auth, method_name
             handle_perform do
               load_card card, card_attribs
-              ActManager.contextualize_delayed_event act_id, card, env, auth do
+              Director.contextualize_delayed_event act_id, card, env, auth do
                 card.send method_name
               end
             end
@@ -63,7 +63,7 @@ class Card
             Card::Error.report error, @card
             raise error
           ensure
-            ActManager.expire
+            Director.expire
           end
 
           def load_card card, card_attribs
@@ -90,7 +90,7 @@ class Card
   end
 
   def perform_delayed_job_args event
-    [Card::ActManager.act&.id,
+    [Card::Director.act&.id,
      self,
      serialize_for_active_job,
      Card::Env.serialize,

data/lib/card/set/event/options.rb

@@ -12,18 +12,18 @@ class Card
         end
 
         def validate_condition_name condition
-          return if Card::Set::Event::CONDITIONS.include? condition
+          return if CONDITIONS.include? condition
 
           raise ArgumentError,
                 "invalid condition key '#{condition}' in event '#{@event}'\n" \
-                "valid conditions are #{Card::Set::Event::CONDITIONS.to_a.join ', '}"
+                "valid conditions are #{CONDITIONS.to_a.join ', '}"
         end
 
         def validate_condition_value condition, val
           if condition == :when
             validate_when_value val
           else
-            invalid = Array.wrap(val) - Array.wrap(valid_values(condition))
+            invalid = Array.wrap(val) - Api::OPTIONS[condition]
             return if invalid.empty?
 
             raise ArgumentError,
@@ -40,10 +40,6 @@ class Card
                 "must be a symbol or a proc"
         end
 
-        def valid_values condition
-          Card::Set::Event::CONDITION_OPTIONS[condition]
-        end
-
         def event_opts stage_or_opts, opts
           opts = normalize_opts stage_or_opts, opts
           process_stage_opts opts