class MetaEvents::Definition::Event

Attributes

category[R]
name[R]

Public Class Methods

new(category, name, *args, &block) click to toggle source

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
normalize_name(name) click to toggle source

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

category_name() click to toggle source

Returns the name of the category for an event.

# File lib/meta_events/definition/event.rb, line 99
def category_name
  category.name
end
desc(text = nil) click to toggle source

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
external_name(name = nil) click to toggle source

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
full_name() click to toggle source

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
introduced(time = nil) click to toggle source

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
note(when_left, who, text) click to toggle source

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
notes() click to toggle source

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
retired_at(value = nil) click to toggle source

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
to_s() click to toggle source

Override for clearer data.

# File lib/meta_events/definition/event.rb, line 133
def to_s
  "<Event #{name.inspect} of #{category}>"
end
validate!(properties) click to toggle source

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

apply_args!(args) click to toggle source

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
apply_options!(options) click to toggle source

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
ensure_complete!() click to toggle source

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