Generate and load the configuration of a policy filter.

    filter_name
        The name of the policy filter.

    filter_options
        Additional filter options. These options are platform-specific.
        See the complete list of options_.

        .. _options: https://github.com/google/capirca/wiki/Policy-format#header-section

    terms
        Dictionary of terms for this policy filter.
        If not specified or empty, will try to load the configuration from the pillar,
        unless ``merge_pillar`` is set as ``False``.

    prepend: ``True``
        When ``merge_pillar`` is set as ``True``, the final list of terms generated by merging
        the terms from ``terms`` with those defined in the pillar (if any): new terms are prepended
        at the beginning, while existing ones will preserve the position. To add the new terms
        at the end of the list, set this argument to ``False``.

    pillar_key: ``acl``
        The key in the pillar containing the default attributes values. Default: ``acl``.

    pillarenv
        Query the master to generate fresh pillar data on the fly,
        specifically from the requested pillar environment.

    saltenv
        Included only for compatibility with
        :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

    merge_pillar: ``False``
        Merge ``terms`` with the corresponding value from the pillar. Default: ``False``.

        .. note::
            By default this state does not merge, to avoid any unexpected behaviours.

            The merge logic depends on the ``prepend`` argument.

            The terms specified through the ``terms`` argument have higher priority
            than the pillar.

    only_lower_merge: ``False``
        Specify if it should merge only the terms fields. Otherwise it will try
        to merge also filters fields. Default: ``False``.
        This option requires ``merge_pillar``, otherwise it is ignored.

    revision_id
        Add a comment in the filter config having the description for the changes applied.

    revision_no
        The revision count.

    revision_date: ``True``
        Boolean flag: display the date when the filter configuration was generated. Default: ``True``.

    revision_date_format: ``%Y/%m/%d``
        The date format to be used when generating the perforce data. Default: ``%Y/%m/%d`` (<year>/<month>/<day>).

    test: ``False``
        Dry run? If set as ``True``, will apply the config, discard and return the changes.
        Default: ``False`` and will commit the changes on the device.

    commit: ``True``
        Commit? Default: ``True``.

    debug: ``False``
        Debug mode. Will insert a new key under the output dictionary,
        as ``loaded_config`` containing the raw configuration loaded on the device.

    CLI Example:

    .. code-block:: bash

        salt 'edge01.flw01' state.sls router.acl test=True

    Output Example:

    .. code-block:: text

        edge01.flw01:
        ----------
                  ID: my-filter
            Function: netacl.filter
              Result: None
             Comment: Testing mode: Configuration discarded.
             Started: 12:24:40.598232
            Duration: 2437.139 ms
             Changes:
                      ----------
                      diff:
                          ---
                          +++
                          @@ -1228,9 +1228,24 @@
                          !
                          +ipv4 access-list my-filter
                          + 10 remark $Id: my-filter_state $
                          + 20 remark $Revision: 5 $
                          + 30 remark my-other-term
                          + 40 permit tcp any range 5678 5680 any
                          +!
                          +!
                      loaded:
                          ! $Id: my-filter_state $
                          ! $Revision: 5 $
                          no ipv6 access-list my-filter
                          ipv6 access-list my-filter
                           remark $Id: my-filter_state $
                           remark $Revision: 5 $
                           remark my-other-term
                           permit tcp any range 5678 5680 any
                          exit

        Summary for edge01.flw01
        ------------
        Succeeded: 1 (unchanged=1, changed=1)
        Failed:    0
        ------------
        Total states run:     1
        Total run time:   2.437 s

    Pillar example:

    .. code-block:: yaml

        acl:
          - my-filter:
              options:
                - inet6
              terms:
                - my-term:
                    source_port: [1234, 1235]
                    protocol:
                      - tcp
                      - udp
                    source_address: 1.2.3.4
                    action: reject
                - my-other-term:
                    source_port:
                      - [5678, 5680]
                    protocol: tcp
                    action: accept

    State SLS Example:

    .. code-block:: jinja

        {%- set filter_name = 'my-filter' -%}
        {%- set my_filter_cfg = salt.netacl.get_filter_pillar(filter_name, pillar_key='firewall') -%}
        my_first_filter_state:
          netacl.filter:
            - filter_name: {{ filter_name }}
            - options: {{ my_filter_cfg['options'] | json }}
            - terms: {{ my_filter_cfg['terms'] | json }}
            - revision_date: false
            - revision_no: 5
            - debug: true

    Or:

    .. code-block:: yaml

        my_first_filter_state:
          netacl.filter:
            - filter_name: my-filter
            - merge_pillar: true
            - pillar_key: firewall
            - revision_date: false
            - revision_no: 5
            - debug: true

    In the example above, as ``inet6`` has been specified in the ``filter_options``,
    the configuration chunk referring to ``my-term`` has been ignored as it referred to
    IPv4 only (from ``source_address`` field).

    .. note::
        The first method allows the user to eventually apply complex manipulation
        and / or retrieve the data from external services before passing the
        data to the state. The second one is more straightforward, for less
        complex cases when loading the data directly from the pillar is sufficient.

    .. note::
        When passing retrieved pillar data into the state file, it is strongly
        recommended to use the json serializer explicitly (`` | json``),
        instead of relying on the default Python serializer.

