Merge pull request #776 from deltalejo/fix/tools-array

Update Command Hooks plugin to follow pattern of other revised plugins and add support for multiple tools per hook

assets/project_as_gem.yml

@@ -306,6 +306,29 @@
 #      :build_root: ./subprojectA/build
 #      :defines: []
 
+# :command_hooks:
+#   :pre_mock_preprocess:
+#   :post_mock_preprocess:
+#   :pre_test_preprocess:
+#   :post_test_preprocess:
+#   :pre_mock_generate:
+#   :post_mock_generate:
+#   :pre_runner_generate:
+#   :post_runner_generate:
+#   :pre_compile_execute:
+#   :post_compile_execute:
+#   :pre_link_execute:
+#   :post_link_execute:
+#   :pre_test_fixture_execute:
+#   :post_test_fixture_execute:
+#   :pre_test:
+#   :post_test:
+#   :pre_release:
+#   :post_release:
+#   :pre_build:
+#   :post_build:
+#   :post_error:
+
 ################################################################
 # TOOLCHAIN CONFIGURATION
 ################################################################
@@ -375,25 +398,4 @@
 #     :arguments: []
 #     :name: 
 #     :optional: FALSE
-# #These tools can be filled out when command_hooks plugin is enabled
-#   :pre_mock_preprocess
-#   :post_mock_preprocess
-#   :pre_mock_generate
-#   :post_mock_generate
-#   :pre_runner_preprocess
-#   :post_runner_preprocess
-#   :pre_runner_generate
-#   :post_runner_generate
-#   :pre_compile_execute
-#   :post_compile_execute
-#   :pre_link_execute
-#   :post_link_execute
-#   :pre_test_fixture_execute
-#   :pre_test
-#   :post_test
-#   :pre_release
-#   :post_release
-#   :pre_build
-#   :post_build
-#   :post_error
 ...

assets/project_with_guts.yml

@@ -306,6 +306,29 @@
 #      :build_root: ./subprojectA/build
 #      :defines: []
 
+# :command_hooks:
+#   :pre_mock_preprocess:
+#   :post_mock_preprocess:
+#   :pre_test_preprocess:
+#   :post_test_preprocess:
+#   :pre_mock_generate:
+#   :post_mock_generate:
+#   :pre_runner_generate:
+#   :post_runner_generate:
+#   :pre_compile_execute:
+#   :post_compile_execute:
+#   :pre_link_execute:
+#   :post_link_execute:
+#   :pre_test_fixture_execute:
+#   :post_test_fixture_execute:
+#   :pre_test:
+#   :post_test:
+#   :pre_release:
+#   :post_release:
+#   :pre_build:
+#   :post_build:
+#   :post_error:
+
 ################################################################
 # TOOLCHAIN CONFIGURATION
 ################################################################
@@ -376,25 +399,4 @@
 #     :arguments: []
 #     :name: 
 #     :optional: FALSE
-# #These tools can be filled out when command_hooks plugin is enabled
-#   :pre_mock_preprocess
-#   :post_mock_preprocess
-#   :pre_mock_generate
-#   :post_mock_generate
-#   :pre_runner_preprocess
-#   :post_runner_preprocess
-#   :pre_runner_generate
-#   :post_runner_generate
-#   :pre_compile_execute
-#   :post_compile_execute
-#   :pre_link_execute
-#   :post_link_execute
-#   :pre_test_fixture_execute
-#   :pre_test
-#   :post_test
-#   :pre_release
-#   :post_release
-#   :pre_build
-#   :post_build
-#   :post_error
 ...

docs/BreakingChanges.md

@@ -160,6 +160,9 @@ In addition, a previously undocumented feature for merging a second configuratio
 
 Thorough documentation on Mixins and the new options for loading a project configuration can be found in _[CeedlingPacket](CeedlingPacket.md))_.
 
+## `command_hooks` plugin tools configuration
+
+Previously, Command Hooks tools were defined under `:tools` section, now they must be defined under top-level `:command_hooks` section in project configuration.
 
 # Subprojects Plugin Replaced
 
@@ -206,4 +209,4 @@ The above subproject definition will now look like the following:
       :defines: 
         - DEFINE_JUST_FOR_THIS_FILE
         - AND_ANOTHER
-```
+```

examples/temp_sensor/project.yml

