card 1.92.2 → 1.93.0

data/lib/card/codename.rb

@@ -1,6 +1,5 @@
 # -*- encoding : utf-8 -*-
 require_dependency "card/cache"
-require_dependency "card/name"
 
 class Card
   # {Card}'s names can be changed, and therefore _names_ should not be directly mentioned in code, lest a name change break the application.
@@ -23,14 +22,45 @@ class Card
   class Codename
     class << self
       # returns codename for id and id for codename
-      # @param key [Integer, String]
-      # @return [String, Integer]
-      def [] key
-        return if key.nil?
-        codehash[key.is_a?(Integer) ? key : key.to_sym]
+      # @param key [Integer, Symbol, String, Card::Name]
+      # @return [Symbol]
+      def [] codename
+        case codename
+        when Integer
+          codehash[codename]
+        when Symbol, String
+          codehash.key?(codename.to_sym) ? codename.to_sym : nil
+        end
+      end
+
+      def id codename
+        case codename
+        when Integer then codehash.key?(codename) && codename
+        when Symbol, String then codehash[codename.to_sym]
+        end
+      end
+
+      def name codename
+        name! codename
+      rescue Error::UnknownCodename => _e
+        yield if block_given?
+      end
+
+      def card codename
+        if (card_id = id(codename))
+          Card[card_id]
+        elsif block_given?
+          yield
+        end
+      end
+
+      def exist? codename
+        id(codename).present?
       end
 
-      # a Hash in which String keys have Integer values and vice versa
+      alias_method :exists?, :exist?
+
+      # a Hash in which Symbol keys have Integer values and vice versa
       # @return [Hash]
       def codehash
         @codehash ||= load_codehash
@@ -42,6 +72,18 @@ class Card
         Card.cache.delete "CODEHASH"
       end
 
+      # @param codename [Symbol, String]
+      # @return [Integer]
+      def id! codename
+        id(codename) || unknown_codename!(codename)
+      end
+
+      # @param codename [Symbol, String]
+      # @return [Card::Name]
+      def name! codename
+        Card::Name[codename.to_sym]
+      end
+
       private
 
       # iterate through every card with a codename
@@ -76,6 +118,12 @@ class Card
         end
         hash
       end
+
+      def unknown_codename! mark
+        raise Card::Error::UnknownCodename, I18n.t(:exception_unknown_codename,
+                                            scope: "lib.card.codename",
+                                            codename: mark)
+      end
     end
   end
 
@@ -86,16 +134,9 @@ class Card
   # @return [Integer]
   # @raise error if codename is missing
   def self.const_missing const
-    if const.to_s =~ /^([A-Z]\S*)ID$/ &&
-       (code = Regexp.last_match(1).underscore.to_sym)
-      if (card_id = Codename[code])
-        const_set const, card_id
-      else
-        raise I18n.t(:exception_missing_codename, scope: "lib.card.codename",
-                                                  code: code, const: const)
-      end
-    else
-      super
-    end
+    return super unless const.to_s =~ /^([A-Z]\S*)ID$/
+    code = Regexp.last_match(1).underscore
+    code_id = Codename.id!(code)
+    const_set const, code_id
   end
 end

data/lib/card/dirty.rb

@@ -0,0 +1,39 @@
+class Card
+  def self.define_dirty_methods field
+    define_method "#{field}_before_act" do
+      attribute_before_act field
+    end
+
+    define_method "#{field}_is_changing?" do
+      attribute_is_changing? field
+    end
+  end
+
+  [:name, :db_content, :trash, :type_id].each do |field|
+    define_dirty_methods field
+  end
+
+  def attribute_before_act attr
+    if saved_change_to_attribute? attr
+      attribute_before_last_save attr
+    elsif will_save_change_to_attribute? attr
+      mutations_from_database.changed_values[attr]
+    elsif not_in_callback?
+      attribute_was attr
+    else
+      _read_attribute attr
+    end
+  end
+
+  def not_in_callback? # or in integrate_with_delay stage
+    mutation_tracker.equal?(mutations_from_database)
+  end
+
+  def attribute_is_changing? attr
+    if not_in_callback?
+      attribute_changed? attr
+    else
+      saved_change_to_attribute?(attr) || will_save_change_to_attribute?(attr)
+    end
+  end
+end

data/lib/card/env/location.rb

@@ -8,7 +8,7 @@ class Card
 
       # TESTME
       def page_path title, opts={}
-        unless title.is_a? Card::Name
+        unless title.name?
           Rails.logger.warn "Pass only Card::Name to page_path " \
                             "(#{title} = #{title.class})"
         end

data/lib/card/env/location_history.rb

@@ -13,7 +13,7 @@ class Card
         return unless save_location?(card)
         discard_locations_for card
         session[:previous_location] =
-          Env::Location.card_path card.cardname.url_key
+          Env::Location.card_path card.name.url_key
         location_history.push previous_location
       end
 

data/lib/card/env/success.rb

