Implement getters for actions

We need a way to access information about actions, such as how many
times they will be trigger or what is their interval.  The getters in
this patch provide API methods for obtaining that information.  Now
programmers using Luvent can have easier access to information about
actions without having to dig into the ‘hands-off’ private details of
the implementation itself.

CHANGELOG.md

@@ -5,6 +5,13 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 
 
+## [v1.2.0] - 2015-02-23
+
+### Added
+
+- Getters for various action properties.
+
+
 ## [v1.1.0] - 2015-02-17
 
 ### Added
@@ -36,6 +43,7 @@ First public release.
 
 
 
+[v1.2.0]: https://github.com/ejmr/Luvent/releases/tag/v1.2.0
 [v1.1.0]: https://github.com/ejmr/Luvent/releases/tag/v1.1.0
 [v1.0.0]: https://github.com/ejmr/Luvent/releases/tag/v1.0.0
 [busted]: http://olivinelabs.com/busted/

README.md

@@ -360,6 +360,19 @@ only invoke the second action.  Once an action reaches its limit then
 Luvent effectively calls `removeAction()`, meaning you would have to
 manually re-add the action before the event would use it again.
 
+### Getters ###
+
+Luvent gives you three getters for obtaining information about
+actions:
+
+1. `getActionTriggerLimit(action_or_id)`
+2. `getActionInterval(action_or_id)`
+3. `getActionPriority(action_or_id)`
+
+This methods complement the setters above and help you gain insight
+into the behavior of an action, e.g. how many times it will be
+triggered before being disabled.
+
 ### Looping Over Actions ###
 
 The API provides two methods for looping through all of the actions
@@ -417,6 +430,9 @@ returns an object with the following methods:
 * `removeActionInterval(action_or_id)`
 * `allActions()`
 * `forEachAction(callable)`
+* `getActionTriggerLimit(action_or_id)`
+* `getActionInterval(action_or_id)`
+* `getActionPriority(action_or_id)`
 
 
 Acknowledgments and Alternatives

src/Luvent.lua

@@ -218,9 +218,9 @@ end
 -- @param event The event with the actions we sort.
 local function sortActionsByPriority(event)
     table.sort(event.actions,
-        function (a1, a2)
-            return a1.priority > a2.priority
-        end)
+               function (a1, a2)
+                   return a1.priority > a2.priority
+    end)
 end
 
 --- Add an action to an event.
@@ -393,6 +393,28 @@ local function createActionSetter(property, valueType, default)
     end
 end
 
+--- Creates an action getter method.
+--
+-- This utility returns a function that creates a getter
+-- for the given property name.
+--
+-- @param property The action property to return from the getter.
+--
+-- @return A method of two arguments: an event and an action (or id).
+-- It will return the property given above for that action.
+--
+-- @see Luvent:getActionInterval
+-- @see Luvent:getActionTriggerLimit
+-- @see Luvent:getActionPriority
+local function createActionGetter(property)
+    return function (event, action)
+        local exists,index = findAction(event, action)
+        assert(exists)
+        assert(event.actions[index][property])
+        return event.actions[index][property]
+    end
+end
+
 --- Modify the interval of an action.
 --
 -- This method lets us change an action to adhere to an interval, i.e.
@@ -408,6 +430,16 @@ end
 -- @name Luvent:setActionInterval
 Luvent.setActionInterval = createActionSetter("interval", "number")
 
+--- Gets the interval for an action.
+--
+-- @param actionToFind The action whose interval to find.
+--
+-- @return The interval as a number.
+--
+-- @class function
+-- @name Luvent:getActionInterval
+Luvent.getActionInterval = createActionGetter("interval")
+
 --- Remove the interval of an action.
 --
 -- This method will remove an interval from the given action if it has
@@ -436,6 +468,16 @@ Luvent.removeActionInterval = createActionSetter("interval", "number", 0)
 -- @name Luvent:setActionPriority
 Luvent.setActionPriority = createActionSetter("priority", "number")
 
+--- Get the priority for an action.
+--
+-- @param actionToFind The action whose priority to return.
+--
+-- @return The action's priority as a number.
+--
+-- @class function
+-- @name Luvent:getActionPriority
+Luvent.getActionPriority = createActionGetter("priority")
+
 --- Remove the priority of an action.
 --
 -- This method will get rid of the action's priority setting, meaning
@@ -512,6 +554,18 @@ function Luvent:setActionTriggerLimit(actionToFind, limit)
     end
 end
 
+--- Gets the trigger limit for an action.
+--
+-- @param actionToFind The action whose limit to return.
+--
+-- @return The trigger limit as a number.
+function Luvent:getActionTriggerLimit(actionToFind)
+    local exists,index = findAction(self, actionToFind)
+    assert(exists)
+    assert(self.actions[index].limit)
+    return self.actions[index].limit
+end
+
 --- Remove any limit on an action.
 --
 -- This method gets rid of any limit placed on an action.  If the

tests/Luvent.spec.lua

@@ -241,6 +241,33 @@ describe("Basic action management", function ()
 
 end)
 
+describe("Action getters", function ()
+
+    local event
+    local noop = function () end
+
+    before_each(function ()
+        event = Luvent.newEvent()
+        event:addAction(noop)
+        event:setActionTriggerLimit(noop, 10)
+        event:setActionInterval(noop, 3)
+        event:setActionPriority(noop, 5)
+    end)
+
+    it("Can get the action limit", function ()
+        assert.are.equal(event:getActionTriggerLimit(noop), 10)
+    end)
+
+    it("Can get the action interval", function ()
+        assert.are.equal(event:getActionInterval(noop), 3)
+    end)
+
+    it("Can get the action priority", function ()
+        assert.are.equal(event:getActionPriority(noop), 5)
+    end)
+
+end)
+
 describe("Triggering events", function ()
 
     local onClickEvent