card 1.104.2 → 1.105.1

data/lib/card/query/sql_statement/where.rb

@@ -3,10 +3,10 @@ class Card
     class SqlStatement
       # handle where clause in SqlStatement
       module Where
-        def where
+        def where explicit=true
           conditions = [explicit_conditions(@query), implicit_conditions(@query)]
           conditions = conditions.reject(&:blank?).join " AND "
-          "WHERE #{conditions}" unless conditions.blank?
+          "#{'WHERE ' if explicit}#{conditions}" unless conditions.blank?
         end
 
         # conditions explicitly specified in the query object

data/lib/card/query.rb

@@ -7,8 +7,8 @@ class Card
   # frequently used directly in code.
   #
   # Query "statements" (objects, really) are made in CQL (Card Query
-  # Language). Because CQL is used by Sharks, the primary language
-  # documentation is on decko.org. (https://decko.org/CQL_Syntax). Note that the
+  # Language). Because CQL is used by Sharks, [the primary CQL Syntax documentation is
+  # on decko.org](https://decko.org/CQL_Syntax). Note that the
   # examples there are in JSON, like Search card content, but statements in
   # Card::Query are in ruby form.
   #
@@ -17,9 +17,11 @@ class Card
   # CQL statement interpretation.
   #
   # The most common way to use Card::Query is as follows:
+  #
   #     list_of_cards = Card::Query.run(statement)
   #
   # This is equivalent to:
+  #
   #     query = Card::Query.new(statement)
   #     list_of_cards = query.run
   #
@@ -32,7 +34,8 @@ class Card
   # - @subqueries - a list of other queries nested within this one
   #
   # Each condition is either a SQL-ready string (boo) or an Array in this form:
-  #    [ field_string_or_sym, Card::Value::Query object ]
+  #
+  #     [field_string_or_sym, (Card::Value::Query object)]
   module Query
     require "card/query/clause"
     require "card/query/card_query"
@@ -48,8 +51,8 @@ class Card
       # their values are translated fairly directly into SQL-safe values.
       # (These are referred to as "properties" in CQL documentation. Need to
       # reconcile #EFM)
-      basic: %i[id name key type_id content left_id right_id
-                creator_id updater_id codename read_rule_id],
+      basic: %i[id name key type_id content left_id right_id codename read_rule_id
+                created_at updated_at creator_id updater_id ],
       # "Relational" values can involve tying multiple queries together
       relational: %i[type
                      part left right
@@ -68,6 +71,7 @@ class Card
 
       plus_relational: %i[plus left_plus right_plus],
       conjunction: %i[and or all any],
+      custom: [:compound],
       ignore: %i[prepend append vars],
       deprecated: %i[view params size]
     }.each_with_object({}) do |pair, h|
@@ -76,7 +80,10 @@ class Card
 
     CONJUNCTIONS = { any: :or, in: :or, or: :or, all: :and, and: :and }.freeze
 
-    MODIFIERS = %i[conj return sort sort_as group dir limit offset]
+    # "dir" is DEPRECATED in favor of sort_dir
+    # "sort" is DEPRECATED in favor of sort_by, except in cases where sort's value
+    # is a hash
+    MODIFIERS = %i[conj return sort_by sort_as sort_dir sort dir group limit offset]
                 .each_with_object({}) { |v, h| h[v] = nil }
 
     OPERATORS =

data/lib/card/reference/all.rb

@@ -73,16 +73,6 @@ class Card
 
       private
 
-      def with_normalized_referee referee_name
-        return unless referee_name # eg commented nest has no referee_name
-
-        referee_name = referee_name.to_name
-        referee_key = referee_name.key
-        return if referee_key == key # don't create self reference
-
-        yield referee_name, referee_key, Lexicon.id(referee_name)
-      end
-
       # interpretation phase helps to prevent duplicate references
       # results in hash like:
       # { referee1_key: [referee1_id, referee1_type2],