@@ -136,7 +136,7 @@ class Card
       def to_url name_context=@name_context
         case (target = target(name_context))
         when Card
-          page_path target.cardname, params
+          page_path target.name, params
         else
           target
         end

data/lib/card/error.rb

@@ -15,6 +15,9 @@ class Card
     class NotFound < StandardError
     end
 
+    class UnknownCodename < NotFound
+    end
+
     # permission errors
     class PermissionDenied < Error
       attr_reader :card

data/lib/card/format.rb

@@ -1,27 +1,47 @@
 # -*- encoding : utf-8 -*-
 
 class Card
-  # The {Format} class is a key strut in the MoFoS
-  # _(Model-Format-Set)_ architecture.
+  # _Views_ are the primary way users interact with cards. Card::Format and its subclasses ({Card::Format::HtmlFormat}, {Card::Format::JsonFormat}, {Card::Format::XmlFormat}, etc) are responsible for defining and rendering _views_.
   #
-  # The primary means of transacting with the card Model (cards across time)
-  # is the _event_.  The primary means for displaying card content (cards across
-  # space) is the _view_. __Format objects manage card views__.
+  # However, Deck-coders (those who code in the Card/Decko framework) rarely write code directly in these classes. Instead they organize their code using {Card::Mods mods}. The {Card::Mod} docs explain how to set up a mod. Once you've done that, you're ready to define a view.  These docs will introduce the basics of view definition and
   #
-  # Here is a very simple view that just displays the card's id:
+  # Here is a very simple view that just defines a label for the card – its name:
   #
-  # ```` view(:simple_content) { card.raw_content } ````
+  #     view :label do
+  #       card.name
+  #     end
   #
-  # But suppose you would like this view to appear differently in different
-  # output formats.  You might need certain characters escaped in some formats
-  # (csv, html, etc) but not others.  You might like to make use of the
-  # aesthetic or structural benefits certain formats allow.
+  # If a format is not specified, the view is defined on the base format class, Card::Format. The following two definitions are equivalent to the definition above:
   #
-  # To this end we have format classes. {Format::HtmlFormat},
-  # {Format::JsonFormat}, {Format::XmlFormat}, etc, each are descendants of
-  # {Card::Format}.
+  #     format do
+  #       view(:label) { card.name }
+  #     end
   #
-  # For information on how Formats intersect with Sets, see {Card::Set::Format}
+  #     format(:base) { view(:label) { card.name } }
+  #
+  # But suppose you would like this view to appear differently in different output formats. For example, you'd like this label to have a tag with a class attribute HTML so that you can style it with CSS.
+  #
+  #     format :html do
+  #       view :label do
+  #         div(class: "my-label") { card.name }
+  #       end
+  #     end
+  #
+  # Note that in place of card.name, you could also use `super`, because this view is translated into a method on Card::Format::HtmlFormat, which inherits from Card::Format.
+  #
+  # ## Common arguments for view definitions
+  #
+  # * :perms - restricts view permissions. Value can be :create, :read, :update, :delete, or a Proc.
+  # * :tags - tag view as needed.
+  #
+  # The most commmon tag is "unknown_ok," which indicates that a view can be rendered even if the card is "unknown" (not real or virtual).
+  #
+  # ## Rendering views
+  #
+  # To render our label view, you can use either of these:
+  #
+  #     render :label
+  #     render_label
   #
   class Format
     include Card::Env::Location
@@ -45,6 +65,10 @@ class Card
     attr_reader :card, :parent, :main_opts
     attr_accessor :form, :error_status
 
+    def self.view_caching?
+      true
+    end
+
     def initialize card, opts={}
       @card = card
       require_card_to_initialize!
@@ -67,7 +91,8 @@ class Card
       end
     end
 
-    def page view, slot_opts
+    def page controller, view, slot_opts
+      @controller = controller
       @card.run_callbacks :show_page do
         show view, slot_opts
       end
@@ -78,7 +103,7 @@ class Card
     end
 
     def controller
-      Env[:controller] ||= CardController.new
+      @controller || Env[:controller] ||= CardController.new
     end
 
     def session
@@ -95,17 +120,26 @@ class Card
       end
     end
 
+    RENDER_METHOD_RE = /^(_)?render(_(\w+))?(!)?/
+
+    def respond_to_missing? method, _include_private=false
+      (method =~ RENDER_METHOD_RE) || template.respond_to?(method)
+    end
+
     def method_missing method, *opts, &proc
-      if method =~ /(_)?(optional_)?render(_(\w+))?/
+      if method =~ RENDER_METHOD_RE
         api_render Regexp.last_match, opts
       else
         pass_method_to_template_object(method, opts, proc) { yield }
       end
     end
 