@@ -254,6 +254,29 @@
 #      :build_root: ./subprojectA/build
 #      :defines: []
 
+# :command_hooks:
+#   :pre_mock_preprocess:
+#   :post_mock_preprocess:
+#   :pre_test_preprocess:
+#   :post_test_preprocess:
+#   :pre_mock_generate:
+#   :post_mock_generate:
+#   :pre_runner_generate:
+#   :post_runner_generate:
+#   :pre_compile_execute:
+#   :post_compile_execute:
+#   :pre_link_execute:
+#   :post_link_execute:
+#   :pre_test_fixture_execute:
+#   :post_test_fixture_execute:
+#   :pre_test:
+#   :post_test:
+#   :pre_release:
+#   :post_release:
+#   :pre_build:
+#   :post_build:
+#   :post_error:
+
 ################################################################
 # TOOLCHAIN CONFIGURATION
 ################################################################
@@ -324,25 +347,4 @@
 #     :arguments: []
 #     :name: 
 #     :optional: FALSE
-# #These tools can be filled out when command_hooks plugin is enabled
-#   :pre_mock_preprocess
-#   :post_mock_preprocess
-#   :pre_mock_generate
-#   :post_mock_generate
-#   :pre_runner_preprocess
-#   :post_runner_preprocess
-#   :pre_runner_generate
-#   :post_runner_generate
-#   :pre_compile_execute
-#   :post_compile_execute
-#   :pre_link_execute
-#   :post_link_execute
-#   :pre_test_fixture_execute
-#   :pre_test
-#   :post_test
-#   :pre_release
-#   :post_release
-#   :pre_build
-#   :post_build
-#   :post_error
 ...

plugins/command_hooks/README.md

@@ -22,14 +22,14 @@ To connect a utilties or scripts to build step hooks, Ceedling tools must be def
 
 A Ceedling tool is just a YAML blob that gathers together a handful of settings and values that tell Ceedling how to build and execute a command line. Your tool can be a command line utility, a script, etc.
 
-Example Ceedling tools follow. Their tool entry names correspond to the build step hooks listed later in this document. That's how this plugin works. When enabled, it ensures any tools you define are executed by the corresponding build step hook that shares their name.
+Example Ceedling tools follow. Their tool entry names correspond to the build step hooks listed later in this document. That's how this plugin works. When enabled, it ensures any tools you define are executed by the corresponding build step hook that shares their name. The build step hook tool entry can be either a Ceedling tool or a list of them.
 
-Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See _[CeedlingPacket][ceedling-packet]_ documentation for `:tools` entries to understand how to craft your argument list and other tool options.
+Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See _[CeedlingPacket][ceedling-packet]_ documentation for [`:tools`](https://github.com/ThrowTheSwitch/Ceedling/blob/test/ceedling_0_32_rc/docs/CeedlingPacket.md#tools-configuring-command-line-tools-used-for-build-steps) entries to understand how to craft your argument list and other tool options.
 
 At present, this plugin only passes at most one runtime parameter for a given build step hook for use in a tool's argument list (from among the many processed by Ceedling's plugin framework). If available, this parameter can be referenced with a Ceedling tool argument expansion identifier `${1}`. That is, wherever you place `${1}` in your tool argument list, `${1}` will expand in the command line Ceedling constructs with the parameter this plugin provides for that build step hook. The list of build steps hooks below document any single parameters they provide at execution.
 
 ```yaml
-:tools:
+:command_hooks:
   # Called every time a mock is generated
   # Who knows what my_script.py does -- sky is the limit
   :pre_mock_generate:
@@ -40,18 +40,26 @@ At present, this plugin only passes at most one runtime parameter for a given bu
       - ${1} # Replaced with the filepath of the header file that will be mocked
       
   # Called after each linking operation
-  # Here, we are converting a binary executable to S-record format
+  # Here, we are performing two task on the same build step hook, converting a
+  # binary executable to S-record format and then, zipping it along with some
+  # other files like linker's memory allocation/usage report and so on.
   :post_link_execute:
-    :executable: objcopy.exe
-    :arguments:
-      - ${1} # Replaced with the filepath to the linker's binary artifact output
-      - output.srec
-      - --strip-all
+    - :executable: objcopy.exe
+      :arguments:
+        - ${1} # Replaced with the filepath to the linker's binary artifact output
+        - output.srec
+        - --strip-all
+    - :executable: 
+      :arguments: tar.exe
+        - -acf
+        - awesome_build.zip
+        - ${1} # Replaced with the filepath to the linker's binary artifact output
+        - memory_report.txt
 ```
 
 # Available Build Step Hooks
 
