Introduce new 'required_by' argument_spec option (#28662)

* Introduce new "required_by' argument_spec option

This PR introduces a new **required_by** argument_spec option which allows you to say *"if parameter A is set, parameter B and C are required as well"*.

- The difference with **required_if** is that it can only add dependencies if a parameter is set to a specific value, not when it is just defined.
- The difference with **required_together** is that it has a commutative property, so: *"Parameter A and B are required together, if one of them has been defined"*.

As an example, we need this for the complex options that the xml module provides. One of the issues we often see is that users are not using the correct combination of options, and then are surprised that the module does not perform the requested action(s).

This would be solved by adding the correct dependencies, and mutual exclusives. For us this is important to get this shipped together with the new xml module in Ansible v2.4. (This is related to bugfix https://github.com/ansible/ansible/pull/28657)

```python
    module = AnsibleModule(
        argument_spec=dict(
            path=dict(type='path', aliases=['dest', 'file']),
            xmlstring=dict(type='str'),
            xpath=dict(type='str'),
            namespaces=dict(type='dict', default={}),
            state=dict(type='str', default='present', choices=['absent',
'present'], aliases=['ensure']),
            value=dict(type='raw'),
            attribute=dict(type='raw'),
            add_children=dict(type='list'),
            set_children=dict(type='list'),
            count=dict(type='bool', default=False),
            print_match=dict(type='bool', default=False),
            pretty_print=dict(type='bool', default=False),
            content=dict(type='str', choices=['attribute', 'text']),
            input_type=dict(type='str', default='yaml', choices=['xml',
'yaml']),
            backup=dict(type='bool', default=False),
        ),
        supports_check_mode=True,
        required_by=dict(
            add_children=['xpath'],
            attribute=['value', 'xpath'],
            content=['xpath'],
            set_children=['xpath'],
            value=['xpath'],
        ),
        required_if=[
            ['count', True, ['xpath']],
            ['print_match', True, ['xpath']],
        ],
        required_one_of=[
            ['path', 'xmlstring'],
            ['add_children', 'content', 'count', 'pretty_print', 'print_match', 'set_children', 'value'],
        ],
        mutually_exclusive=[
            ['add_children', 'content', 'count', 'print_match','set_children', 'value'],
            ['path', 'xmlstring'],
        ],
    )
```

* Rebase and fix conflict

* Add modules that use required_by functionality

* Update required_by schema

* Fix rebase issue

lib/ansible/module_utils/basic.py

@@ -748,7 +748,7 @@ class AnsibleModule(object):
     def __init__(self, argument_spec, bypass_checks=False, no_log=False,
                  check_invalid_arguments=None, mutually_exclusive=None, required_together=None,
                  required_one_of=None, add_file_common_args=False, supports_check_mode=False,
-                 required_if=None):
+                 required_if=None, required_by=None):
 
         '''
         Common code for quickly building an ansible module in Python
@@ -777,6 +777,7 @@ class AnsibleModule(object):
         self.required_together = required_together
         self.required_one_of = required_one_of
         self.required_if = required_if
+        self.required_by = required_by
         self.cleanup_files = []
         self._debug = False
         self._diff = False
@@ -848,6 +849,7 @@ class AnsibleModule(object):
             self._check_required_together(required_together)
             self._check_required_one_of(required_one_of)
             self._check_required_if(required_if)
+            self._check_required_by(required_by)
 
         self._set_defaults(pre=False)
 
@@ -1706,6 +1708,24 @@ class AnsibleModule(object):
                         msg += " found in %s" % " -> ".join(self._options_context)
                     self.fail_json(msg=msg)
 
+    def _check_required_by(self, spec, param=None):
+        if spec is None:
+            return
+        if param is None:
+            param = self.params
+        for (key, value) in spec.items():
+            if key not in param or param[key] is None:
+                continue
+            missing = []
+            # Support strings (single-item lists)
+            if isinstance(value, string_types):
+                value = [value, ]
+            for required in value:
+                if required not in param or param[required] is None:
+                    missing.append(required)
+            if len(missing) > 0:
+                self.fail_json(msg="missing parameter(s) required by '%s': %s" % (key, ', '.join(missing)))
+
     def _check_required_arguments(self, spec=None, param=None):
         ''' ensure all required arguments are present '''
         missing = []
@@ -2008,6 +2028,7 @@ class AnsibleModule(object):
                         self._check_required_together(v.get('required_together', None), param)
                         self._check_required_one_of(v.get('required_one_of', None), param)
                         self._check_required_if(v.get('required_if', None), param)
+                        self._check_required_by(v.get('required_by', None), param)
 
                     self._set_defaults(pre=False, spec=spec, param=param)