-    def respond_to_missing? method_name, _include_private=false
-      (method_name =~ /(_)?(optional_)?render(_(\w+))?/) ||
-        template.respond_to?(method_name)
+    def api_render match, opts
+      view = match[2] ? match[3] : opts.shift                 # view can be part of method name or first argument
+      args = opts[0] ? opts.shift.clone : {}                  # opts are opts ;)
+      args[:optional] = (opts.shift || :show) unless match[4] # bang (!) after render
+      args[:skip_perms] = true if match[1]                    # underscore (_) before render
+      render! view, args
     end
 
     def pass_method_to_template_object method, opts, proc

data/lib/card/format/content.rb

@@ -53,7 +53,7 @@ class Card
       end
 
       def unique_id
-        "#{card.cardname.safe_key}-#{id_counter}"
+        "#{card.name.safe_key}-#{id_counter}"
       end
 
       def output *content

data/lib/card/format/context_names.rb

@@ -12,7 +12,7 @@ class Card
       end
 
       def context_names_from_parent
-        part_keys = @card.cardname.part_names.map(&:key)
+        part_keys = @card.name.part_names.map(&:key)
         parent.context_names.reject { |n| !part_keys.include? n.key }
       end
 
@@ -32,7 +32,7 @@ class Card
       end
 
       def title_in_context title=nil
-        title = title ? title.to_name.absolute_name(card.cardname) : card.cardname
+        title = title ? title.to_name.absolute_name(card.name) : card.name
         title.from *context_names
       end
     end

data/lib/card/format/nest.rb

@@ -45,7 +45,7 @@ class Card
       def nest_render nested_card, view, options, override
         subformat = nest_subformat nested_card, options, view
         view = subformat.modal_nest_view view if override
-        rendered = count_chars { subformat.optional_render view, options }
+        rendered = count_chars { subformat.render view, options }
         block_given? ? yield(rendered, view) : rendered
       end
 
@@ -80,7 +80,7 @@ class Card
       #   home.nest :self         # => nest for '*self'
       #   home.field_nest :self   # => nest for 'Home+*self'
       def field_nest field, opts={}
-        field = card.cardname.field(field) unless field.is_a? Card
+        field = card.name.field(field) unless field.is_a? Card
         nest field, opts
       end
 

data/lib/card/format/nest/fetch.rb

@@ -21,7 +21,7 @@ class Card
           new_args = { name: nest_name, type: nest_opts[:type] }
 
           new_args[:supercard] = card.context_card unless nest_name.strip.blank?
-          # special case.  gets absolutized incorrectly. fix in cardname?
+          # special case.  gets absolutized incorrectly. fix in name?
 
           nest_new_main_args new_args if nest_name =~ /^_main\+/
           nest_new_content_args new_args, nest_name

data/lib/card/format/nest/subformat.rb

@@ -24,7 +24,7 @@ class Card
         end
 
         def field_subformat field
-          field = card.cardname.field(field) unless field.is_a?(Card)
+          field = card.name.field(field) unless field.is_a?(Card)
           subformat field
         end
       end

data/lib/card/format/render.rb

@@ -3,7 +3,7 @@ class Card
     # View rendering methods.
     #
     module Render
-      def render view, args={}
+      def render! view, args={}
         voo = View.new self, view, args, @voo
         with_voo voo do
           voo.process do |final_view, options|
@@ -63,10 +63,6 @@ class Card
           source_location.second.to_s
       end
 
-      def view_caching?
-        true
-      end
-
       # setting (:alway, :never, :nested) designated in view definition
       def view_cache_setting view
         method = self.class.view_cache_setting_method view
@@ -77,11 +73,13 @@ class Card
       end
 
       def stub_render cached_content
-        expand_stubs cached_content do |stub_hash|
+        result = expand_stubs cached_content do |stub_hash|
           prepare_stub_nest(stub_hash) do |stub_card, mode, options, override|
             with_nest_mode(mode) { nest stub_card, options, override }
           end
         end
+        puts "STUB IN RENDERED VIEW: #{card.name}: #{voo.ok_view}\n#{result}" if result =~ /stub/
+        result
       end
 
       def prepare_stub_nest stub_hash
@@ -110,18 +108,6 @@ class Card
         end
       end
 
-      def api_render match, opts
-        view = match[3] ? match[4] : opts.shift
-        args = opts[0] ? opts.shift.clone : {}
-        optional_render_args(args, opts) if match[2]
-        args[:skip_perms] = true if match[1]
-        render view, args
-      end
-
-      def optional_render_args args, opts
-        args[:optional] = opts.shift || :show
-      end
-
       def view_method view
         unless supports_view? view
           voo.unsupported_view = view

data/lib/card/migration.rb

@@ -65,7 +65,7 @@ class Card::Migration < ActiveRecord::Migration[4.2]
         begin
           yield
         ensure
-          Card::Cache.reset_all
+          ::Card::Cache.reset_all
         end
       end
     end

data/lib/card/migration/import.rb

@@ -99,7 +99,7 @@ class Card
 
       def fetch_local_data name, view
         Card::Auth.as_bot do
-          Card[name].format(format: :json).render(view || :content)
+          Card[name].format(format: :json).render!(view || :content)
         end
       end