def filter(name,  # pylint: disable=redefined-builtin
           filter_name,
           filter_options=None,
           terms=None,
           prepend=True,
           pillar_key='acl',
           pillarenv=None,
           saltenv=None,
           merge_pillar=False,
           only_lower_merge=False,
           revision_id=None,
           revision_no=None,
           revision_date=True,
           revision_date_format='%Y/%m/%d',
           test=False,
           commit=True,
           debug=False):
    '''
    Generate and load the configuration of a policy filter.

    filter_name
        The name of the policy filter.

    filter_options
        Additional filter options. These options are platform-specific.
        See the complete list of options_.

        .. _options: https://github.com/google/capirca/wiki/Policy-format#header-section

    terms
        Dictionary of terms for this policy filter.
        If not specified or empty, will try to load the configuration from the pillar,
        unless ``merge_pillar`` is set as ``False``.

    prepend: ``True``
        When ``merge_pillar`` is set as ``True``, the final list of terms generated by merging
        the terms from ``terms`` with those defined in the pillar (if any): new terms are prepended
        at the beginning, while existing ones will preserve the position. To add the new terms
        at the end of the list, set this argument to ``False``.

    pillar_key: ``acl``
        The key in the pillar containing the default attributes values. Default: ``acl``.

    pillarenv
        Query the master to generate fresh pillar data on the fly,
        specifically from the requested pillar environment.

    saltenv
        Included only for compatibility with
        :conf_minion:`pillarenv_from_saltenv`, and is otherwise ignored.

    merge_pillar: ``False``
        Merge ``terms`` with the corresponding value from the pillar. Default: ``False``.

        .. note::
            By default this state does not merge, to avoid any unexpected behaviours.

            The merge logic depends on the ``prepend`` argument.

            The terms specified through the ``terms`` argument have higher priority
            than the pillar.

    only_lower_merge: ``False``
        Specify if it should merge only the terms fields. Otherwise it will try
        to merge also filters fields. Default: ``False``.
        This option requires ``merge_pillar``, otherwise it is ignored.

    revision_id
        Add a comment in the filter config having the description for the changes applied.

    revision_no
        The revision count.

    revision_date: ``True``
        Boolean flag: display the date when the filter configuration was generated. Default: ``True``.

    revision_date_format: ``%Y/%m/%d``
        The date format to be used when generating the perforce data. Default: ``%Y/%m/%d`` (<year>/<month>/<day>).

    test: ``False``
        Dry run? If set as ``True``, will apply the config, discard and return the changes.
        Default: ``False`` and will commit the changes on the device.

    commit: ``True``
        Commit? Default: ``True``.

    debug: ``False``
        Debug mode. Will insert a new key under the output dictionary,
        as ``loaded_config`` containing the raw configuration loaded on the device.

    CLI Example:

    .. code-block:: bash

        salt 'edge01.flw01' state.sls router.acl test=True

    Output Example:

    .. code-block:: text

        edge01.flw01:
        ----------
                  ID: my-filter
            Function: netacl.filter
              Result: None
             Comment: Testing mode: Configuration discarded.
             Started: 12:24:40.598232
            Duration: 2437.139 ms
             Changes:
                      ----------
                      diff:
                          ---
                          +++
                          @@ -1228,9 +1228,24 @@
                          !
                          +ipv4 access-list my-filter
                          + 10 remark $Id: my-filter_state $
                          + 20 remark $Revision: 5 $
                          + 30 remark my-other-term
                          + 40 permit tcp any range 5678 5680 any
                          +!
                          +!
                      loaded:
                          ! $Id: my-filter_state $
                          ! $Revision: 5 $
                          no ipv6 access-list my-filter
                          ipv6 access-list my-filter
                           remark $Id: my-filter_state $
                           remark $Revision: 5 $
                           remark my-other-term
                           permit tcp any range 5678 5680 any
                          exit

        Summary for edge01.flw01
        ------------
        Succeeded: 1 (unchanged=1, changed=1)
        Failed:    0
        ------------
        Total states run:     1
        Total run time:   2.437 s

    Pillar example:

    .. code-block:: yaml

        acl:
          - my-filter:
              options:
                - inet6
              terms:
                - my-term:
                    source_port: [1234, 1235]
                    protocol:
                      - tcp
                      - udp
                    source_address: 1.2.3.4
                    action: reject
                - my-other-term:
                    source_port:
                      - [5678, 5680]
                    protocol: tcp
                    action: accept

    State SLS Example:

    .. code-block:: jinja

        {%- set filter_name = 'my-filter' -%}
        {%- set my_filter_cfg = salt.netacl.get_filter_pillar(filter_name, pillar_key='firewall') -%}
        my_first_filter_state:
          netacl.filter:
            - filter_name: {{ filter_name }}
            - options: {{ my_filter_cfg['options'] | json }}
            - terms: {{ my_filter_cfg['terms'] | json }}
            - revision_date: false
            - revision_no: 5
            - debug: true

    Or:

    .. code-block:: yaml

        my_first_filter_state:
          netacl.filter:
            - filter_name: my-filter
            - merge_pillar: true
            - pillar_key: firewall
            - revision_date: false
            - revision_no: 5
            - debug: true

    In the example above, as ``inet6`` has been specified in the ``filter_options``,
    the configuration chunk referring to ``my-term`` has been ignored as it referred to
    IPv4 only (from ``source_address`` field).

    .. note::
        The first method allows the user to eventually apply complex manipulation
        and / or retrieve the data from external services before passing the
        data to the state. The second one is more straightforward, for less
        complex cases when loading the data directly from the pillar is sufficient.

    .. note::
        When passing retrieved pillar data into the state file, it is strongly
        recommended to use the json serializer explicitly (`` | json``),
        instead of relying on the default Python serializer.
    '''
    ret = salt.utils.napalm.default_ret(name)
    test = __opts__['test'] or test
    if not filter_options:
        filter_options = []
    if not terms:
        terms = []
    loaded = __salt__['netacl.load_filter_config'](filter_name,
                                                   filter_options=filter_options,
                                                   terms=terms,
                                                   prepend=prepend,
                                                   pillar_key=pillar_key,
                                                   pillarenv=pillarenv,
                                                   saltenv=saltenv,
                                                   merge_pillar=merge_pillar,
                                                   only_lower_merge=only_lower_merge,
                                                   revision_id=revision_id if revision_id else name,
                                                   revision_no=revision_no,
                                                   revision_date=revision_date,
                                                   revision_date_format=revision_date_format,
                                                   test=test,
                                                   commit=commit,
                                                   debug=debug)
    return salt.utils.napalm.loaded_ret(ret, loaded, test, debug)