Class: Subtrigger::Rule

Inherits:
Object
  • Object
show all
Defined in:
lib/subtrigger/rule.rb

Overview

A Rule object knows when to fire some kind of action for some kind of revision. When the Subversion hook is fired, a Rule can inspect it and choose whether or not to fire its trigger (a piece code defined by the user).

In the first example, the rule will output fired whenever a Revision comes along with a message containing foo.

In the second example, we find all applicable rules for a given Revision object. We can then run each of them.

Examples:

1: Define a simple Rule

Rule.new(/foo/) { puts 'fired' }

2: Finding and firing Rules

rev = Revision.new
Rule.matching(rev).map { |rule| rule.run(rev) }

Author:

  • Arjan van der Gaag

Since:

  • 0.3.0

Constant Summary collapse

CannotCompare =

Exception for when trying to apply a rule to something other than an instance of Revision.

Since:

  • 0.3.0

Class.new(Exception)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(pattern, &block) ⇒ Rule #initialize(options, &block) ⇒ Rule

Create a new Rule object with criteria for different properties of a Revision. The required block defines the callback to run. It will have the current Revision object yielded to it.

Criteria are Ruby objects that should match (‘===`) a Revision’s attributes. These would usually be regular expressions, but they can be strings or custom objects if you want to.

Overloads:

  • #initialize(pattern, &block) ⇒ Rule

    Define a rule with a pattern matching the log message

    Parameters:

    • pattern (Regex) —

      is the regular expression to match against the revision’s log message

  • #initialize(options, &block) ⇒ Rule

    Define a rule with various criteria in a hash.

    Parameters:

    • options (Hash) —

      defines matching criteria.

    Options Hash (options):

    • :author (Object) —

      Criterium for Revision#author

    • :date (Object) —

      Criterium for Revision#date

    • :number (Object) —

      Criterium for Revision#number

    • :project (Object) —

      Criterium for Revision#project

Raises:

  • (ArgumentError)

Since:

  • 0.3.0



90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/subtrigger/rule.rb', line 90

def initialize(pattern_or_options, &block)
  raise ArgumentError, 'a Rule requires a block' unless block_given?

  # If not given a hash, we build a hash defaulting on message
  unless pattern_or_options.is_a?(Hash)
    pattern_or_options = { :message => pattern_or_options }
  end

  @criteria, @block = pattern_or_options, block
  @criteria.inspect
  self.class.register self
end

Instance Attribute Details

#block ⇒ Object (readonly)

The callback to run on a match

Since:

  • 0.3.0



32
33
34
 
# File 'lib/subtrigger/rule.rb', line 32

def block
  @block
end

#criteria ⇒ Object (readonly)

A hash of Revision attributes and regular expressions to match against

Since:

  • 0.3.0



29
30
31
 
# File 'lib/subtrigger/rule.rb', line 29

def criteria
  @criteria
end

Class Method Details

.matching(revision) ⇒ Array<Rule>

Return an array of all existing Rule objects that match the given revision.

Parameters:

  • revision (Revision) —

    is the revision to compare rules to.

Returns:

  • (Array<Rule>) —

    list of all matching rules

Since:

  • 0.3.0



67
68
69
 
# File 'lib/subtrigger/rule.rb', line 67

def self.matching(revision)
  @rules.select { |child| child === revision }
end

.reset ⇒ Object

Reset the list of known rules, deleting all currently known rules.

Returns:

  • nil

Since:

  • 0.3.0



58
59
60
 
# File 'lib/subtrigger/rule.rb', line 58

def self.reset
  @rules = []
end

.rules ⇒ Array<Rule>

Return an array of all rules currently defined.

Returns:

Since:

  • 0.3.0



51
52
53
 
# File 'lib/subtrigger/rule.rb', line 51

def self.rules
  @rules
end

Instance Method Details

#===(other) ⇒ Boolean

Use #matches? to see if this Rule matches the given Revision.

Parameters:

  • the (Object) —

    object to compare to

Returns:

  • (Boolean)

See Also:

Since:

  • 0.3.0



116
117
118
119
120
 
# File 'lib/subtrigger/rule.rb', line 116

def ===(other)
  matches?(other)
rescue CannotCompare
  super
end

#matches?(revision) ⇒ Boolean

See if the current rule matches a given subversion revision.

Parameters:

  • revision (Revision) —

    the Revision object to compare to.

Returns:

  • (Boolean)

Raises:

  • Subtrigger::Rule::CannotCompare when comparing to something other than a revision.

See Also:

Since:

  • 0.3.0



129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/subtrigger/rule.rb', line 129

def matches?(revision)
  raise CannotCompare unless @criteria.keys.all? { |k| k == :all || revision.respond_to?(k) }
  match = @criteria.any?
  @criteria.each_pair do |key, value|
    if key == :all
      match = (value === revision)
    else
      match &= (value === revision.send(key.to_sym))
    end
  end
  match
end

#run(rev) ⇒ nil

Call this Rule’s callback method with the give Revision object.

Returns:

  • (nil)

Since:

  • 0.3.0



105
106
107
108
 
# File 'lib/subtrigger/rule.rb', line 105

def run(rev)
  @rev = rev
  block.call(@rev, collect_captures)
end