Create regulators ActionEnvironment class

Create the ActionEnvironment class used in the regulators action
framework.

Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: I9d5493cd9d3b8594076e5a97628b61a152c8c500
diff --git a/phosphor-regulators/meson.build b/phosphor-regulators/meson.build
index 7142616..6d04d87 100644
--- a/phosphor-regulators/meson.build
+++ b/phosphor-regulators/meson.build
@@ -1,4 +1,4 @@
-phosphor_regulators_includes = include_directories('src')
+phosphor_regulators_includes = include_directories('src', 'src/actions')
 
 subdir('src')
 subdir('test')
diff --git a/phosphor-regulators/src/actions/action_environment.hpp b/phosphor-regulators/src/actions/action_environment.hpp
new file mode 100644
index 0000000..fb34141
--- /dev/null
+++ b/phosphor-regulators/src/actions/action_environment.hpp
@@ -0,0 +1,230 @@
+/**
+ * Copyright © 2019 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#pragma once
+
+#include "device.hpp"
+#include "id_map.hpp"
+#include "rule.hpp"
+
+#include <cstddef> // for size_t
+#include <stdexcept>
+#include <string>
+
+namespace phosphor
+{
+namespace power
+{
+namespace regulators
+{
+
+/**
+ * @class ActionEnvironment
+ *
+ * The current environment when executing actions.
+ *
+ * The ActionEnvironment contains the following information:
+ *   - current device ID
+ *   - current volts value (if any)
+ *   - mapping from device and rule IDs to the corresponding objects
+ *   - rule call stack depth (to detect infinite recursion)
+ */
+class ActionEnvironment
+{
+  public:
+    // Specify which compiler-generated methods we want
+    ActionEnvironment() = delete;
+    ActionEnvironment(const ActionEnvironment&) = delete;
+    ActionEnvironment(ActionEnvironment&&) = delete;
+    ActionEnvironment& operator=(const ActionEnvironment&) = delete;
+    ActionEnvironment& operator=(ActionEnvironment&&) = delete;
+    ~ActionEnvironment() = default;
+
+    /**
+     * Maximum rule call stack depth.  Used to detect infinite recursion.
+     */
+    static constexpr size_t maxRuleDepth{30};
+
+    /**
+     * Constructor.
+     *
+     * @param idMap mapping from IDs to the associated Device/Rule objects
+     * @param deviceID current device ID
+     */
+    explicit ActionEnvironment(const IDMap& idMap,
+                               const std::string& deviceID) :
+        idMap{idMap},
+        deviceID{deviceID}
+    {
+    }
+
+    /**
+     * Decrements the rule call stack depth by one.
+     *
+     * Should be used when a call to a rule returns.  Does nothing if depth is
+     * already 0.
+     */
+    void decrementRuleDepth()
+    {
+        if (ruleDepth > 0)
+        {
+            --ruleDepth;
+        }
+    }
+
+    /**
+     * Returns the device with the current device ID.
+     *
+     * Throws invalid_argument if no device is found with current ID.
+     *
+     * @return device with current device ID
+     */
+    Device& getDevice() const
+    {
+        return idMap.getDevice(deviceID);
+    }
+
+    /**
+     * Returns the current device ID.
+     *
+     * @return current device ID
+     */
+    const std::string& getDeviceID() const
+    {
+        return deviceID;
+    }
+
+    /**
+     * Returns the rule with the specified ID.
+     *
+     * Throws invalid_argument if no rule is found with specified ID.
+     *
+     * @param id rule ID
+     * @return rule with specified ID
+     */
+    Rule& getRule(const std::string& id) const
+    {
+        return idMap.getRule(id);
+    }
+
+    /**
+     * Returns the current rule call stack depth.
+     *
+     * The depth is 0 if no rules have been called.
+     *
+     * @return rule call stack depth
+     */
+    size_t getRuleDepth() const
+    {
+        return ruleDepth;
+    }
+
+    /**
+     * Returns the current volts value.
+     *
+     * Call hasVolts() first to check whether a volts value has been set.
+     *
+     * Throws logic_error if no volts value has been set.
+     *
+     * @return current volts value
+     */
+    double getVolts() const
+    {
+        if (!hasVoltsValue)
+        {
+            throw std::logic_error{"No volts value has been set."};
+        }
+        return volts;
+    }
+
+    /**
+     * Returns whether a volts value has been set.
+     *
+     * @return true if a volts value has been set, false otherwise
+     */
+    bool hasVolts() const
+    {
+        return hasVoltsValue;
+    }
+
+    /**
+     * Increments the rule call stack depth by one.
+     *
+     * Should be used when a rule is called.
+     *
+     * Throws runtime_error if the new depth exceeds maxRuleDepth.  This
+     * indicates that infinite recursion has probably occurred (rule A -> rule B
+     * -> rule A).
+     */
+    void incrementRuleDepth()
+    {
+        if (ruleDepth >= maxRuleDepth)
+        {
+            throw std::runtime_error("Maximum rule depth exceeded.");
+        }
+        ++ruleDepth;
+    }
+
+    /**
+     * Sets the current device ID.
+     *
+     * @param id device ID
+     */
+    void setDeviceID(const std::string& id)
+    {
+        deviceID = id;
+    }
+
+    /**
+     * Sets the current volts value.
+     *
+     * @param volts new volts value.
+     */
+    void setVolts(double volts)
+    {
+        this->volts = volts;
+        hasVoltsValue = true;
+    }
+
+  private:
+    /**
+     * Mapping from string IDs to the associated Device and Rule objects.
+     */
+    const IDMap& idMap{};
+
+    /**
+     * Current device ID.
+     */
+    std::string deviceID{};
+
+    /**
+     * Indicates whether a volts value has been set.
+     */
+    bool hasVoltsValue{false};
+
+    /**
+     * Current volts value (if set).
+     */
+    double volts{0};
+
+    /**
+     * Rule call stack depth.
+     */
+    size_t ruleDepth{0};
+};
+
+} // namespace regulators
+} // namespace power
+} // namespace phosphor
diff --git a/phosphor-regulators/test/actions/action_environment_tests.cpp b/phosphor-regulators/test/actions/action_environment_tests.cpp
new file mode 100644
index 0000000..eddce87
--- /dev/null
+++ b/phosphor-regulators/test/actions/action_environment_tests.cpp
@@ -0,0 +1,273 @@
+/**
+ * Copyright © 2019 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#include "action_environment.hpp"
+#include "device.hpp"
+#include "id_map.hpp"
+#include "rule.hpp"
+
+#include <cstddef> // for size_t
+#include <exception>
+#include <stdexcept>
+
+#include <gtest/gtest.h>
+
+using namespace phosphor::power::regulators;
+
+TEST(ActionEnvironmentTests, Constructor)
+{
+    // Create IDMap
+    IDMap idMap{};
+    Device reg1{"regulator1"};
+    idMap.addDevice(reg1);
+
+    // Verify object state after constructor
+    try
+    {
+        ActionEnvironment env{idMap, "regulator1"};
+        EXPECT_EQ(env.getDevice().getID(), "regulator1");
+        EXPECT_EQ(env.getDeviceID(), "regulator1");
+        EXPECT_EQ(env.getRuleDepth(), 0);
+        EXPECT_THROW(env.getVolts(), std::logic_error);
+        EXPECT_EQ(env.hasVolts(), false);
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+}
+
+TEST(ActionEnvironmentTests, DecrementRuleDepth)
+{
+    IDMap idMap{};
+    ActionEnvironment env{idMap, ""};
+    EXPECT_EQ(env.getRuleDepth(), 0);
+    env.incrementRuleDepth();
+    env.incrementRuleDepth();
+    EXPECT_EQ(env.getRuleDepth(), 2);
+    env.decrementRuleDepth();
+    EXPECT_EQ(env.getRuleDepth(), 1);
+    env.decrementRuleDepth();
+    EXPECT_EQ(env.getRuleDepth(), 0);
+    env.decrementRuleDepth();
+    EXPECT_EQ(env.getRuleDepth(), 0);
+}
+
+TEST(ActionEnvironmentTests, GetDevice)
+{
+    // Create IDMap
+    IDMap idMap{};
+    Device reg1{"regulator1"};
+    idMap.addDevice(reg1);
+
+    ActionEnvironment env{idMap, "regulator1"};
+
+    // Test where current device ID is in the IDMap
+    try
+    {
+        Device& device = env.getDevice();
+        EXPECT_EQ(device.getID(), "regulator1");
+        EXPECT_EQ(&device, &reg1);
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+
+    // Test where current device ID is not in the IDMap
+    env.setDeviceID("regulator2");
+    try
+    {
+        env.getDevice();
+        ADD_FAILURE() << "Should not have reached this line.";
+    }
+    catch (const std::invalid_argument& ia_error)
+    {
+        EXPECT_STREQ(ia_error.what(),
+                     "Unable to find device with ID \"regulator2\"");
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+}
+
+TEST(ActionEnvironmentTests, GetDeviceID)
+{
+    IDMap idMap{};
+    ActionEnvironment env{idMap, ""};
+    EXPECT_EQ(env.getDeviceID(), "");
+    env.setDeviceID("regulator1");
+    EXPECT_EQ(env.getDeviceID(), "regulator1");
+}
+
+TEST(ActionEnvironmentTests, GetRule)
+{
+    // Create IDMap
+    IDMap idMap{};
+    Rule setVoltageRule{"set_voltage_rule"};
+    idMap.addRule(setVoltageRule);
+
+    ActionEnvironment env{idMap, ""};
+
+    // Test where rule ID is in the IDMap
+    try
+    {
+        Rule& rule = env.getRule("set_voltage_rule");
+        EXPECT_EQ(rule.getID(), "set_voltage_rule");
+        EXPECT_EQ(&rule, &setVoltageRule);
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+
+    // Test where rule ID is not in the IDMap
+    try
+    {
+        env.getRule("set_voltage_rule2");
+        ADD_FAILURE() << "Should not have reached this line.";
+    }
+    catch (const std::invalid_argument& ia_error)
+    {
+        EXPECT_STREQ(ia_error.what(),
+                     "Unable to find rule with ID \"set_voltage_rule2\"");
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+}
+
+TEST(ActionEnvironmentTests, GetRuleDepth)
+{
+    IDMap idMap{};
+    ActionEnvironment env{idMap, ""};
+    EXPECT_EQ(env.getRuleDepth(), 0);
+    env.incrementRuleDepth();
+    EXPECT_EQ(env.getRuleDepth(), 1);
+    env.incrementRuleDepth();
+    EXPECT_EQ(env.getRuleDepth(), 2);
+    env.decrementRuleDepth();
+    EXPECT_EQ(env.getRuleDepth(), 1);
+    env.decrementRuleDepth();
+    EXPECT_EQ(env.getRuleDepth(), 0);
+}
+
+TEST(ActionEnvironmentTests, GetVolts)
+{
+    IDMap idMap{};
+    ActionEnvironment env{idMap, ""};
+    EXPECT_EQ(env.hasVolts(), false);
+
+    // Test where a volts value has not been set
+    try
+    {
+        env.getVolts();
+    }
+    catch (const std::logic_error& l_error)
+    {
+        EXPECT_STREQ(l_error.what(), "No volts value has been set.");
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+
+    // Test where a volts value has been set
+    env.setVolts(1.31);
+    try
+    {
+        double volts = env.getVolts();
+        EXPECT_EQ(volts, 1.31);
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+}
+
+TEST(ActionEnvironmentTests, HasVolts)
+{
+    IDMap idMap{};
+    ActionEnvironment env{idMap, ""};
+    EXPECT_EQ(env.hasVolts(), false);
+    env.setVolts(1.31);
+    EXPECT_EQ(env.hasVolts(), true);
+}
+
+TEST(ActionEnvironmentTests, IncrementRuleDepth)
+{
+    IDMap idMap{};
+    ActionEnvironment env{idMap, ""};
+    EXPECT_EQ(env.getRuleDepth(), 0);
+
+    // Test where rule depth has not exceeded maximum
+    try
+    {
+        for (size_t i = 1; i <= env.maxRuleDepth; ++i)
+        {
+            env.incrementRuleDepth();
+            EXPECT_EQ(env.getRuleDepth(), i);
+        }
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+
+    // Test where rule depth has exceeded maximum
+    try
+    {
+        env.incrementRuleDepth();
+    }
+    catch (const std::runtime_error& r_error)
+    {
+        EXPECT_STREQ(r_error.what(), "Maximum rule depth exceeded.");
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+}
+
+TEST(ActionEnvironmentTests, SetDeviceID)
+{
+    IDMap idMap{};
+    Device reg1{"regulator1"};
+    idMap.addDevice(reg1);
+    ActionEnvironment env{idMap, "regulator1"};
+
+    EXPECT_EQ(env.getDeviceID(), "regulator1");
+    env.setDeviceID("regulator2");
+    EXPECT_EQ(env.getDeviceID(), "regulator2");
+}
+
+TEST(ActionEnvironmentTests, SetVolts)
+{
+    try
+    {
+        IDMap idMap{};
+        ActionEnvironment env{idMap, ""};
+        EXPECT_EQ(env.hasVolts(), false);
+        env.setVolts(2.35);
+        EXPECT_EQ(env.hasVolts(), true);
+        EXPECT_EQ(env.getVolts(), 2.35);
+    }
+    catch (const std::exception& error)
+    {
+        ADD_FAILURE() << "Should not have caught exception.";
+    }
+}
diff --git a/phosphor-regulators/test/actions/meson.build b/phosphor-regulators/test/actions/meson.build
new file mode 100644
index 0000000..8c3d2b8
--- /dev/null
+++ b/phosphor-regulators/test/actions/meson.build
@@ -0,0 +1,11 @@
+test('phosphor-regulators-actions-tests',
+     executable('phosphor-regulators-actions-tests',
+                'action_environment_tests.cpp',
+                dependencies: [
+                    gmock,
+                    gtest,
+                ],
+                implicit_include_directories: false,
+                include_directories: phosphor_regulators_includes,
+     )
+)
diff --git a/phosphor-regulators/test/meson.build b/phosphor-regulators/test/meson.build
index c89e689..fdf8c00 100644
--- a/phosphor-regulators/test/meson.build
+++ b/phosphor-regulators/test/meson.build
@@ -13,4 +13,4 @@
      )
 )
 
-# subdir('actions')
+subdir('actions')