Class: MetaEvents::Definition::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/meta_events/definition/event.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(category, name, *args, &block) ⇒ Event

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.

Raises:

  • (ArgumentError) 


53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# 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

Instance Attribute Details

#category ⇒ Object (readonly)

Returns the value of attribute category.



15
16
17
 
# File 'lib/meta_events/definition/event.rb', line 15

def category
  @category
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



15
16
17
 
# File 'lib/meta_events/definition/event.rb', line 15

def name
  @name
end

Class Method Details

.normalize_name(name) ⇒ Object

Normalizes the name of an Event, so that we don’t run into crazy Symbol-vs.-String bugs.

Raises:

  • (ArgumentError) 


19
20
21
22
 
# 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

Instance Method Details

#category_name ⇒ Object

Returns the name of the category for an event.



99
100
101
 
# File 'lib/meta_events/definition/event.rb', line 99

def category_name
  category.name
end

#desc(text = nil) ⇒ Object

Returns, or sets, the description for an event.



81
82
83
84
 
# File 'lib/meta_events/definition/event.rb', line 81

def desc(text = nil)
  @description = text if text
  @description
end

#external_name(name = nil) ⇒ Object

Returns, or sets, an external_name to use for an event.



93
94
95
96
 
# File 'lib/meta_events/definition/event.rb', line 93

def external_name(name = nil)
  @external_name = name if name
  @external_name
end

#full_name ⇒ Object

Returns the canonical full name of an event, including all prefixes.



104
105
106
 
# File 'lib/meta_events/definition/event.rb', line 104

def full_name
  "#{category.prefix}#{name}"
end

#introduced(time = nil) ⇒ Object

Returns, or sets, the introduced-at time for an event.



87
88
89
90
 
# 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) ⇒ Object

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.

Raises:

  • (ArgumentError) 


118
119
120
121
122
123
124
125
 
# 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 ⇒ Object

Returns all notes associated with this event, as an array of Hashes.



128
129
130
 
# File 'lib/meta_events/definition/event.rb', line 128

def notes
  @notes
end

#retired_at(value = nil) ⇒ Object

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.



111
112
113
114
 
# 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 ⇒ Object

Override for clearer data.



133
134
135
 
# File 'lib/meta_events/definition/event.rb', line 133

def to_s
  "<Event #{name.inspect} of #{category}>"
end

#validate!(properties) ⇒ Object

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.



74
75
76
77
78
 
# 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