@@ -96,6 +86,16 @@ class Card
         end
       end
 
+      def with_normalized_referee referee_name
+        return unless referee_name # eg commented nest has no referee_name
+
+        referee_name = referee_name.to_name
+        referee_key = referee_name.key
+        return if referee_key == key # don't create self reference
+
+        yield referee_name, referee_key, Lexicon.id(referee_name)
+      end
+
       # translate interpreted reference hash into values array,
       # removing duplicate and unnecessary ref_types
       def reference_values_array ref_hash

data/lib/card/set/abstract.rb

@@ -1,5 +1,6 @@
 class Card
   module Set
+    # Base class for abstract sets defined in {Card::Set set modules}
     class Abstract < Pattern::Base
     end
   end

data/lib/card/set/advanced_api.rb

@@ -4,7 +4,7 @@ class Card
     module AdvancedApi
       def assign_type type, module_key=nil
         module_key ||= shortname
-        Type.assignment[module_key] = type.card_id
+        Type.assignment[module_key] = type
       end
 
       def setting_opts opts

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

@@ -1,8 +1,16 @@
 class Card
   module Set
     class Event
-      # card methods for testing event applicability
+      # card methods for scheduling events and testing event applicability
       module All
+        def schedule event
+          @scheduled ||= {}
+          return if @scheduled[event.to_sym]
+
+          send :"#{event}_with_delay"
+          @scheduled[event.to_sym] = true
+        end
+
         include SkipAndTrigger
 
         def event_applies? event

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

@@ -8,7 +8,8 @@ class Card
   # needed, then we clearly need to make sure that they are fully restored. At a bare
   # minimum they would need to include set modules.
   def serializable_attributes
-    self.class.action_specific_attributes + set_specific.keys - %i[supercard superleft]
+    self.class.action_specific_attributes + set_specific.keys -
+      %i[supercard superleft subcards]
   end
 
   module Set
@@ -28,7 +29,8 @@ class Card
         end
 
         def with_delay? opts
-          DELAY_STAGES.include?(opts[:after]) || DELAY_STAGES.include?(opts[:before])
+          opts.delete(:delay) ||
+            DELAY_STAGES.intersect?([opts[:after], opts[:before]].to_set)
         end
 
         def define_delayed_event_method

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

@@ -4,7 +4,7 @@ class Card
       module Options
         def validate_conditions
           @opts.each do |key, val|
-            next if key.in? %i[stage before after around]
+            next if key.in? %i[stage before after around delay]
 
             validate_condition_name key
             validate_condition_value key, val

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

@@ -3,6 +3,37 @@ class Card
     class Event
       # opt into (trigger) or out of (skip) events
       module SkipAndTrigger
+        settings = [
+          :skip,                        # [Array] skip event(s) for all cards in act
+          :skip_in_action,              # [Array] skip event for just this card
+          :trigger,                     # [Array] trigger event(s) for all cards in act
+          :trigger_in_action,           # [Array] trigger event for just this card
+        ]
+        attr_reader(*settings)
+
+        Card.action_specific_attributes +=
+          settings + %i[skip_hash full_skip_hash trigger_hash full_trigger_hash]
+
+        def skip= skip_val
+          @skip_hash = @full_skip_hash = nil
+          @skip = skip_val
+        end
+
+        def skip_in_action= skip_val
+          @skip_hash = @full_skip_hash = nil
+          @skip_in_action = skip_val
+        end
+
+        def trigger= trigger_val
+          @trigger_hash = @full_trigger_hash = nil
+          @trigger = trigger_val
+        end
+
+        def trigger_in_action= trigger_val
+          @trigger_hash = @full_trigger_hash = nil
+          @trigger_in_action = trigger_val
+        end
+
         # force skipping this event for all cards in act
         def skip_event! *events
           @full_skip_hash = nil
@@ -59,23 +90,16 @@ class Card
         end
 
         def full_skip_hash