-Define any of the following entries within the `:tools:` section of your Ceedling project file to automagically connect utilities or scripts to build process steps.
+Define any of the following entries within the `:command_hooks:` section of your Ceedling project file to automagically connect utilities or scripts to build process steps.
 
 Some hooks are called for every file-related operation for which the hook is named. Other hooks are triggered by single build step for which the hook is named.
 

plugins/command_hooks/lib/command_hooks.rb

@@ -5,36 +5,64 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-require 'ceedling/plugin'
 require 'ceedling/constants'
-class CommandHooks < Plugin
+require 'ceedling/exceptions'
+require 'ceedling/plugin'
+
+COMMAND_HOOKS_ROOT_NAME = 'command_hooks'.freeze
+COMMAND_HOOKS_SYM       = COMMAND_HOOKS_ROOT_NAME.to_sym
 
-  attr_reader :config
+COMMAND_HOOKS_LIST = [
+  :pre_mock_preprocess,
+  :post_mock_preprocess,
+  :pre_test_preprocess,
+  :post_test_preprocess,
+  :pre_mock_generate,
+  :post_mock_generate,
+  :pre_runner_generate,
+  :post_runner_generate,
+  :pre_compile_execute,
+  :post_compile_execute,
+  :pre_link_execute,
+  :post_link_execute,
+  :pre_test_fixture_execute,
+  :post_test_fixture_execute,
+  :pre_test,
+  :post_test,
+  :pre_release,
+  :post_release,
+  :pre_build,
+  :post_build,
+  :post_error,
+].freeze
+
+class CommandHooks < Plugin
 
   def setup
-    @config = {
-      :pre_mock_preprocess       => ((defined? TOOLS_PRE_MOCK_PREPROCESS)       ? TOOLS_PRE_MOCK_PREPROCESS       : nil ),
-      :post_mock_preprocess      => ((defined? TOOLS_POST_MOCK_PREPROCESS)      ? TOOLS_POST_MOCK_PREPROCESS      : nil ),
-      :pre_test_preprocess       => ((defined? TOOLS_PRE_TEST_PREPROCESS)       ? TOOLS_PRE_TEST_PREPROCESS       : nil ),
-      :post_test_preprocess      => ((defined? TOOLS_POST_TEST_PREPROCESS)      ? TOOLS_POST_TEST_PREPROCESS      : nil ),
-      :pre_mock_generate         => ((defined? TOOLS_PRE_MOCK_GENERATE)         ? TOOLS_PRE_MOCK_GENERATE         : nil ),
-      :post_mock_generate        => ((defined? TOOLS_POST_MOCK_GENERATE)        ? TOOLS_POST_MOCK_GENERATE        : nil ),
-      :pre_runner_generate       => ((defined? TOOLS_PRE_RUNNER_GENERATE)       ? TOOLS_PRE_RUNNER_GENERATE       : nil ),
-      :post_runner_generate      => ((defined? TOOLS_POST_RUNNER_GENERATE)      ? TOOLS_POST_RUNNER_GENERATE      : nil ),
-      :pre_compile_execute       => ((defined? TOOLS_PRE_COMPILE_EXECUTE)       ? TOOLS_PRE_COMPILE_EXECUTE       : nil ),
-      :post_compile_execute      => ((defined? TOOLS_POST_COMPILE_EXECUTE)      ? TOOLS_POST_COMPILE_EXECUTE      : nil ),
-      :pre_link_execute          => ((defined? TOOLS_PRE_LINK_EXECUTE)          ? TOOLS_PRE_LINK_EXECUTE          : nil ),
-      :post_link_execute         => ((defined? TOOLS_POST_LINK_EXECUTE)         ? TOOLS_POST_LINK_EXECUTE         : nil ),
-      :pre_test_fixture_execute  => ((defined? TOOLS_PRE_TEST_FIXTURE_EXECUTE)  ? TOOLS_PRE_TEST_FIXTURE_EXECUTE  : nil ),
-      :post_test_fixture_execute => ((defined? TOOLS_POST_TEST_FIXTURE_EXECUTE) ? TOOLS_POST_TEST_FIXTURE_EXECUTE : nil ),
-      :pre_test                  => ((defined? TOOLS_PRE_TEST)                  ? TOOLS_PRE_TEST                  : nil ),
-      :post_test                 => ((defined? TOOLS_POST_TEST)                 ? TOOLS_POST_TEST                 : nil ),
-      :pre_release               => ((defined? TOOLS_PRE_RELEASE)               ? TOOLS_PRE_RELEASE               : nil ),
-      :post_release              => ((defined? TOOLS_POST_RELEASE)              ? TOOLS_POST_RELEASE              : nil ),
-      :pre_build                 => ((defined? TOOLS_PRE_BUILD)                 ? TOOLS_PRE_BUILD                 : nil ),
-      :post_build                => ((defined? TOOLS_POST_BUILD)                ? TOOLS_POST_BUILD                : nil ),
-      :post_error                => ((defined? TOOLS_POST_ERROR)                ? TOOLS_POST_ERROR                : nil ),
-    }
+    project_config = @ceedling[:setupinator].config_hash
+
+    config_exists = @ceedling[:configurator_validator].exists?(
+      project_config,
+      COMMAND_HOOKS_SYM
+    )
+
+    unless config_exists
+      name = @ceedling[:reportinator].generate_config_walk([COMMAND_HOOKS_SYM])
+      error = "Missing configuration #{name}"
+      raise CeedlingException.new(error)
+    end
+
+    @config = project_config[COMMAND_HOOKS_SYM]
+
+    validate_config(@config)
+
+    @config.each do |hook, tool|
+      if tool.is_a?(Array)
+        tool.each_index {|index| validate_hook_tool(project_config, hook, index)}
+      else
+        validate_hook_tool(project_config, hook)
+      end
+    end
   end
 
   def pre_mock_preprocess(arg_hash);       run_hook( :pre_mock_preprocess,       arg_hash[:header_file] ); end
