Class: Card

Inherits:
Cardio::Record show all
Extended by:
Cache::CardClass, Director::CardClass, Dirty::MethodFactory, Fetch::CardClass, Mark, Name::CardClass, Query::CardClass
Includes:
Cache::All, Content::All, Director::All, Dirty, DirtyNames, Fetch::All, Name::All, Reference::All, Rule::All, Set::CardMethods, Subcards::All
Defined in:
lib/card.rb,
lib/card/env.rb,
lib/card/set.rb,
lib/card/auth.rb,
lib/card/mark.rb,
lib/card/name.rb,
lib/card/rule.rb,
lib/card/view.rb,
lib/card/cache.rb,
lib/card/dirty.rb,
lib/card/error.rb,
lib/card/fetch.rb,
lib/card/query.rb,
lib/card/format.rb,
lib/card/mailer.rb,
lib/card/content.rb,
lib/card/lexicon.rb,
lib/card/setting.rb,
lib/card/codename.rb,
lib/card/director.rb,
lib/card/name/all.rb,
lib/card/rule/all.rb,
lib/card/set/type.rb,
lib/card/subcards.rb,
lib/card/cache/all.rb,
lib/card/fetch/all.rb,
lib/card/reference.rb,
lib/card/set/event.rb,
lib/card/set/trait.rb,
lib/card/auth/proxy.rb,
lib/card/auth/setup.rb,
lib/card/auth/token.rb,
lib/card/query/join.rb,
lib/card/rule/cache.rb,
lib/card/set/format.rb,
lib/card/view/cache.rb,
lib/card/content/all.rb,
lib/card/env/success.rb,
lib/card/env/support.rb,
lib/card/fetch/store.rb,
lib/card/format/nest.rb,
lib/card/query/value.rb,
lib/card/set/helpers.rb,
lib/card/set/pattern.rb,
lib/card/view/classy.rb,
lib/card/auth/current.rb,
lib/card/content/diff.rb,
lib/card/director/all.rb,
lib/card/director/run.rb,
lib/card/env/location.rb,
lib/card/format/error.rb,
lib/card/query/clause.rb,
lib/card/set/abstract.rb,
lib/card/subcards/add.rb,
lib/card/subcards/all.rb,
lib/card/view/options.rb,
lib/card/content/chunk.rb,
lib/card/content/clean.rb,
lib/card/fetch/results.rb,
lib/card/format/render.rb,
lib/card/reference/all.rb,
lib/card/set/event/all.rb,
lib/card/set/registrar.rb,
lib/card/subcards/args.rb,
lib/card/content/parser.rb,
lib/card/director/store.rb,
lib/card/fetch/retrieve.rb,
lib/card/format/content.rb,
lib/card/format/nesting.rb,
lib/card/format/wrapper.rb,
lib/card/name/all/parts.rb,
lib/card/set/i18n_scope.rb,
lib/card/cache/temporary.rb,
lib/card/director/phases.rb,
lib/card/director/stages.rb,
lib/card/name/card_class.rb,
lib/card/query/act_query.rb,
lib/card/set/inheritance.rb,
lib/card/set/pattern/all.rb,
lib/card/subcards/relate.rb,
lib/card/subcards/remove.rb,
lib/card/view/cache/stub.rb,
lib/card/view/permission.rb,
lib/card/auth/permissions.rb,
lib/card/cache/card_class.rb,
lib/card/cache/persistent.rb,
lib/card/env/serializable.rb,
lib/card/env/slot_options.rb,
lib/card/fetch/card_class.rb,
lib/card/query/card_class.rb,
lib/card/query/card_query.rb,
lib/card/set/advanced_api.rb,
lib/card/set/card_methods.rb,
lib/card/set/i18n_scanner.rb,
lib/card/set/pattern/base.rb,
lib/card/cache/prepopulate.rb,
lib/card/env/serialization.rb,
lib/card/format/nest/fetch.rb,
lib/card/model/save_helper.rb,
lib/card/set/event/options.rb,
lib/card/content/diff/l_c_s.rb,
lib/card/env/success/target.rb,
lib/card/name/name_variants.rb,
lib/card/query/action_query.rb,
lib/card/set/required_field.rb,
lib/card/content/diff/result.rb,
lib/card/director/card_class.rb,
lib/card/format/nesting/main.rb,
lib/card/format/nesting/mode.rb,
lib/card/format/registration.rb,
lib/card/query/sql_statement.rb,
lib/card/set/event/callbacks.rb,
lib/card/content/diff/summary.rb,
lib/card/director/event_delay.rb,
lib/card/dirty/method_factory.rb,
lib/card/env/location_history.rb,
lib/card/format/context_names.rb,
lib/card/name/all/descendants.rb,
lib/card/query/abstract_query.rb,
lib/card/query/card_query/run.rb,
lib/card/rule/read_rule_cache.rb,
lib/card/view/options/voo_api.rb,
lib/card/query/reference_query.rb,
lib/card/rule/preference_cache.rb,
lib/card/set/format/haml_paths.rb,
lib/card/cache/persistent_class.rb,
lib/card/content/chunk/abstract.rb,
lib/card/director/class_methods.rb,
lib/card/view/options/key_lists.rb,
lib/card/format/card_action_view.rb,
lib/card/query/card_query/custom.rb,
lib/card/query/value/match_value.rb,
lib/card/set/event/delayed_event.rb,
lib/card/view/cache/cache_action.rb,
lib/card/view/options/visibility.rb,
lib/card/format/method_delegation.rb,
lib/card/format/nesting/subformat.rb,
lib/card/query/abstract_query/tie.rb,
lib/card/query/card_query/sorting.rb,
lib/card/query/card_query/found_by.rb,
lib/card/query/sql_statement/joins.rb,
lib/card/query/sql_statement/order.rb,
lib/card/query/sql_statement/where.rb,
lib/card/set/pattern/class_methods.rb,
lib/card/director/subdirector_array.rb,
lib/card/set/event/skip_and_trigger.rb,
lib/card/set/format/abstract_format.rb,
lib/card/content/diff/l_c_s/processor.rb,
lib/card/query/card_query/conjunctions.rb,
lib/card/query/card_query/normalization.rb,
lib/card/query/card_query/interpretation.rb,
lib/card/model/save_helper/save_arguments.rb,
lib/card/query/abstract_query/query_helper.rb,
lib/card/query/card_query/match_attributes.rb,
lib/card/set/format/abstract_format/wrapper.rb,
lib/card/model/save_helper/save_helper_helper.rb,
lib/card/set/format/abstract_format/view_opts.rb,
lib/card/query/card_query/reference_attributes.rb,
lib/card/set/format/abstract_format/haml_views.rb,
lib/card/query/card_query/relational_attributes.rb,
lib/card/set/format/abstract_format/view_definition.rb