-          @full_skip_hash ||= act_skip_hash.merge skip_in_action_hash
+          @full_skip_hash ||= act_skip_hash.merge hash_with_value(skip_in_action, true)
         end
 
         def act_skip_hash
           (act_card || self).skip_hash
         end
 
-        def skip_in_action_hash
-          hash_with_value skip_in_action, true
-        end
-
         def full_trigger_hash
-          @full_trigger_hash ||= act_trigger_hash.merge trigger_in_action_hash
-        end
-
-        def trigger_in_action_hash
-          hash_with_value trigger_in_action, true
+          @full_trigger_hash ||=
+            act_trigger_hash.merge hash_with_value(trigger_in_action, true)
         end
 
         def act_trigger_hash

data/lib/card/set/format/abstract_format/haml_views.rb

@@ -10,15 +10,15 @@ class Card
         #   # mod/core/set/type/basic.rb
         #   view :my_view, template: :haml  # uses mod/core/view/type/basic/my_view.haml
         #
-        #   view :with_instance_variables, template: :haml do
+        #   view :sample_view, template: :haml do
         #     @actor = "Mark Haml"
         #   end
         #
-        #   # mod/core/view/type/basic/with_instance_variables.haml
+        #   # mod/core/set/type/basic/sample_view.haml
         #   Luke is played by
         #     = actor
         #
-        #   > render :with_instance_variables  # => "Luke is played by Mark Haml"
+        #   > render :sample_view  # => "Luke is played by Mark Haml"
         module HamlViews
           include Card::Set::Format::HamlPaths
 

data/lib/card/set/format/abstract_format/wrapper.rb

@@ -1,7 +1,6 @@
 class Card
   module Set
     module Format
-      # AbstractFormat extends all format classes
       module AbstractFormat
         # The Wrapper module provides an API to define wrap methods.
         # It is available in all formats.

data/lib/card/set/format/abstract_format.rb

@@ -3,9 +3,10 @@
 class Card
   module Set
     module Format
-      # AbstractFormat manages the basic format API, including API to define a {#view}.
-      # Whenever you create a format block in a set module in a {Cardio::Mod mod}, you
-      # create a format module that is extended with AbstractFormat.
+      # AbstractFormat manages the DSL for defining {#view views}.
+      #
+      # Whenever you create a {Format format} block in a {Cardio::Set set module},
+      # you create a format module that is extended with AbstractFormat.
       module AbstractFormat
         include ViewOpts
         include ViewDefinition
@@ -59,7 +60,7 @@ class Card
         #     * *:create*, *:read* (default), *:update*, *:delete* - only users with the
         #       given permission for the card viewed.
         #     * *:none* - no permission check; anyone can view
-        #     * a *Proc* object.  Eg `perms: ->(_fmt) { Auth.needs_setup? }`
+        #     * a format method name.  Eg `perms: :is_my_view_ok?`
         #
         # * __:template__ [Symbol] view is defined in a template. Currently `:haml` is
         #   the only supported value.  See {HamlViews}

data/lib/card/set/format/haml_paths.rb

@@ -3,9 +3,6 @@ class Card
     module Format
       # methods for handling paths to HAML templates
       module HamlPaths
-        CORE_MODS = ::Set.new %w[core admin].freeze
-        TEMPLATE_DIR = %w[template set].freeze
-
         delegate :tmp_files?, to: Cardio::Mod::LoadStrategy
 
         def haml_to_html haml, locals={}, a_binding=nil, debug_info={}
@@ -49,34 +46,21 @@ class Card
           end
         end
 
-        TMPSET_REGEXP = %r{(?<carddir>/card)/tmp(sets)?/set/mod\d{3}-(?<modname>[^/]+)/}
+        TMPSET_REGEXP = %r{^.*/tmp(sets)?/set/[\w-]+/mod\d{3}-(?<modname>[^/]+)}
 
         def deep_source source
           return source unless tmp_files?
 
