Macro now can define defaults for parameters

Change-Id: Idc6688a76b80b904d24ff537a3df514b6d24b700

doc/source/changelog.rst

@@ -15,6 +15,10 @@ Features added
   * `macro-uses-global-defaults.yaml <https://review.opendev.org/c/jjb/jenkins-job-builder/+/910877/4/tests/yamlparser/job_fixtures/macro-uses-global-defaults.yaml>`_
   * `macro-uses-custom-defaults.yaml <https://review.opendev.org/c/jjb/jenkins-job-builder/+/910877/4/tests/yamlparser/job_fixtures/macro-uses-custom-defaults.yaml>`_
 
+* Macros can now define default parameters in their body the same way as jobs, job-templates and projects.
+  See this example:
+  `macro-parameter-precenence.yaml <https://review.opendev.org/c/jjb/jenkins-job-builder/+/910880/5/tests/yamlparser/job_fixtures/macro-parameter-precenence.yaml>`_
+
 .. note::
    After moving to 6.1.0 release, to remove deprecation warnings make these adjustments to your JJB sources:
 

doc/source/definition.rst

@@ -131,6 +131,8 @@ job-template.
    top of the file. Just once. This will be the value that the job takes on if
    it is not passed in by a project using the template.
 
+   And, you can do the same in `Macro`_ definitions.
+
 #. Using {var|default}
 
    In this method we can define the default with the definition of the
@@ -468,8 +470,8 @@ Defaults
 
 Defaults collect job attributes (including actions) and will supply
 those values when the job is created, unless superseded by a value in
-the 'Job'_ definition.  If a set of Defaults is specified with the
+the `Job`_ definition.  If a set of Defaults is specified with the
-name ``global``, that will be used by all `Job`_ (and `Job Template`_)
+name ``global``, that will be used by all `Job`_, `Job Template`_ and `Macro`_
 definitions unless they specify a different Default object with the
 ``defaults`` attribute.  For example::
 
@@ -485,8 +487,8 @@ You can define variables that will be realized in a `Job Template`.
 
 Would create jobs ``build-i386`` and ``build-amd64``.
 
-You can also reference a variable ``{template-name}`` in any value and it will
+In job templates, you can also reference a variable ``{template-name}`` in any value
-be subtitued by the name of the current job template being processed.
+and it will be subtitued by the name of the current job template being processed.
 
 .. _variable_references:
 

jenkins_jobs/job.py

@@ -35,18 +35,18 @@ class JobBase(RootBase):
         folder = d.pop_loc_string("folder", None)
         contents, params = split_contents_params(d, job_contents_keys)
         return cls(
-            roots.defaults,
+            _defaults=roots.defaults,
-            Expander(config),
+            _expander=Expander(config),
-            keep_descriptions,
+            _keep_descriptions=keep_descriptions,
-            id,
+            _id=id,
-            name,
+            name=name,
-            pos,
+            pos=pos,
-            description,
+            description=description,
-            defaults,
+            defaults_name=defaults,
-            params,
+            params=params,
-            contents,
+            _contents=contents,
-            project_type,
+            project_type=project_type,
-            folder,
+            folder=folder,
         )
 
     @property

jenkins_jobs/macro.py

@@ -60,23 +60,19 @@ class Macro(ElementBase):
         name = d.pop_required_loc_string("name")
         defaults = d.pop_loc_string("defaults", "global")
         elements = d.pop_required_element(elements_name)
+        params = d
         expander = Expander(config)
         str_expander = StringsOnlyExpander(config)
-        if d:
-            example_key = next(iter(d.keys()))
-            raise JenkinsJobsException(
-                f"In {type_name} macro {name!r}: unexpected elements: {','.join(d.keys())}",
-                pos=data.key_pos.get(example_key),
-            )
         macro = cls(
-            roots.defaults,
+            _defaults=roots.defaults,
-            expander,
+            _expander=expander,
-            str_expander,
+            _str_expander=str_expander,
-            type_name,
+            _type_name=type_name,
-            name,
+            name=name,
-            defaults,
+            defaults_name=defaults,
-            pos,
+            pos=pos,
-            elements or [],
+            params=params,
+            elements=elements or [],
         )
         roots.assign(roots.macros[type_name], name, macro, "macro")
 
@@ -87,6 +83,7 @@ class Macro(ElementBase):
         defaults = self._pick_defaults(self.defaults_name)
         full_params = LocDict.merge(
             defaults.params,
+            self.params,
             params,
         )
         element_list = self.elements

jenkins_jobs/root_base.py

@@ -44,6 +44,7 @@ class ElementBase:
     """Base class for YAML elements - job, view, template, or macro"""
 
     _defaults: dict
+    params: dict
 
     @property
     def title(self):
@@ -75,7 +76,6 @@ class RootBase(ElementBase):
     pos: Pos
     description: str
     defaults_name: str
-    params: dict
     _contents: dict
 
     @property

jenkins_jobs/view.py

@@ -34,17 +34,17 @@ class ViewBase(RootBase):
         view_type = d.pop_loc_string("view-type", "list")
         contents, params = split_contents_params(d, view_contents_keys)
         return cls(
-            roots.defaults,
+            _defaults=roots.defaults,
-            Expander(config),
+            _expander=Expander(config),
-            keep_descriptions,
+            _keep_descriptions=keep_descriptions,
-            id,
+            _id=id,
-            name,
+            name=name,
-            pos,
+            pos=pos,
-            description,
+            description=description,
-            defaults,
+            defaults_name=defaults,
-            params,
+            params=params,
-            contents,
+            _contents=contents,
-            view_type,
+            view_type=view_type,
         )
 
     @property

tests/yamlparser/error_fixtures/unexpected_macro_elements.error

@@ -1,3 +0,0 @@
-unexpected_macro_elements.yaml:3:5: In builder macro 'sample-builder': unexpected elements: something_unexpected
-        something_unexpected: sample-value
-        ^

tests/yamlparser/error_fixtures/unexpected_macro_elements.yaml

@@ -1,4 +0,0 @@
-- builder:
-    name: sample-builder
-    something_unexpected: sample-value
-    builders: []

tests/yamlparser/job_fixtures/macro-parameter-precenence.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <actions/>
+  <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
+  <keepDependencies>false</keepDependencies>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+  <concurrentBuild>false</concurrentBuild>
+  <canRoam>true</canRoam>
+  <properties/>
+  <scm class="hudson.scm.NullSCM"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command># 1-call
+echo param_1=1-call
+# 2-macro
+echo param_2=2-macro
+# 3-defaults
+echo param_3=3-defaults
+# 4-defaults
+echo param_4=4-defaults
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>

tests/yamlparser/job_fixtures/macro-parameter-precenence.yaml

@@ -0,0 +1,35 @@
+- defaults:
+    name: global
+    param_1: '1-defaults'
+    param_2: '2-defaults'
+    param_3: '3-defaults'
+    param_4: '4-defaults'
+
+- builder:
+    name: sample-builder
+    param_1: 1-macro
+    param_2: 2-macro
+    builders:
+    - shell: |
+        # 1-call
+        echo param_1={param_1}
+        # 2-macro
+        echo param_2={param_2}
+        # 3-defaults
+        echo param_3={param_3}
+        # 4-defaults
+        echo param_4={param_4}
+
+- job-template:
+    name: sample-job
+    param_1: '1-template'
+    param_2: '2-template'
+    param_3: '3-template'
+    builders:
+    - sample-builder:
+        param_1: 1-call
+
+- project:
+    name: test-project
+    jobs:
+    - sample-job