class MetaEvents::Definition::Event
Attributes
Public Class Methods
Creates a new instance. category
must be the ::MetaEvents::Definition::Category
that this event is part of; name
must be the name of the event.
In order to create a new instance, you must also supply a description for the instance and indicate when it was introduced; this is part of the required record-keeping that makes the MetaEvents
DSL useful. You can do this in one of several ways (expressed as it would look in the DSL):
category :user do event :signup, "2014-01-01", "a new user we've never heard of before signs up" end
or:
category :user do event :signup, :introduced => "2014-01-01", :desc => "a new user we've never heard of before signs up" end
or:
category :user do event :signup do introduced "2014-01-01" desc "a new user we've never heard of before signs up" end end
You can also combine these in any way you want; what's important is just that they get set, or else you'll get an exception at definition time.
# File lib/meta_events/definition/event.rb, line 53 def initialize(category, name, *args, &block) raise ArgumentError, "Must supply a Category, not #{category.inspect}" unless category.kind_of?(::MetaEvents::Definition::Category) @category = category @name = self.class.normalize_name(name) @notes = [ ] apply_options!(args.extract_options!) args = apply_args!(args) raise ArgumentError, "Too many arguments: don't know what to do with #{args.inspect}" if args.present? instance_eval(&block) if block ensure_complete! end
Normalizes the name of an Event
, so that we don't run into crazy Symbol-vs.-String bugs.
# File lib/meta_events/definition/event.rb, line 19 def normalize_name(name) raise ArgumentError, "Must supply a name for an event, not: #{name.inspect}" if name.blank? name.to_s.strip.downcase.to_sym end
Public Instance Methods
Returns the name of the category for an event.
# File lib/meta_events/definition/event.rb, line 99 def category_name category.name end
Returns, or sets, the description for an event.
# File lib/meta_events/definition/event.rb, line 81 def desc(text = nil) @description = text if text @description end
Returns, or sets, an external_name
to use for an event.
# File lib/meta_events/definition/event.rb, line 93 def external_name(name = nil) @external_name = name if name @external_name end
Returns the canonical full name of an event, including all prefixes.
# File lib/meta_events/definition/event.rb, line 104 def full_name "#{category.prefix}#{name}" end
Returns, or sets, the introduced-at time for an event.
# File lib/meta_events/definition/event.rb, line 87 def introduced(time = nil) @introduced = Time.parse(time) if time @introduced end
Adds a note to this event. Notes are simply metadata right now – useful for indicating what the history of an event is, significant changes in its meaning, and so on.
# File lib/meta_events/definition/event.rb, line 118 def note(when_left, who, text) raise ArgumentError, "You must specify when this note was left" if when_left.blank? when_left = Time.parse(when_left) raise ArgumentError, "You must specify who left this note" if who.blank? raise ArgumentError, "You must specify an actual note" if text.blank? @notes << { :when_left => when_left, :who => who, :text => text } end
Returns all notes associated with this event, as an array of Hashes.
# File lib/meta_events/definition/event.rb, line 128 def notes @notes end
Returns the time at which this event has been retired, if any – this is the earliest time from its category (which, in turn, is the earliest of the category and the version), and this event. If an event has been retired, then validate!
will fail.
# File lib/meta_events/definition/event.rb, line 111 def retired_at(value = nil) @retired_at = Time.parse(value) if value [ @retired_at, category.retired_at ].compact.min end
Override for clearer data.
# File lib/meta_events/definition/event.rb, line 133 def to_s "<Event #{name.inspect} of #{category}>" end
Given a set of properties, validates this event – that is, either returns without doing anything if everything is OK, or raises an exception if the event should not be allowed to be fired. Currently, all we do is fail if the event has been retired (directly, or via its Category
or Version
); however, this could easily be extended to provide for required properties, property validation, or anything else.
# File lib/meta_events/definition/event.rb, line 74 def validate!(properties) if retired_at raise ::MetaEvents::Definition::DefinitionSet::RetiredEventError, "Event #{full_name} was retired at #{retired_at.inspect} (or its category or version was); you can't use it any longer." end end
Private Instance Methods
Called with the arguments (past the category and event name) supplied to the constructor; responsible for applying those to the object properly.
# File lib/meta_events/definition/event.rb, line 160 def apply_args!(args) intro = args.shift d = args.shift introduced intro if intro desc d if d args end
Called with the set of options (which can be empty) supplied in the constructor; responsible for applying those to the object properly.
# File lib/meta_events/definition/event.rb, line 147 def apply_options!(options) options.assert_valid_keys(:introduced, :desc, :description, :retired_at, :external_name) introduced options[:introduced] if options[:introduced] desc options[:desc] if options[:desc] desc options[:description] if options[:description] external_name options[:external_name] if options[:external_name] @retired_at = Time.parse(options[:retired_at]) if options[:retired_at] end
Called at the very end of the constructor, to ensure that you have declared all required properties for this event.
# File lib/meta_events/definition/event.rb, line 140 def ensure_complete! raise ArgumentError, "You must specify a description for event #{full_name}, either as an argument, in the options, or using 'desc'" if @description.blank? raise ArgumentError, "You must record when you introduced event #{full_name}, either as an argument, in the options, or using 'introduced'" if (! @introduced) end