-          source&.gsub TMPSET_REGEXP do
-            match = Regexp.last_match
-            source_mod_dir match[:modname], match[:carddir]
+          source&.sub TMPSET_REGEXP do
+            "#{Cardio::Mod.fetch(Regexp.last_match[:modname]).path}/set"
           end
         end
 
-        def source_mod_dir modname, carddir
-          # TODO: handle non-standard mod dirs
-          dir = "/mod/#{modname}/set/"
-          return dir unless modname.in? CORE_MODS
-
-          "#{carddir}/#{dir}/"
-        end
-
         def try_haml_template_path template_path, view, source_dir, ext="haml"
           template_path = File.join(template_path, view.to_s) if view.present?
           template_path += ".#{ext}"
-          TEMPLATE_DIR.each do |template_dir|
-            path = ::File.expand_path(template_path, source_dir)
-                         .sub(%r{(/mod/[^/]+)/set/}, "\\1/#{template_dir}/")
-            return path if ::File.exist?(path)
-          end
-          false
+          path = ::File.expand_path(template_path, source_dir)
+          path if ::File.exist? path
         end
 
         def haml_block_locals &block

data/lib/card/set/format.rb

@@ -2,33 +2,58 @@
 
 class Card
   module Set
-    # This document explains how to use format blocks within {Cardio::Mod mods}. To make
-    # use of it, you will need to understand both {Cardio::Mod mods} and {Card::Set sets}.
+    # Card::Set::Format is responsible for handling `format` blocks within the set module
+    # DSL, which is used in {Cardio::Mod Set module} files found in {Cardio::Mod mods'}
+    # set directories. Monkeys use the DSL to define views that apply to specific sets of
+    # cards in specific formats. The views can then be
+    # used by Monkeys in code and by Sharks via the UI.
     #
-    # Within a card mod, you can define format blocks like the following:
+    # For example, imagine you have a set module file in `mod/mymod/type/my_type.rb`.
+    # There you can define a view like this:
     #
     #     format :html do
-    #       def beethoven
+    #       view :hello do
+    #         greeting
+    #       end
+    #     end
+    #
+    # {AbstractFormat#view Learn more about defining views}
+    #
+    # This view will now be available to MyType cards in HTML -- but not in other formats.
+    # Similarly, you can define other methods in format blocks:
+    #
+    #     format :html do
+    #       def greeting
     #         :rocks
     #       end
     #     end
     #
-    # The magic that happens here is that the method #beethoven is now applicable (and
-    # available) _only_ to the cards in the set specified by the mod, and only when
-    # the card is rendering a view in the HTML format.
+    # The magic that happens here is that the method #greeting is now applicable (and
+    # available) _only_ to the cards in the {Card::Set set} specified by the mod, and
+    # only when rendering a view of the card in the HTML format. {Card::Format Learn
+    # more about formats}.
     #
-    # If you care, you can certainly learn about how all this works. How the set module
-    # creates a module that looks something like `Card::Set::Type::MyType::HtmlFormat`.
-    # How the format object for a given card in the set includes this module dynamically
-    # when it's initialized. And so on...
+    # So if, for example, I had a card "MyCard" with the type "MyType", the following
+    # should use the method above:
     #
-    # But as monkeys, we don't usually think about all that much, because we work in
+    # ````
+    # "MyCard".card.format(:html).greeting
+    # ````
+    #
+    # ...but if the card had a different type, or if I tried to use the method in, say,
+    # the JSON format, this #beethoven method wouldn't be available.
+    #
+    # Under the hood, the DSL creates a ruby module that looks something like
+    # `Card::Set::Type::MyType::HtmlFormat`. This module will then be dynamically included
+    # in HTML format objects for MyCard.
+    #
+    # As monkeys, we don't usually think about all that much, because we work in
     # the set module space, which lets us focus on the card patterns.
     #
     # Speaking of which, there are a few key patterns to be aware of:
     #
     # 1. Just as in {Card::Set sets}, format methods for narrower sets will override