Overview

Cards are wiki-inspired building blocks.

This documentation is for developers who want to understand:

1. how ruby Card objects work, and
2. how to extend them.

It assumes that you’ve already read the introductory text in README.

Throughout this document we will refer to @card as an instance of a Card object.

## Names

There are four important card identifiers, sometimes called “marks”. Every card has a unique name, key, and id. Some cards also have a codename.

@card.name     # The name, a Card::Name object, is the most recognizable card
               # mark.
@card.key      # The key, a String, is a simple lower-case name variant.
@card.id       # The id is an Integer.
@card.codename # The codename, a Symbol, is the name by which a card can be
               # referred to in code.

All names with the same key (including the key itself) are considered variants of each other. No two cards can have names with the same key. Name objects inherit from Strings but add many other methods for common card name patterns, eg ‘“A+B”.to_name.right => “B”`.

Setting a card’s name, eg ‘@card.name = “New Name”`, will automatically update the key.

## Type

Every card has a type, and every type itself has an associated card. For example, Paula’s type might be User, so there is also a User card.

The type may be accessed in several ways:

    @card.type_id      # returns id of type card [Integer]
    @card.type_name    # returns name of type card [Card::Name]
    @card.type_code    # returns codename of type card [Symbol]
    @card.type_card    # returns Cardtype card associated with @card's type [Card]

