card 1.99.6 → 1.100.0

data/db/seed/test/fixtures/schema_migrations.yml

@@ -59,3 +59,7 @@ schema_migrations_029:
   version: '20190131223248'
 schema_migrations_030:
   version: '20190929202325'
+schema_migrations_031:
+  version: '20200718051236'
+schema_migrations_032:
+  version: '20200805200729'

data/db/seeds.rb

@@ -1,3 +1,4 @@
 require "card/seed_consts"
 require "active_record/fixtures"
 ActiveRecord::FixtureSet.create_fixtures CARD_SEED_PATH, CARD_SEED_TABLES
+Card::Mod::Loader.load_mods

data/db/test_seed.rb

@@ -252,7 +252,7 @@ class SharedData
 
         Card::Auth.signin Card::WagnBotID
         create "Google glass+*self+*follow_fields", ""
-        create "Sunglasses+*self+*follow_fields", "[[#{Card[:nests].name}]]\n[[_self+price]]\n[[_self+producer]]"
+        create "Sunglasses+*self+*follow_fields", "[[#{:nests.cardname}]]\n[[_self+price]]\n[[_self+producer]]"
         create "Sunglasses+tint"
         create "Sunglasses+price"
 

data/db/version.txt

@@ -1 +1 @@
-20190929202325
+20200805200729

data/lib/card.rb

@@ -4,7 +4,7 @@ ActiveSupport.run_load_hooks(:before_card, self)
 
 # Cards are wiki-inspired building blocks.
 #
-# This documentation is intended for developers who want to understand:
+# This documentation is for developers who want to understand:
 #
 #   1. how ruby Card objects work, and
 #   2. how to extend them.
@@ -82,7 +82,7 @@ ActiveSupport.run_load_hooks(:before_card, self)
 #
 # {Card::Set::Format::AbstractFormat More on views}
 #
-# {Card::Set::Event More on events}
+# {Card::Set::Event::Api More on events}
 #
 # ## Accounts and Permissions
 #
@@ -92,9 +92,11 @@ ActiveSupport.run_load_hooks(:before_card, self)
 #
 # {Card::Auth More on accounts}
 class Card < ApplicationRecord
-  extend ::Card::Mark
-  extend ::Card::Dirty::MethodFactory
-  include ::Card::Dirty
+  extend Mark
+  extend Dirty::MethodFactory
+  include Dirty
+  include DirtyNames
+  include Director::CardMethods
 
   Card::Cache # trigger autoload
 
@@ -108,12 +110,11 @@ class Card < ApplicationRecord
 
   self.set_patterns = []
   self.action_specific_attributes = [
-    :action, :supercard, :superleft,
+    :supercard,
+    :superleft,
+    :action,
     :current_action,
-
     :last_action_id_before_edit,
-    :only_storage_phase,          # used to save subcards
-    :changed_attributes,
 
     :skip,                        # skip event(s) for all cards in act
     :skip_in_action,              # skip event for just this card
@@ -129,32 +130,9 @@ class Card < ApplicationRecord
   ]
 
   attr_accessor(*action_specific_attributes)
-  attr_accessor :follower_stash
-
-  STAGE_CALLBACKS = [
-    :select_action, :show_page, :act,
-    # VALIDATION PHASE
-    :initialize_stage, :prepare_to_validate_stage, :validate_stage,
-    :initialize_final_stage, :prepare_to_validate_final_stage,
-    :validate_final_stage,
-    # STORAGE PHASE
-    :prepare_to_store_stage, :store_stage, :finalize_stage,
-    :prepare_to_store_final_stage, :store_final_stage, :finalize_final_stage,
-    # INTEGRATION PHASE
-    :integrate_stage, :integrate_with_delay_stage,
-    :integrate_final_stage,
-    :after_integrate_stage,
-    :after_integrate_final_stage, :integrate_with_delay_final_stage
-  ].freeze
-  define_callbacks(*STAGE_CALLBACKS)
 
-  # Validation and integration phase are only called for the act card
-  # The act card starts those phases for all its subcards
-  before_validation :validation_phase, unless: -> { only_storage_phase? }
-  around_save :storage_phase
-  after_commit :integration_phase, unless: -> { only_storage_phase? }
-  #  after_rollback :clean_up, unless: -> { only_storage_phase? }
+  define_callbacks :select_action, :show_page, :act
 