-    #    format methods for more general sets.  So if a #beethoven method is defined
+    #    format methods for more general sets.  So if a #greeting method is defined
     #    for all cards and again for a specific card type, then the type method will
     #    override the all method when both apply.
     # 2. Similarly, specific formats inherit from more general formats, and all formats
@@ -36,27 +61,28 @@ class Card
     #    will define methods on the base format class.
     #
     #         format do
-    #           def haydn
-    #             :sucks
+    #           def farewell
+    #             "goodbye"
     #           end
     #         end
     #
     # 3. It is possible to use super to refer to overridden methods.  For example
     #
     #         format :html do
-    #           def haydn
+    #           def goodbye
     #             "<em>#{super}</em>"
     #           end
     #         end
     #
     #     Note: Set precedence has a higher priority than Format precedence.
     #
-    # 4. {#view} and {#before} can both be called outside of a format block. They will
-    #   be defined on the base format.
-    #
-    # 5. Some very powerful API calls (including {AbstractFormat#view view} and
+    # 4. Some very powerful API calls (including {AbstractFormat#view view} and
     # {AbstractFormat#before before}) are defined in {AbstractFormat}. These methods are
     # always available in format blocks.
+    #
+    # 5. {#view} and {#before}, however, can ALSO both be called outside of a format
+    # block. They will be defined on the base format.
+    #
     module Format
       require "card/set/format/haml_paths"
       require "card/set/format/abstract_format"

data/lib/card/set/helpers.rb

@@ -1,42 +1,32 @@
 class Card
   module Set
+    # These helper methods provide easy access to metadata, such as information about
+    # the set modified by a module. These methods are seldom used by Monkeys; they are
+    # primarily Platypus tools.
     module Helpers
       SET_PATTERN_TEST_REGEXP = /^(?<pattern>\w+)_set\?$/
 
+      # @return [String] short name of card module. For example, returns Type::User for
+      # Card::Set::Type::User
       def shortname
         first = 2 # shortname eliminates Card::Set
         last = first + num_set_parts(pattern_code)
         set_name_parts[first..last].join "::"
       end
 
-      def underscore
+      # @return [String] name of card module with underscores. For example, returns
+      # Card__Set__Type__User for Card::Set::Type::User
+      def underscored_name
         shortname.tr(":", "_").underscore
       end
 
-      def num_set_parts pattern_code
-        return 1 if pattern_code == :abstract
-
-        Pattern.find(pattern_code).anchor_parts_count
-      end
-
-      def set_format_type_key
-        @set_format_type_key ||= :"#{set_type_key}_format"
-      end
-
-      def set_type_key
-        if all_set?
-          :base
-        elsif abstract_set?
-          :abstract
-        else
-          :nonbase
-        end
-      end
-
+      # @return [Array] list of strings of parts of set module's name
+      # Eg, returns ["Card", "Set", "Type", "User"] for Card::Set::Type::User
       def set_name_parts
         @set_name_parts ||= name.split "::"
       end
 
+      # @return [Symbol] codename associated with set's pattern. Eg :type, :right, etc
       def pattern_code
         @pattern_code ||= set_name_parts[2].underscore.to_sym
       end
@@ -50,6 +40,8 @@ class Card
         end
       end
 
+      # @return [true/false]
+      # handles all_set?, abstract_set?, type_set?, etc.
       def respond_to_missing? method_name, _include_private=false
         method_name.match? SET_PATTERN_TEST_REGEXP
       end
@@ -64,21 +56,6 @@ class Card
         end
       end
 
-      def test_set
-        # rubocop:disable Lint/Eval
-        ::Card::Set::Self.const_remove_if_defined :TestSet
-        eval <<-RUBY, binding, __FILE__, __LINE__ + 1
-          class ::Card::Set::Self
-            module TestSet
-              extend Card::Set
-              include_set #{name}
-            end
-          end
-        RUBY
-        ::Card::Set::Self::TestSet
-        # rubocop:enable Lint/Eval
-      end
-
       def format_modules format_sym, test: true
         if base_format_modules?
           [format_module(format_sym)]
