card 1.91 → 1.92

data/lib/card/subcards.rb

@@ -269,7 +269,7 @@ class Card
       if @context_card.name =~ /^\+/ || name.blank?
         name.to_name
       else
-        name.to_name.to_absolute_name(@context_card.name)
+        name.to_name.absolute_name(@context_card.name)
       end
     end
 

data/lib/card/tasks/card.rake

@@ -2,7 +2,7 @@ namespace :card do
   def importer
     @importer ||= Card::Migration::Import.new Card::Migration.data_path
   end
-  
+
   desc "merge import card data that was updated since the last push into " \
        "the the database"
   task merge: :environment do
@@ -38,8 +38,7 @@ namespace :card do
   desc "add a new card to import data"
   task add: :environment do
     _task, name, type, codename = ARGV
-    importer.add_card name: name, type: type || "Basic",
-                                     codename: codename
+    importer.add_card name: name, type: type || "Basic", codename: codename
     exit
   end
 
@@ -58,4 +57,45 @@ namespace :card do
     importer.pull card, opts.merge(remote: ENV["from"])
     exit # without exit the card argument is treated as second rake task
   end
+
+  desc "migrate structure and cards"
+  task migrate: :environment do
+    ENV["NO_RAILS_CACHE"] = "true"
+    ENV["SCHEMA"] ||= "#{Cardio.gem_root}/db/schema.rb"
+
+    stamp = ENV["STAMP_MIGRATIONS"]
+
+    puts "migrating structure"
+    Rake::Task["card:migrate:structure"].invoke
+    Rake::Task["card:migrate:stamp"].invoke :structure if stamp
+
+    puts "migrating core cards"
+    Card::Cache.reset_all
+    # not invoke because we don't want to reload environment
+    Rake::Task["card:migrate:core_cards"].execute
+    if stamp
+      Rake::Task["card:migrate:stamp"].reenable
+      Rake::Task["card:migrate:stamp"].invoke :core_cards
+    end
+
+    puts "migrating deck cards"
+    # not invoke because we don't want to reload environment
+    Rake::Task["card:migrate:deck_cards"].execute
+    if stamp
+      Rake::Task["card:migrate:stamp"].reenable
+      Rake::Task["card:migrate:stamp"].invoke :deck_cards
+    end
+
+    Card::Cache.reset_all
+  end
+
+  desc "reset cache"
+  task reset_cache: :environment do
+    Card::Cache.reset_all
+  end
+
+  desc "reset machine output"
+  task reset_machine_output: :environment do
+    Card.reset_all_machines
+  end
 end

data/lib/card/tasks/card/migrate.rake

@@ -0,0 +1,77 @@
+def run_card_migration core_or_deck
+  prepare_migration
+  verbose = ENV["VERBOSE"] ? ENV["VERBOSE"] == "true" : true
+  Cardio.schema_mode(core_or_deck) do |paths|
+    ActiveRecord::Migrator.migrations_paths = paths
+    ActiveRecord::Migration.verbose = verbose
+    ActiveRecord::Migrator.migrate paths, version
+  end
+end
+
+def prepare_migration
+  Card::Cache.reset_all
+  ENV["SCHEMA"] ||= "#{Cardio.gem_root}/db/schema.rb"
+  Card::Cache.reset_all
+  Card.config.action_mailer.perform_deliveries = false
+  Card.reset_column_information
+  # this is needed in production mode to insure core db
+  Card::Reference.reset_column_information
+  # structures are loaded before schema_mode is set
+end
+
+namespace :card do
+  namespace :migrate do
+    desc "migrate cards"
+    task cards: [:core_cards, :deck_cards]
+
+    desc "migrate structure"
+    task structure: :environment do
+      ENV["SCHEMA"] ||= "#{Cardio.gem_root}/db/schema.rb"
+      Cardio.schema_mode(:structure) do |paths|
+        ActiveRecord::Migrator.migrations_paths = paths
+        ActiveRecord::Migrator.migrate paths, version
+        Rake::Task["db:_dump"].invoke # write schema.rb
+      end
+    end
+
+    desc "migrate core cards"
+    task core_cards: :environment do
+      require "card/migration/core"
+      run_card_migration :core_cards
+    end
+
+    desc "migrate deck cards"
+    task deck_cards: :environment do
+      require "card/migration"
+      run_card_migration :deck_cards
+    end
+
+    desc "Redo the deck cards migration given by VERSION."
+    task redo: :environment do
+      version = ENV["VERSION"] ? ENV["VERSION"].to_i : nil
+      verbose = ENV["VERBOSE"] ? ENV["VERBOSE"] == "true" : true
+      raise "VERSION is required" unless version
+      ActiveRecord::Migration.verbose = verbose
+      ActiveRecord::SchemaMigration.where(version: version.to_s).delete_all
+      ActiveRecord::Migrator.run :up, Cardio.migration_paths(:deck_cards),
+                                 version
+    end
+
+    # maybe we should move this to a method?
+    desc "write the version to a file (not usually called directly)"
+    task :stamp, :type do |_t, args|
+      ENV["SCHEMA"] ||= "#{Cardio.gem_root}/db/schema.rb"
+      Cardio.config.action_mailer.perform_deliveries = false
+
+      stamp_file = Cardio.schema_stamp_path(args[:type])
+
+      Cardio.schema_mode args[:type] do
+        version = ActiveRecord::Migrator.current_version
+        if version.to_i > 0 && (file = open(stamp_file, "w"))
+          puts ">>  writing version: #{version} to #{stamp_file}"
+          file.puts version
+        end
+      end
+    end
+  end
+end