-  ActiveSupport.run_load_hooks(:card, self)
+  ActiveSupport.run_load_hooks :card, self
 end
 ActiveSupport.run_load_hooks :after_card, self

data/lib/card/auth/current.rb

@@ -106,7 +106,7 @@ class Card
       end
 
       # find +\*account card by +\*api card
-      # @param token [String]
+      # @param api_key [String]
       # @return [+*account card, nil]
       def find_account_by_api_key api_key
         find_account_by :api_key, api_key.strip

data/lib/card/auth/permissions.rb

@@ -6,17 +6,18 @@ class Card
       # @return [true/false]
       def always_ok?
         usr_id = as_id
-        return false unless usr_id
-
-        always_ok_usr_id? usr_id
+        case usr_id
+        when Card::WagnBotID then true # cannot disable
+        when nil             then false
+        else
+          always_ok_usr_id? usr_id
+        end
       end
 
       # specified user has root permission
       # @param usr_id [Integer]
       # @return [true/false]
       def always_ok_usr_id? usr_id, force_cache_update=false
-        return true if usr_id == Card::WagnBotID # cannot disable
-
         always = always_cache
         if always[usr_id].nil? || force_cache_update
           update_always_cache usr_id, admin?(usr_id)

data/lib/card/cache/prepopulate.rb

@@ -17,15 +17,18 @@ class Card
         return unless prepopulate?
 
         prepopulate_rule_caches
-        # prepopulate_card_cache
+        # prepopulate_lexicon_caches
       end
 
       def prepopulate_cache variable
         @prepopulated ||= {}
         value = @prepopulated[variable] ||= yield
-        Card.cache.soft.write variable, value
+        Card.cache.soft.write variable, value.clone
       end
 
+      # def prepopulate_lexicon_caches
+      # end
+
       def prepopulate_rule_caches
         prepopulate_cache("RULES") { Card::Rule.rule_cache }
         prepopulate_cache("READRULES") { Card::Rule.read_rule_cache }

data/lib/card/content/clean.rb