- {Set::All::Type Common type methods}

## Content

There are two primary methods for accessing a card’s content:

@card.db_content   # the content as it appears in the database
@card.content      # the "official" content, which may be different from

db_content when db_content is overridden with a structure rule.

- {Content Processing card content}
- {Set::All::Content Common content methods}

## Fetch

The two main ways to retrieve cards are fetching (retrieving cards one at a time) and querying (retrieving lists of cards). More on querying below.

Any of the above marks (name, key, id, codename) can be used to fetch a card, eg:

@card1 = Card.fetch "Garden" # returns the card with the name "Garden" (or, more

precisely, with the key “garden”)

@card2 = Card.fetch 100      # returns the card with the id 100
@card3 = Card.fetch :help    # returns the card with the codename help

The fetch API will first try to find the card in the cache and will only look in the database if necessary.

The ‘Card[]` shortcut will return the same results but does not support the full range of advanced options and will not return virtual cards (cards that can be constructed from naming patterns but are not actually in the database).

# equivalent to the above but more concise
@card1 = Card["Garden"]
@card2 = Card[100]
@card3 = Card[:help]

Better still, you can use the ‘#card` method on Strings, Integers, Symbols, and Arrays

# equivalent to the above but even more concise
@card1 = "Garden".card
@card2 = 100.card
@card3 = :help.card

The ‘#card_id`, `#cardname`, and `#codename` methods work on all the same objects and provide convenient shortcuts for quickly fetching and returning card attributes.

- {Card::Fetch::CardClass More on fetching.}

## Query

Card queries find and return lists of cards, eg:

    Card.search type_id: 4 # returns an Array of cards with the type_id of 4.

- {Card::Query More on queries}

## Views and Events

Views and events are a _Shark’s_ primary tools for manipulating cards. Views customize card presentation, while events customize card transactions. Or, if you like, views and events respectively alter cards in space and time.

Both views and events are defined in mods, short for modules or modifications.