data/lib/card/view.rb

@@ -1,13 +1,13 @@
 require_dependency "card/view/visibility"
-require_dependency "card/view/fetch"
 require_dependency "card/view/cache"
 require_dependency "card/view/stub"
 require_dependency "card/view/options"
 
 class Card
   class View
+    # Card::View handles view rendering and caching.
+
     include Visibility
-    include Fetch
     include Cache
     include Stub
     include Options
@@ -16,11 +16,16 @@ class Card
     attr_reader :format, :parent, :card
     attr_accessor :unsupported_view
 
+    # @return [Symbol]
     def self.canonicalize view
       return if view.blank? # error?
       view.to_viewname.key.to_sym
     end
 
+    # @param format [Card::Format]
+    # @param view [Symbol]
+    # @param raw_options [Hash]
+    # @param parent [Card::View] (optional)
     def initialize format, view, raw_options={}, parent=nil
       @format = format
       @raw_view = view
@@ -32,24 +37,48 @@ class Card
     end
 
     # handle rendering, including optional visibility, permissions, and caching
+    # @return [rendered view or a stub]
     def process
       process_live_options
-      process_visibility_options
       return if optional? && hide?(requested_view)
       fetch { yield ok_view, foreign_live_options }
     end
 
-    # the view to "attempt".  Typically the same as @raw_view, but @raw_view is
-    # often overridden for the main view (top view of the main card on a page)
+    # the view to "attempt".  Typically the same as @raw_view, but @raw_view can
+    # be overridden, eg for the main view (top view of the main card on a page)
+    # @return [Symbol] view name
     def requested_view
       @requested_view ||= View.canonicalize live_options[:view]
     end
 
     # the final view.  can be different from @requested_view when there are
     # issues with permissions, recursions, unknown cards, etc.
+    # @return [Symbol] view name
     def ok_view
       @ok_view ||= format.ok_view requested_view,
                                   normalized_options[:skip_perms]
     end
+
+    # @return [Card::View]
+    def root
+      @root = parent ? parent.root : self
+    end
+
+    # @return [true/false]
+    def root?
+      !parent
+    end
+
+    # neither view nor format has a parent
+    # @return [true/false]
+    def deep_root?
+      !parent && !format.parent
+    end
+
+    # next voo object found tracing ancestry through parent voos and/or parent formats
+    # @return [Card::View]
+    def next_ancestor
+      parent || (format.parent && format.parent.voo)
+    end
   end
 end

data/lib/card/view/cache.rb

@@ -1,47 +1,77 @@
+require_dependency "card/view/cache_action"
+
 class Card
   class View
-    # cache mechanics for view caching
+    include CacheAction
+
     module Cache