@@ -95,6 +72,36 @@ class Card
 
       private
 
+      # @return [Symbol] base_format,
+      def set_format_type_key
+        @set_format_type_key ||= :"#{set_type_key}_format"
+      end
+
+      def set_type_key
+        if all_set?
+          :base
+        elsif abstract_set?
+          :abstract
+        else
+          :nonbase
+        end
+      end
+
+      def test_set
+        # rubocop:disable Lint/Eval
+        ::Card::Set::Self.const_remove_if_defined :TestSet
+        eval <<-RUBY, binding, __FILE__, __LINE__ + 1
+          class ::Card::Set::Self
+            module TestSet
+              extend Card::Set
+              include_set #{name}
+            end
+          end
+        RUBY
+        ::Card::Set::Self::TestSet
+        # rubocop:enable Lint/Eval
+      end
+
       def base_format_modules?
         !set_format_type_key || set_format_type_key == :base_format
       end
@@ -107,6 +114,12 @@ class Card
         format_class = Card::Format.format_class format: format_sym
         Card::Set.modules[set_format_type_key][format_class][shortname] || []
       end
+
+      def num_set_parts pattern_code
+        return 1 if pattern_code == :abstract
+
+        Pattern.find(pattern_code).anchor_parts_count
+      end
     end
   end
 end

data/lib/card/set/inheritance.rb

@@ -3,8 +3,8 @@ class Card
     # API to inherit other sets and their formats
     module Inheritance
       # include a set module and all its format modules
-      # @param [Module] set
-      # @param [Hash] opts choose the formats you want to include. You can also
+      # @param set [Module]
+      # @param opts [Hash] choose the formats you want to include. You can also
       #    pass arbitrary options to the included set. The option is saved
       #    in the including set. To use the option you need a `included` method
       #    in the included set to fetch the option.
@@ -41,8 +41,8 @@ class Card
       end
 
       # include format modules of a set
-      # @param [Module] set
-      # @param [Hash] opts choose the formats you want to include
+      # @param set [Module]
+      # @param opts [Hash] choose the formats you want to include
       # @option opts [Symbol, Array<Symbol>] :only include only these formats
       # @option opts [Symbol, Array<Symbol>] :except don't include these formats
       # @example

data/lib/card/set/pattern/all.rb

@@ -21,7 +21,7 @@ class Card
           @patterns = @concrete_patterns = nil
           @template = @virtual = nil
           @set_mods_loaded = @set_modules = @set_names = @rule_lookup_keys = nil
-          @junction_only = nil # only applies to set cards
+          @compound_only = nil # only applies to set cards
           true
         end
 

data/lib/card/set/pattern/base.rb

@@ -39,7 +39,7 @@ class Card
 
         def anchor_codenames
           anchor_parts.map do |part|
-            part.cardname&.code || break
+            part.cardname&.codename || break
           end
         end
 

data/lib/card/set/pattern/class_methods.rb

@@ -3,7 +3,7 @@ class Card
     module Pattern
       # methods for Set::Pattern classes
       module ClassMethods
-        attr_accessor :pattern_code, :junction_only, :assigns_type, :anchorless
+        attr_accessor :pattern_code, :compound_only, :assigns_type, :anchorless
         attr_writer :anchor_parts_count
 
         def new card
@@ -17,8 +17,8 @@ class Card
           opts.each { |key, val| send "#{key}=", val }
         end
 
-        def junction_only?
-          junction_only == true
+        def compound_only?
+          compound_only == true
         end
 
         def anchorless?
@@ -35,7 +35,7 @@ class Card
         end
 
         def pattern_applies? card
-          junction_only? ? card.name.compound? : true
+          compound_only? ? card.name.compound? : true
         end
 
         def anchor_parts_count