- {Set::Format::AbstractFormat#view More on views}
- {Set::Event::Api#event More on events}

## Accounts and Permissions

Card code is always executed in the context of a given user account. Permissions for that account are automatically checked when running a query, performing an action, or rendering a view. A typical query, for example, can only return cards that the current user has permission to read.

You can see the current user with ‘Card::Auth.current`. The permissions of a proxy user can be temporarily assumed using `Card::Auth#as`.

More on accounts

Defined Under Namespace

Modules: Auth, Dirty, DirtyNames, Env, Lexicon, Mark, Model, Query, Rule, Set, Setting Classes: Cache, Codename, Content, Director, Error, Fetch, Format, Mailer, Name, Reference, Subcards, View

Constant Summary

Constants included from Mark

Mark::CODENAME_MARK_RE, Mark::ID_MARK_RE

Constants included from Reference::All

Reference::All::PARTIAL_REF_CODE

Instance Attribute Summary

Attributes included from Director::All

#director

Attributes included from Name::All

#supercard

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Mark

cardish, id_from_string, id_or_name, name_from_id_from_string

Methods included from Dirty::MethodFactory

define_dirty_methods

Methods included from Name::CardClass

generate_alternative_name, rename!, uniquify_name

Methods included from Cache::CardClass

expire, retrieve_from_cache, retrieve_from_cache_by_id, retrieve_from_cache_by_key, write_to_cache, write_to_soft_cache

Methods included from Director::CardClass

create, create!, ensure, ensure!

Methods included from Fetch::CardClass

[], fetch, fetch_from_cast, fetch_name, fetch_type_id, id, quick_fetch, uri_fetch

Methods included from Query::CardClass

count_by_cql, find_each, find_in_batches, search

Methods included from Subcards::All

#drop_field, #drop_subcard, #field, #field?, #field_content, #handle_subcard_errors, #subcard, #subcard?, #subcard_content, #subcards, #subcards?

Methods included from Fetch::All

#fetch, #newish, #refresh

Methods included from Rule::All

#preference, #preference?, #preference_card, #preference_card_id, #rule, #rule?, #rule_card, #rule_card_id, #standard_rule?

Methods included from Reference::All

#create_references_out, #name_referers, #nestees, #nesters, #referees, #referees_from_references, #referer_cards_from_references, #referers, #swap_names, #update_references_out

Methods included from Director::All

#act, #act_card, #act_card?, #clear_action_specific_attributes, #identify_action, #prepare_for_phases, #restore_changes_information, #save, #save!, #save_if_needed, #save_if_needed!, #save_needed?, #update, #update!, #valid?

Methods included from Cache::All

#ensure_view_cache_key, #expire, #view_cache_clean?

Methods included from Set::Pattern::All

#concrete_patterns, #each_type_assigning_module_key, #in_set?, #include_module?, #patterns, #patterns?, #reset_patterns, #rule_lookup_keys, #safe_set_keys, #set_format_modules, #set_modules, #set_names

Methods included from Set::Event::All

#event_applies?, #schedule

Methods included from Set::Event::SkipAndTrigger

#skip=, #skip_event!, #skip_event?, #skip_event_in_action!, #skip_hash, #skip_in_action=, #trigger=, #trigger_event!, #trigger_event?, #trigger_event_in_action!, #trigger_hash, #trigger_in_action=

Methods included from Content::All

#blank_content?, #clear_drafts, #content, #content=, #content?, #content_object, #last_draft_content, #nests?, #refresh_content, #save_content_draft, #standard_content, #standardize_content, #structured_content

Methods included from Name::All

#[], #autoname, #key, #key=, #lex, #name, #name=, #update_subcard_names, #update_superleft

Methods included from Name::All::Descendants

#child_ids, #each_child, #each_descendant, #field_cards, #field_ids, #field_names

Methods included from Name::All::Parts

#left, #left_id=, #left_or_new, #right, #right_id=, #tag, #trunk

Methods included from DirtyNames

#dirty_name, #lex_before_act, #name_before_act, #name_is_changing?

Methods included from Dirty

#attribute_before_act, #attribute_is_changing?, dirty_aliases, dirty_fields, dirty_options, #not_in_callback?

Class Method Details

.cache ⇒ Object 



5
6
7
 
# File 'lib/card/cache.rb', line 5

def cache
  Card::Cache[Card]
end

Instance Method Details

#deserialize_for_active_job!(attr) ⇒ Object 



86
87
88
89
90
91
 
# File 'lib/card/set/event/delayed_event.rb', line 86

def deserialize_for_active_job! attr
  attr.each do |attname, val|
    instance_variable_set("@#{attname}", val)
  end
  include_set_modules
end

#log_event_call(event) ⇒ Object 



177
178
179
180
181
 
# File 'lib/card/set/event.rb', line 177

def log_event_call event
  Rails.logger.debug "#{name}: #{event}"
  # puts "#{name}: #{event}"
  # puts "#{Card::Director.to_s}".green
end

#rescuing_if_integration(is_integration, &block) ⇒ Object 



163
164
165
 
# File 'lib/card/set/event.rb', line 163

def rescuing_if_integration is_integration, &block
  is_integration ? rescuing_integration(&block) : yield
end

#rescuing_integration ⇒ Object

one failed integration event should not harm others.



168
169
170
171
172
173
174
175
 
# File 'lib/card/set/event.rb', line 168

def rescuing_integration
  yield
rescue StandardError => e
  # puts "integration error: #{e.message}".red
  Card::Error.report e, self
ensure
  true
end

#serializable_attributes ⇒ Object

attributes that ActiveJob can handle

supercard and superleft are excluded, because it caused issues to have them in delayed job but not fully restored (set modules not included, attributes not retained, etc.) Since we’re supposed to have an actual left by the integrate_with_delay stage, it’s not clear that they’re needed. But if we revisit and find they are needed, then we clearly need to make sure that they are fully restored. At a bare minimum they would need to include set modules.



10
11
12
13
 
# File 'lib/card/set/event/delayed_event.rb', line 10

def serializable_attributes
  self.class.action_specific_attributes + set_specific.keys -
    %i[supercard superleft subcards]
end