-      # adds tracking, mapping, and stub handling to standard cache fetching
+      # Support context-aware card view caching.
+      #
+      # render or retrieve view (or stub) with current options
+      # @params &block [Block] render block
+      # @return [rendered view or stub]
+      def fetch &block
+        case cache_action
+          when :yield       then yield                # simple render
+          when :cache_yield then cache_render(&block) # render to/from cache
+          when :stub        then stub                 # render stub
+        end
+      end
+
+      # Fetch view via cache and, when appropriate, render its stubs
+      #
+      # If this is a free cache action (see CacheAction), we go through the stubs and render them now.
+      # If the cache is active (ie, we are inside another view), we do not worry about stubs but keep going,
+      # because the free cache we're inside will take care of those stubs.
+      #
+      # @return [String (usually)] rendered view
+      def cache_render
+        cached_view = cache_fetch { yield }
+        cache_active? ? cached_view : format.stub_render(cached_view)
+      end
+
+      # Is there already a view cache in progress on which this one depends?
+      #
+      # Note that if you create a brand new independent format object (ie, not a subformat)
+      # its activity will be treated as unrelated to this caching/rendering.
+      #
+      # @return [true/false]
+      def cache_active?
+        deep_root? ? false : self.class.caching?
+      end
+
+      # If view is cached, retrieve it.  Otherwise render and store it.
+      # Uses the primary cache API.
       def cache_fetch
-        cached_view = caching do
+        caching do
           self.class.cache.fetch cache_key do
-            card.register_view_cache_key cache_key
+            register_cache_key
             yield
           end
         end
-
-        caching? ? cached_view : format.stub_render(cached_view)
       end
 
-      # tracks that a cache fetch is in progress
+      # keep track of nested cache fetching
       def caching
         self.class.caching(self) { yield }
       end
 
-      # answers: should this cache fetch depend on one already in progress?
-      # Note that if you create a brand new format object (ie, not a subformat)
-      # midrender, (eg card.format...), it needs to be treated as unrelated to
-      # any caching in progress.
-      def caching?
-        deep_root? ? false : self.class.caching?
-      end
 
-      # neither view nor format has a parent
-      def deep_root?
-        !parent && !format.parent
-      end
+      #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      # VIEW CACHE KEY
 
-      def root
-        @root = parent ? parent.root : self
-      end
 
       def cache_key
         @cache_key ||= [
-          card.key, format.class, format.mode, options_for_cache_key
+          card.key, format.class, format.nest_mode, options_for_cache_key
         ].map(&:to_s).join "-"
       end
 
+      # Registers the cached view for later clearing in the event of related card changes
+      def register_cache_key
+        card.register_view_cache_key cache_key
+      end
+
       def options_for_cache_key
         hash_for_cache_key(live_options) + hash_for_cache_key(viz_hash)
       end
@@ -52,22 +82,29 @@ class Card
         end.join ";"
       end
 
+      def array_for_cache_key array
+        # TODO: needs better handling of edit_structure
+        #  currently we pass complete structure as nested array
+        array.map do |item|
+          item.is_a?(Array) ? item.join(":") : item.to_s
+        end.sort.join ","
+      end
+
       def option_for_cache_key key, value
-        string_value =
-          case value
+        "#{key}:#{option_value_to_string value}"
+      end
+
+      def option_value_to_string value
+        case value
           when Hash then "{#{hash_for_cache_key value}}"
-          when Array then
-            # TODO: needs better handling of edit_structure
-            #       currently we pass complete structure as nested array
-            value.map do |item|
-              item.is_a?(Array) ? item.join(":") : item.to_s
-            end.sort.join ","
+          when Array then array_for_cache_key(value)
           else value.to_s
-          end
-        "#{key}:#{string_value}"
+        end
       end
 
+      #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
       # cache-related Card::View class methods
+
       module ClassMethods
         def cache
           Card::Cache[Card::View]

data/lib/card/view/cache_action.rb

