card 1.105.0 → 1.105.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c27e643a91315f8bfd6fc3fba7c744848203ba221637e03808a35f7d21869bec
-  data.tar.gz: 6792846d1b8853ab5681db115b60a5fdb0753771b90af28572b00208ef1a147d
+  metadata.gz: a96757584caadc22d04248602d0ebbb9185feef79f2e1e674cac585efc867154
+  data.tar.gz: de1483f559b35a2b6e3da653b8dc911b2b44245b94d7c7791c0e72d8d88bd4fa
 SHA512:
-  metadata.gz: 736423e17a671d1cdd5281fea9ba90ceaf6f37ab55bcbe52ac5ef8f0c91649a93d9e6e38d24fd841dba3966379162fdd55e0a3b71be7bab9fb7697c40fafef1b
-  data.tar.gz: 4e6de86094dfad8e899383d005bb78fa8d9a21d0e73f4d2799c49db683b8a08a37d711fb45be7325240fb77d0a284f9539206f35ccb107e29bdc6766fc1470d6
+  metadata.gz: 3a085f0940b3af5c235568a29bfebe0fa3295c610e17fd71303ccbc9bee14a124fe4bd36b8a170779518e3653b53a406ed41c71c5eace1cbc62d50a664afa183
+  data.tar.gz: 22c86dad3e3c21c5e7a40e18f2ed92ae712daa9f26ad0109d8b96b00412172cea7c735a0422c01b914b14bdcc8df77c34adb89b9744a448c51c1f992c4baaa7e

data/VERSION

@@ -1 +1 @@
-0.15.0
+0.15.2.pre1

data/lib/card/director/card_class.rb

@@ -16,35 +16,38 @@ class Card
 
       # The ensure methods are use to make sure a card exists and can be used when you're
       # unsure as to whether it already does. It's arguments are largely the same as
-      # those used by Card.create and @card.update with the important exception of
-      # `conflict`.
-
+      # those used by {#create Card#create} and {Director::All#update @card.update} with
+      # the important exception of `conflict`.
+      #
       # The conflict argument takes one of three values:
-      # - defer: let existing card stay as it is
-      # - default: update existing card if it is "pristine" (has not been edited by
-      #   anyone other than Decko Bot)
-      # - override: update existing card
-
+      #
+      #   - **defer**: let existing card stay as it is
+      #   - **default**: update existing card if it is "pristine" (meaning it has not
+      #     been edited by anyone other than Decko Bot)
+      #   - **override**: update existing card
+      #
       # If the options specify a codename and the name is already in use, things get a
       # little more involved. (Note: we MUST ensure that a card with the codename exists!)
-
-      # If the conflict setting is "defer":
+      #
+      # If the conflict setting is "**defer**":
       #
       #   - if the _codename_ is NOT already in use, we create a new card with an
       #     altered name
       #   - otherwise we do nothing.
       #
-      # If the conflict setting is "default":
+      # If the conflict setting is "**default**":
+      #
       #    - if the _codename_ is NOT already in use:
       #      - if the card using the name we want is pristine, we update that card
       #      - otherwise we create a new card with an altered name
-      #    - if the _codename IS already in use
+      #    - if the _codename_ IS already in use
       #      - if the card with the codename is pristine, we update everything but the
       #        name (which is used by another card)
       #      - otherwise we do nothing
       #
-      # If the conflict setting is "override":
-      #    - if the _codename is NOT already in use, we update the existing card with the
+      # If the conflict setting is "**override**":
+      #
+      #    - if the _codename_ is NOT already in use, we update the existing card with the
       #      name.
       #    - otherwise we alter the card withe the conflicting name and update the card
       #      with the codename.

data/lib/card/fetch/card_class.rb

@@ -1,29 +1,32 @@
 class Card
   class Fetch
-    # = Card#fetch
-    #
-    # A multipurpose retrieval operator that integrates caching, database lookups,
+    # A multipurpose retrieval system that integrates caching, database lookups,
     # and "virtual" card construction
     module CardClass
       # Look for cards in
-      # * cache
-      # * database
-      # * virtual cards
+      #   * cache
+      #   * database
+      #   * virtual cards
       #
       # @param args [Integer, String, Card::Name, Symbol, Array]
       #    Initials args must be one or more "marks," which uniquely idenfify cards:
+      #
+      #
       #      1. a name/key. (String or Card::Name)
       #      2. a numeric id. Can be (a) an Integer or (b) a String with an integer
       #         prefixed with a tilde, eg "~1234"
       #      3. a codename. Can be (a) a Symbol or (b) a String with a colon prefix,
       #         eg :mycodename
+      #
       #    If you pass more then one mark or an array of marks they get joined with a '+'.
       #    The final argument can be a Hash to set the following options
-      #      :skip_virtual               Real cards only
-      #      :skip_modules               Don't load Set modules
-      #      :look_in_trash              Return trashed card objects
-      #      :local_only                 Use only local cache for lookup and storing
-      #      new: { opts for Card#new }  Return a new card when not found
+      #
+      #        :skip_virtual               Real cards only
+      #        :skip_modules               Don't load Set modules
+      #        :look_in_trash              Return trashed card objects
+      #        :local_only                 Use only local cache for lookup and storing
+      #        new: { opts for Card#new }  Return a new card when not found
+      #
       # @return [Card]
       def fetch *args
         f = Fetch.new(*args)
@@ -32,9 +35,9 @@ class Card
         Card.new name: "card id out of range: #{f.mark}"
       end
 
-      # fetch only real (no virtual) cards
+      # a shortcut for fetch that returns only real cards (no virtuals)
       #
-      # @param mark - see #fetch
+      # @param mark [various] - see {#fetch}
       # @return [Card]
       def [] *mark
         fetch(*mark, skip_virtual: true)
@@ -62,6 +65,9 @@ class Card
       # ATTRIBUTE FETCHING
       # The following methods optimize fetching of specific attributes
 
+      # numerical card id
+      # @params cardish [various] interprets integers as id, symbols as codename, etc
+      # @return [Integer]
       def id cardish
         case cardish
         when Integer then cardish

data/lib/card/name.rb

@@ -5,10 +5,10 @@
 require "cardname"
 
 class Card
-  # The Cardname class provides generalized of Card naming patterns
-  # (compound names, key-based variants, etc)
+  # The {Cardname} class provides generalized of Card naming patterns (compound names,
+  # key-based variants, etc) and can be used independently of Card objects.
   #
-  # Card::Name adds support for deeper card integration
+  # {Card::Name} adds support for deeper integration with Card objects
   class Name < Cardname
     include NameVariants
 

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

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/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

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/registrar.rb

@@ -3,7 +3,7 @@
 class Card
   module Set
     # the set loading process has two main phases:
-
+    #
     #  1. Definition: interpret each set file, creating/defining set and
     #     set_format modules
     #  2. Organization: have base classes include modules associated with the
@@ -72,10 +72,8 @@ class Card
 
       # makes sets ready for dynamic loading via #include_set_modules
       def register_set_of_type set_module, set_type
-        mods = modules[set_type]
-        key = set_module.shortname
-        mods[key] ||= []
-        mods[key] << set_module
+        list = modules[set_type][set_module.shortname] ||= []
+        list << set_module unless list.member? set_module
       end
 
       def process_base_format_modules base_format_modules

data/lib/card/set/required_field.rb

@@ -18,11 +18,12 @@ class Card
       end
 
       def parent_event_name
-        [parent_set.underscore, "requires_field", field].join("__").to_sym
+        [parent_set.underscored_name, "requires_field", field].join("__").to_sym
       end
 
       def field_event_name action
-        [field, "required_by", parent_set.underscore, "on", action].join("__").to_sym
+        [field, "required_by", parent_set.underscored_name, "on", action]
+          .join("__").to_sym
       end
 
       private

data/lib/card/set/type.rb

@@ -1,5 +1,6 @@
 class Card
   module Set
+    # Base class for type sets defined in {Card::Set set modules}
     class Type < Pattern::Base
       cattr_accessor :assignment
       self.assignment = {}

data/lib/card/set.rb

@@ -1,7 +1,6 @@
 # -*- encoding : utf-8 -*-
 
 class Card
-  #
   # A _Set_ is a group of {Card Cards} to which _Rules_ may apply. Sets can be as
   # specific as a single card, as general as all cards, or anywhere in between.
   #