@@ -60,7 +88,62 @@ def post_build;                          run_hook( :post_build
   def post_error;                          run_hook( :post_error                                        ); end
 
   private
-
+
+  ##
+  # Validate plugin configuration.
+  #
+  # :args:
+  #   - config: :command_hooks section from project config hash
+  #
+  def validate_config(config)
+    unless config.is_a?(Hash)
+      name = @ceedling[:reportinator].generate_config_walk([COMMAND_HOOKS_SYM])
+      error = "Expected configuration #{name} to be a Hash but found #{config.class}"
+      raise CeedlingException.new(error)
+    end
+
+    unknown_hooks = config.keys - COMMAND_HOOKS_LIST
+
+    unknown_hooks.each do |not_a_hook|
+      name = @ceedling[:reportinator].generate_config_walk([COMMAND_HOOKS_SYM, not_a_hook])
+      error = "Unrecognized option: #{name}"
+      @ceedling[:loginator].log(error, Verbosity::ERRORS)
+    end
+
+    unless unknown_hooks.empty?
+      error = "Unrecognized hooks have been found in project configuration"
+      raise CeedlingException.new(error)
+    end
+  end
+
+  ##
+  # Validate given hook tool.
+  #
+  # :args:
+  #   - config: Project configuration hash
+  #   - keys: Key and index of hook inside :command_hooks configuration
+  #
+  def validate_hook_tool(config, *keys)
+    walk = [COMMAND_HOOKS_SYM, *keys]
+    name = @ceedling[:reportinator].generate_config_walk(walk)
+    hash = @ceedling[:config_walkinator].fetch_value(config, *walk)
+
+    tool_exists = @ceedling[:configurator_validator].exists?(config, *walk)
+
+    unless tool_exists
+      raise CeedlingException.new("Missing configuration #{name}")
+    end
+
+    tool = hash[:value]
+
+    unless tool.is_a?(Hash)
+      error = "Expected configuration #{name} to be a Hash but found #{tool.class}"
+      raise CeedlingException.new(error)
+    end
+
+    @ceedling[:tool_validator].validate(tool: tool, name: name, boom: true)
+  end
+
   ##
   # Run a hook if its available.
   #
@@ -110,4 +193,3 @@ def run_hook(which_hook, name="")
     end
   end
 end
-