@@ -0,0 +1,158 @@
+class Card
+  class View
+    module CacheAction
+      # determine action to be used in #fetch
+
+      # course of action based on config/status/options
+      # @return [Symbol] :yield, :cache_yield, or
+      def cache_action
+        log_cache_action do
+          send "#{cache_status}_cache_action"
+        end
+      end
+
+      def log_cache_action
+        action = yield
+        if false # TODO: make configurable
+          puts "VIEW CACHE [#{action}] (#{card.name}##{requested_view})"
+        end
+        action
+      end
+
+      # @return [Symbol] :off, :active, or :free
+      def cache_status
+        case
+        when !cache_on?    then :off    # view caching is turned off, format- or system-wide
+        when cache_active? then :active # another view cache is in progress; this view is inside it
+        else                    :free   # no other cache in progress
+        end
+      end
+
+
+      # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      # CACHE STATUS: OFF
+      # view caching is turned off, format- or system-wide
+
+      # @return [True/False]
+      def cache_on?
+        Card.config.view_cache && format.view_caching?
+      end
+
+      # always skip all the magic
+      def off_cache_action
+        :yield
+      end
+
+
+      # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      # CACHE STATUS: FREE
+      # caching is on; no other cache in progress
+
+      # @return [Symbol]
+      def free_cache_action
+        free_cache_ok? ? :cache_yield : :yield
+      end
+
+      # @return [True/False]
+      def free_cache_ok?
+        cache_setting != :never &&
+          foreign_live_options.empty? &&
+          clean_enough_to_cache?
+        # note: foreign options are a problem in the free cache, because
+      end
+
+
+      # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      # CACHE STATUS: ACTIVE
+      # another view cache is in progress; this view is inside it
+
+      # @return [Symbol]
+      def active_cache_action
+        validate_active_cache_action do
+          active_cache_ok? ? active_cache_action_from_setting : :stub
+        end
+      end
+
+      # catch recursive views and invalid stubs
+      def validate_active_cache_action
+        return :yield if ok_view == :too_deep
+        #FIXME - this allows "too deep" error to be cached inside another view. may need a "raise" cache action?
+        action = yield
+        validate_stub! if action == :stub
+        action
+      end
+
+      # @return [True/False]
+      def active_cache_ok?
+        return false unless parent && clean_enough_to_cache?
+        return true if normalized_options[:skip_perms]
+        active_cache_permissible?
+      end
+
+      # apply any permission checks required by view.
+      # (do not cache views with nuanced permissions)
+      def active_cache_permissible?
+        case permission_task
+        when :none                  then true
+        when parent.permission_task then true
+        when Symbol                 then card.anyone_can?(permission_task)
+        else                             false
+        end
+      end
+
+      # task directly associated with the view in its definition via the
+      # "perms" directive
+      def permission_task
+        @permission_task ||= Card::Format.perms[requested_view] || :read
+      end
+
+      # determine the cache action from the cache setting (assuming cache status is "active")
+      # @return [Symbol] cache action
+      def active_cache_action_from_setting
+        level = ACTIVE_CACHE_LEVEL[cache_setting]
+        level || raise("unknown cache setting: #{cache_setting}")
+      end
+
+      ACTIVE_CACHE_LEVEL = {
+        always:   :cache_yield, # read/write cache specifically for this view
+        standard: :yield,       # render view; it will only be cached within active view
+        never:    :stub         # render a stub
+      }.freeze
+
+      # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      # SHARED METHODS
+
+      # Mod developers can configure cache directives on view definitions.  eg:
+      #   view :myview, cache: :standard do ...
+      #
+      # There are three possible values for those rules.
+      # * *standard* (default) cache when possible, but avoid double caching
+      #   (caching one view while already caching another)
+      # * *always* cache whenever possible, even if that means double caching
+      # * *never* don't ever cache this view
+      #
+      # Of these, "never" is most often used explicitly, usually in places
+      # where the view can be altered by things other than simple related card changes.
+      # It is important to note that to use "never", a view MUST be stubbable (ie, no
+      # foreign options). Otherwise the rendering may be involved in an active cache,
+      # reach an uncacheable view, attempt to stub it, and fail.
+      #
+      # @return [Symbol] :standard, :always, or :never
+      def cache_setting
+        format.view_cache_setting requested_view
+      end
+
+
+      # altered view requests and altered cards are not cacheable
+      # @return [True/False]
+      def clean_enough_to_cache?
+        requested_view == ok_view &&
+          !card.unknown? &&
+          !card.db_content_changed?
+        # FIXME: might consider other changes as disqualifying, though
+        # we should make sure not to disallow caching of virtual cards
+      end
+
+    end
+  end
+end