@@ -11,39 +10,86 @@ class Card
   # web interface and are thus documented at https://decko.org/rules.
   #  - **Code rules** can be defined in a 'set module'.
   #
-  # The {Cardio::Mod} docs explain how to create mods and set_modules. This page explains
-  # how those modules become useful.
+  # ## Set Modules
+  #
+  # ### File structure
+  #
+  # Set modules specify views, events, and other methods for a given set of cards.
+  # They are defined in a {Cardio::Mod mod's} _set_ directory. For example, suppose
+  # you've created a mod called *biz*, your deck has Company cards, and you want to
+  # extend the behavior of those cards.
+  #
+  # You can add a set module like so:
+  #
+  #       card generate set biz type company
+  #
+  # This will create the following two files:
+  #
+  #       mod/biz/set/type/company.rb
+  #       mod/biz/spec/set/type/company.rb
+  #
+  # If you would like to break this code into smaller files, you can extend this
+  # pattern into another directory, eg:
+  #
+  #       mod/biz/set/type/company/foo.rb
+  #       mod/biz/set/type/company/bar.rb
+  #
+  # The general pattern can be expressed as follows:
+  #
+  #       DECKNAME/mod/MODNAME/set/SET_PATTERN/ANCHOR[/FREENAME].rb
   #
-  # Suppose you have created a "mod" for managing your contacts called "contactmanager",
-  # and it includes code that would apply to all +address cards here:
+  # **Note:** _the set module's filename connects it to the set, so both the set_pattern
+  # and the set_anchor must correspond to the codename of a card in the database to
+  # function correctly. For example, the type/company directory corresponds to the Set
+  # card named `:company+:type`. Both the :company and :type codenames must exist for this
+  # to work properly._
+  #
+  # ### Writing/Editing set modules
+  #
+  #  A set module is mostly standard ruby, but the files are quite concise because
+  #
+  #   1. the set module's file location is used to autogenerate ruby module definitions
+  #   2. A DSL (Domain-Specific Language) makes common tasks easy.
+  #
+  # You can, for example, edit `mod/biz/set/type/company.rb`, and add _only_ the
+  # following code:
+  #
+  #     def hello
+  #       "world"
+  #     end
   #
-  #      ./contactmanager/set/right/address.rb
+  # No further code is needed for this method to be available to cards with the type
+  # Company (as specified by the file's location). This code will automatically be added
+  # to a ruby module named `Card::Set::Type::Company`. That module is extended with the
+  # {Card::Set} module, giving it access to the set module DSL.
   #
-  # Then, whenever you fetch or instantiate a +address card, the card will automatically
-  # include code from that set module.  In fact, it will include all the set modules
-  # associated with sets of which it is a member.
+  # These important Card::Set subclasses explain more about the DSL
+  #
+  #   - {Format} introduces format blocks
+  #   - {Format::AbstractFormat} covers {Format::AbstractFormat#view view} definitions
+  #   - {Event::Api} explains {Event::Api#event event} definitions
+  #
+  # ### Loading set modules
+  #
+  # Whenever you fetch or instantiate a card, the card will automatically
+  # include code from all the set modules associated with sets of which it is a member.
   #
   #  For example, say you have a Plaintext card named 'Philipp+address', and you have set
   # files for the following sets:
   #
-  #      * all cards
-  #      * all Plaintext cards
-  #      * all cards ending in +address
+  #   * all cards
+  #   * all Plaintext cards
+  #   * all cards ending in +address
   #
-  #  When you run this:
+  #  When you run any of these:
   #
-  #      mycard = Card.fetch 'Philipp+address'
+  #      mycard = Card.fetch "Philipp+address"
+  #      mycard = "Philipp+address".card
+  #      mycard = ["Philipp", "address"].card
   #
   #  ...then mycard will include the set modules associated with each of those sets in the
   # above order.
   #
-  #  Note that the set module's filename connects it to the set, so both the set_pattern
-  # and the set_anchor must correspond to the codename of a card in the database to
-  # function correctly.
-  #
-  #  A set module is "just ruby", but is generally quite concise because Card uses
-  #        a) the set module's file location to autogenerate ruby module names and
-  #        b) Card::Set to provide API for the most common set methods.
   #
   module Set
     include Event::Api