@@ -32,32 +32,38 @@ class Card
 
       ATTR_VALUE_RE = [/(?<=^')[^']+(?=')/, /(?<=^")[^"]+(?=")/, /\S+/].freeze
 
+      def clean! string, tags=ALLOWED_TAGS
+        cleaned = clean_tags string, tags
+        cleaned = clean_spaces cleaned if Cardio.config.space_last_in_multispace
+        cleaned
+      end
+
+      private
+
       ## Method that cleans the String of HTML tags
       ## and attributes outside of the allowed list.
-      def clean! string, tags=ALLOWED_TAGS
+      def clean_tags string, ok_tags
         # $LAST_MATCH_INFO is nil if string is a SafeBuffer
-        string.to_str.gsub(%r{<(/*)(\w+)([^>]*)>}) do |raw|
-          raw = $LAST_MATCH_INFO
-          tag = raw[2].downcase
-          if (attrs = tags[tag])
-            html_attribs =
-              attrs.each_with_object([tag]) do |attr, pcs|
-                q, rest_value = process_attribute attr, raw[3]
-                pcs << "#{attr}=#{q}#{rest_value}#{q}" unless rest_value.blank?
-              end * " "
-            "<#{raw[1]}#{html_attribs}>"
-          else
-            " "
-          end
+        string.to_str.gsub(%r{<(/*)(\w+)([^>]*)>}) do |_raw|
+          clean_tag $LAST_MATCH_INFO, ok_tags
         end.gsub(/<\!--.*?-->/, "")
       end
 
-      if Cardio.config.space_last_in_multispace
-        def clean_with_space_last! string, tags=ALLOWED_TAGS
-          cwo = clean_without_space_last!(string, tags)
-          cwo.gsub(/(?:^|\b) ((?:&nbsp;)+)/, '\1 ')
-        end
-        alias_method_chain :clean!, :space_last
+      def clean_spaces string
+        string.gsub(/(?:^|\b) ((?:&nbsp;)+)/, '\1 ')
+      end
+
+      def clean_tag match, ok_tags
+        tag = match[2].downcase
+        return " " unless (ok_attrs = ok_tags[tag])
+        "<#{match[1]}#{html_attribs tag, match[3], ok_attrs}>"
+      end
+
+      def html_attribs tag, raw_attr, ok_attrs
+        ok_attrs.each_with_object([tag]) do |ok_attr, pcs|
+          q, rest_value = process_attribute ok_attr, raw_attr
+          pcs << "#{ok_attr}=#{q}#{rest_value}#{q}" unless rest_value.blank?
+        end * " "
       end
 
       def process_attribute attrib, all_attributes

data/lib/card/director.rb

@@ -0,0 +1,231 @@
+class Card
+  # Directs the symphony of a card {Card::Act **act**}.
+  #
+  # Each act is divided into {Card::Action **actions**}: one action for each card.
+  # There are three action types: _create_, _update_, and _delete_.
+  #
+  # Each action is divided into three **phases**: _validation_, _storage_, and
+  # _integration_.
+  #
+  # Each phase is divided into three **stages**, as follows:
+  #
+  # #### Validation Stages
+  #
+  # * __VI__: initialize
+  # * __VP__: prepare_to_validate
+  # * __VV__: validate
+  #
+  # #### Storage Stages
+  #
+  # * __SP__: prepare_to_store
+  # * __SS__: store
+  # * __SF__: finalize
+  #
+  # #### Integration Stages
+  #
+  # * __II__: integrate
+  # * __IA__: after_integrate
+  # * __ID__: integrate_with_delay
+  #
+  # And each stage can have many {Card::Set::Event::Api **events**}, each of which is
+  # defined using the {Card::Set::Event::Api Event API}.
+  #
+  # The table below gives you an overview events can/should do in each stage:
+  #
+  # |    Phase:                 |    validation    |     storage     |  integration
+  # |    Stage:                 |   VI - VP - VV   |   SP - SS - SF  |  II - IA  - ID
+  # |---------------------------| :---:            | :---:           |:---:
+  # | **tasks**
+  # |  attach subcard           | yes!  yes!  yes  | yes   yes   yes | yes   yes   no
+  # |  detach subcard           | yes!  yes!  yes  | yes   no    no! |       no!
+  # |  validate                 | yes   yes   yes! |       no        |       no
+  # |  insecure change [^1]     | yes   yes!  no   |       no!       |       no!
+  # |  secure change [^2]       |       yes        | yes!  no!   no! |       no!
+  # |  abort                    |       yes!       |       yes       |       yes
+  # |  add errors               |       yes!       |       no!       |       no!
+  # |  subsave                  |       yes        |       yes       |       yes!
+  # |  has id (new card)        |       no         | no    no?   yes |       yes
+  # |  within web request       |       yes        |       yes       | yes   yes   no
+  # |  within transaction [^3]  |       yes        |       yes       |       no
+  # | **values**
+  # |    dirty attributes       |       yes        |       yes       |       yes
+  # |    params                 |       yes        |       yes       |       yes
+  # |    success                |       yes        |       yes       |       yes
+  # |    session                |       yes        |       yes       | yes   yes   no
+  #
+  # #### Understanding the Table
+  #
+  #  - **yes!**  the recommended stage to do that
+  #  - **yes**   ok to do it here
+  #  - **no**    not recommended; risky but not guaranteed to fail
+  #  - **no!**   never do it here. it won't work or will break things
+  #
+  # If there is only a single entry in a phase column it counts for all stages
+  # of that phase
+  #
+  # [^1]: 'insecure' means a change that might make the card invalid to save
+  # [^2]: 'secure' means you're sure that the change won't invalidate the card
+  # [^3]: If an exception is raised in the validation or storage phase
+  #       everything will rollback. If an integration event fails, db changes
+  #       of the other two phases will remain persistent, and other integration
+  #       events will continue to run.
+  #
+  # ## Director, Directors, and Subdirectors
+  #
+  # Only one act can be performed at a time in any given Card process. Information about
+  # that act is managed by _Director class methods_. Every act is associated with a
+  # single "main" card.
+  #
+  # The act, however, may involve many cards/actions. Each action has its own _Director
+  # instance_ that leads the card through all its stages. When a card action (A1)
+  # initiates a new action on a different card (A2), a new Director object is initialized.
+  # The new A2 subdirector's @parent is the director of the A1 card. Conversely, the
+  # A1 card stores a SubdirectorArray in @subdirectors to give it access to A2's
+  # Director and any little Director babies to which it gave birth.
+  #
+  # Subdirectors follow one of two distinct patterns:
+  #
+  # 1. {Card::Subcards **Subcards**}. When a card is altered using the subcards API, the
+  #    director follows a "breadth-first" pattern. For each stage a card runs its
+  #    stage events and then triggers its subcards to run that stage before proceeding
+  #    to the next stage. If a subcard is added in a stage then by the end of that
+  #    stage the director will catch it up to the current stage.
+  # 2. **Subsaves**. When a card is altered by a direct save (`Card.create(!)`,
+  #    `card.update(!)`, `card.delete(!)`, `card.save(!)`...), then the validation and
+  #    storage phases are executed immediately (depth-first), returning the saved card.
+  #    The integration phase, however, is executed following the same pattern as with
+  #    subcards.
+  #
+  # Let's consider a subcard example. Suppose you define the following event on
+  # self/bar.rb
+  #
+  #     event :met_a_foo_at_the_bar, :prepare_to_store, on: :update do
+  #       add_subcard "foo"
+  #     end
+  #
+  # And then you run `Card[:bar].update!({})`.
+  #
+  # When bar reaches the event in its `prepare_to_store` stage, the "foo" subcard will be
+  # added. After that stage ends, the stages `initialize`, `prepare_to_validate`,
+  # `validate`, and `prepare_to_store` are executed for foo so that it is now caught
+  # up with Bar at the `prepare_to_store` stage.
+  #
+  # If you have subcards within subcards, stages are executed preorder depth-first.
+  #
+  # Eg, assuming:
+  #
+  # - A has subcards AA and AB
+  # - AA has subcard AAA
+  # - AB has subcard ABA
+  #
+  # ...then the order of execution is:
+  #
+  # 1. A
+  # 2. AA
+  # 3. AAA
+  # 4. AB
+  # 5. ABA
+  #
+  # A special case can happen in the store stage when a supercard needs a subcard's id
+  # (for example as left_id or as type_id) and the subcard doesn't have an id yet
+  # (because it gets created in the same act). In this case the subcard's store stage
+  # is executed BEFORE the supercard's store stage.
+  #
+  # ---
+  class Director
+    extend EventDelay
+    extend ActDirection
+
+    include Stages
+    include Phases
+    include Run
+    include Store
+
+    attr_accessor :act, :card, :stage, :parent, :subdirectors
+    attr_reader :running
+    alias_method :running?, :running
+
+    def initialize card, parent
+      @card = card
+      @card.director = self
+      # for read actions there is no validation phase
+      # so we have to set the action here
+      @stage = nil
+      @running = false
+      @prepared = false
+      @parent = parent
+      @subdirectors = SubdirectorArray.initialize_with_subcards(self)
+      register
+    end
+
+    def main?
+      parent.nil?
+    end
+
+    def head?
+      @head || main?
+    end
+
+    def register
+      Director.add self
+    end
+
+    def unregister
+      Director.delete self
+    end
+
+    def delete
+      @parent&.subdirectors&.delete self
+      @card.director = nil
+      @subdirectors.clear
+      @stage = nil
+      @action = nil
+    end
+
+    def appoint card
+      reset_stage
+      update_card card
+      @head = true
+    end
+
+    def abort
+      @abort = true
+    end
+
+    def need_act
+      act_director = main_director
+      raise Card::Error, "act requested without a main director" unless act_director
+
+      @act = act_director.act ||= Director.need_act
+    end
+
+    def main_director
+      return self if main?
+
+      Director.act_director || (@parent&.main_director)
+    end
+
+    def to_s level=1
+      str = @card.name.to_s.clone
+      if @subdirectors.present?
+        subs = subdirectors.map { |d| "  " * level + d.to_s(level + 1) }.join "\n"
+        str << "\n#{subs}"
+      end
+      str
+    end
+
+    def replace_card card
+      card.action = @card.action
+      card.director = self
+      @card = card
+      reset_stage
+      catch_up_to_stage @stage if @stage
+    end
+
+    def update_card card
+      old_card = @card
+      @card = card
+      Director.card_changed old_card
+    end
+  end
+end