r'''
    Returns information about a specified policy

    Args:
        policy_name (str):
            The name of the policy to lookup
        policy_class (str):
            The class of policy, i.e. machine, user, both
        adml_language (str):
            The ADML language to use for Administrative Template data lookup

    Returns:
        dict: Information about the specified policy

    CLI Example:

    .. code-block:: bash

        salt '*' lgpo.get_policy_info 'Maximum password age' machine

    You can use ``lgpo.get_policy_info`` to get all the possible names that
    could be used in a state file or from the command line (along with elements
    that need to be set/etc). The key is to match the text you see in the
    ``gpedit.msc`` gui exactly, including quotes around words or phrases. The
    "full path" style is really only needed when there are multiple policies
    that use the same base name. For example, ``Access data sources across
    domains`` exists in ~10 different paths. If you put that through
    ``get_policy_info`` you'll get back a message that it is used for multiple
    policies and you need to be more specific.

    CLI Example:

    .. code-block:: bash

        salt-call --local lgpo.get_policy_info ShellRemoveOrderPrints_2 machine

        local:
            ----------
            message:
            policy_aliases:
                - Turn off the "Order Prints" picture task
                - ShellRemoveOrderPrints_2
                - System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task
            policy_class:
                machine
            policy_elements:
            policy_found:
                True
            policy_name:
                ShellRemoveOrderPrints_2
            rights_assignment:
                False

    Escaping can get tricky in cmd/Powershell. The following is an example of
    escaping in Powershell using backquotes:

    .. code-block:: bash

        PS>salt-call --local lgpo.get_policy_info "Turn off the `\`"Order Prints`\`" picture task" machine

        local:
            ----------
            message:
            policy_aliases:
                - Turn off the "Order Prints" picture task
                - ShellRemoveOrderPrints_2
                - System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task
            policy_class:
                machine
            policy_elements:
            policy_found:
                True
            policy_name:
                Turn off the "Order Prints" picture task
            rights_assignment:
                False

    This function can then be used to get the options available for specifying
    Group Policy Objects to be used in state files. Based on the above any of
    these *should* be usable:

    .. code-block:: bash

        internet_communications_settings:
          lgpo.set:
            - computer_policy:
                Turn off the "Order Prints" picture task: Enabled

    .. code-block:: bash

        internet_communications_settings:
          lgpo.set:
            - computer_policy:
                ShellRemoveOrderPrints_2: Enabled

    When using the full path, it might be a good idea to use single quotes
    around the path:

    .. code-block:: bash

        internet_communications_settings:
          lgpo.set:
            - computer_policy:
                'System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task': 'Enabled'

    If you struggle to find the policy from ``get_policy_info`` using the name
    as you see in ``gpedit.msc``, the names such as "ShellRemoveOrderPrints_2"
    come from the ``.admx`` files. If you know nothing about ``.admx/.adml``
    relationships (ADML holds what you see in the GUI, ADMX holds the more
    technical details), then this may be a little bit too much info, but here is
    an example with the above policy using Powershell:


    .. code-block:: bash

        PS>Get-ChildItem -Path C:\Windows\PolicyDefinitions -Recurse -Filter *.adml | Select-String "Order Prints"

        C:\windows\PolicyDefinitions\en-US\ICM.adml:152:      <string id="ShellRemoveOrderPrints">Turn off the "Order Prints" picture task</string>
        C:\windows\PolicyDefinitions\en-US\ICM.adml:153:      <string id="ShellRemoveOrderPrints_Help">This policy setting specifies whether the "Order Prints Online" task is available from Picture Tasks in Windows folders.
        C:\windows\PolicyDefinitions\en-US\ICM.adml:155:The Order Prints Online Wizard is used to download a list of providers and allow users to order prints online.
        C:\windows\PolicyDefinitions\en-US\ICM.adml:157:If you enable this policy setting, the task "Order Prints Online" is removed from Picture Tasks in File Explorer folders.

    From this grep, we can see id "ShellRemoveOrderPrints" is the ID of the
    string used to describe this policy, then we search for it in the ADMX:

    .. code-block:: bash

        PS>Get-ChildItem -Path C:\Windows\PolicyDefinitions -Recurse -Filter *.admx | Select-String "ShellRemoveOrderPrints"

        C:\windows\PolicyDefinitions\ICM.admx:661:    <policy name="ShellRemoveOrderPrints_1" class="User" displayName="$(string.ShellRemoveOrderPrints)" explainText="$(string.ShellRemoveOrderPrints_Help)" key="Software\Microsoft\Windows\CurrentVersion\Policies\Explorer" valueName="NoOnlinePrintsWizard">
        C:\windows\PolicyDefinitions\ICM.admx:671:    <policy name="ShellRemoveOrderPrints_2" class="Machine" displayName="$(string.ShellRemoveOrderPrints)" explainText="$(string.ShellRemoveOrderPrints_Help)" key="Software\Microsoft\Windows\CurrentVersion\Policies\Explorer" valueName="NoOnlinePrintsWizard">

    Now we have two to pick from. And if you notice the ``class="Machine"`` and
    ``class="User"`` (which details if it is a computer policy or user policy
    respectively) the ``ShellRemoveOrderPrints_2`` is the "short name" we could
    use to pass through ``get_policy_info`` to see what the module itself is
    expecting.

def get_policy_info(policy_name,
                    policy_class,
                    adml_language='en-US'):
    r'''
    Returns information about a specified policy

    Args:
        policy_name (str):
            The name of the policy to lookup
        policy_class (str):
            The class of policy, i.e. machine, user, both
        adml_language (str):
            The ADML language to use for Administrative Template data lookup

    Returns:
        dict: Information about the specified policy

    CLI Example:

    .. code-block:: bash

        salt '*' lgpo.get_policy_info 'Maximum password age' machine

    You can use ``lgpo.get_policy_info`` to get all the possible names that
    could be used in a state file or from the command line (along with elements
    that need to be set/etc). The key is to match the text you see in the
    ``gpedit.msc`` gui exactly, including quotes around words or phrases. The
    "full path" style is really only needed when there are multiple policies
    that use the same base name. For example, ``Access data sources across
    domains`` exists in ~10 different paths. If you put that through
    ``get_policy_info`` you'll get back a message that it is used for multiple
    policies and you need to be more specific.

    CLI Example:

    .. code-block:: bash

        salt-call --local lgpo.get_policy_info ShellRemoveOrderPrints_2 machine

        local:
            ----------
            message:
            policy_aliases:
                - Turn off the "Order Prints" picture task
                - ShellRemoveOrderPrints_2
                - System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task
            policy_class:
                machine
            policy_elements:
            policy_found:
                True
            policy_name:
                ShellRemoveOrderPrints_2
            rights_assignment:
                False

    Escaping can get tricky in cmd/Powershell. The following is an example of
    escaping in Powershell using backquotes:

    .. code-block:: bash

        PS>salt-call --local lgpo.get_policy_info "Turn off the `\`"Order Prints`\`" picture task" machine

        local:
            ----------
            message:
            policy_aliases:
                - Turn off the "Order Prints" picture task
                - ShellRemoveOrderPrints_2
                - System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task
            policy_class:
                machine
            policy_elements:
            policy_found:
                True
            policy_name:
                Turn off the "Order Prints" picture task
            rights_assignment:
                False

    This function can then be used to get the options available for specifying
    Group Policy Objects to be used in state files. Based on the above any of
    these *should* be usable:

    .. code-block:: bash

        internet_communications_settings:
          lgpo.set:
            - computer_policy:
                Turn off the "Order Prints" picture task: Enabled

    .. code-block:: bash

        internet_communications_settings:
          lgpo.set:
            - computer_policy:
                ShellRemoveOrderPrints_2: Enabled

    When using the full path, it might be a good idea to use single quotes
    around the path:

    .. code-block:: bash

        internet_communications_settings:
          lgpo.set:
            - computer_policy:
                'System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task': 'Enabled'

    If you struggle to find the policy from ``get_policy_info`` using the name
    as you see in ``gpedit.msc``, the names such as "ShellRemoveOrderPrints_2"
    come from the ``.admx`` files. If you know nothing about ``.admx/.adml``
    relationships (ADML holds what you see in the GUI, ADMX holds the more
    technical details), then this may be a little bit too much info, but here is
    an example with the above policy using Powershell:


    .. code-block:: bash

        PS>Get-ChildItem -Path C:\Windows\PolicyDefinitions -Recurse -Filter *.adml | Select-String "Order Prints"

        C:\windows\PolicyDefinitions\en-US\ICM.adml:152:      <string id="ShellRemoveOrderPrints">Turn off the "Order Prints" picture task</string>
        C:\windows\PolicyDefinitions\en-US\ICM.adml:153:      <string id="ShellRemoveOrderPrints_Help">This policy setting specifies whether the "Order Prints Online" task is available from Picture Tasks in Windows folders.
        C:\windows\PolicyDefinitions\en-US\ICM.adml:155:The Order Prints Online Wizard is used to download a list of providers and allow users to order prints online.
        C:\windows\PolicyDefinitions\en-US\ICM.adml:157:If you enable this policy setting, the task "Order Prints Online" is removed from Picture Tasks in File Explorer folders.

    From this grep, we can see id "ShellRemoveOrderPrints" is the ID of the
    string used to describe this policy, then we search for it in the ADMX:

    .. code-block:: bash

        PS>Get-ChildItem -Path C:\Windows\PolicyDefinitions -Recurse -Filter *.admx | Select-String "ShellRemoveOrderPrints"

        C:\windows\PolicyDefinitions\ICM.admx:661:    <policy name="ShellRemoveOrderPrints_1" class="User" displayName="$(string.ShellRemoveOrderPrints)" explainText="$(string.ShellRemoveOrderPrints_Help)" key="Software\Microsoft\Windows\CurrentVersion\Policies\Explorer" valueName="NoOnlinePrintsWizard">
        C:\windows\PolicyDefinitions\ICM.admx:671:    <policy name="ShellRemoveOrderPrints_2" class="Machine" displayName="$(string.ShellRemoveOrderPrints)" explainText="$(string.ShellRemoveOrderPrints_Help)" key="Software\Microsoft\Windows\CurrentVersion\Policies\Explorer" valueName="NoOnlinePrintsWizard">

    Now we have two to pick from. And if you notice the ``class="Machine"`` and
    ``class="User"`` (which details if it is a computer policy or user policy
    respectively) the ``ShellRemoveOrderPrints_2`` is the "short name" we could
    use to pass through ``get_policy_info`` to see what the module itself is
    expecting.
    '''
    # return the possible policy names and element names
    ret = {'policy_name': policy_name,
           'policy_class': policy_class,
           'policy_aliases': [],
           'policy_found': False,
           'rights_assignment': False,
           'policy_elements': [],
           'message': 'policy not found'}
    policy_class = policy_class.title()
    policy_data = _policy_info()
    if policy_class not in policy_data.policies.keys():
        policy_classes = ', '.join(policy_data.policies.keys())
        ret['message'] = 'The requested policy class "{0}" is invalid, ' \
                         'policy_class should be one of: {1}' \
                         ''.format(policy_class, policy_classes)
        return ret
    if policy_name in policy_data.policies[policy_class]['policies']:
        ret['policy_aliases'].append(
            policy_data.policies[policy_class]['policies'][policy_name]['Policy'])
        ret['policy_found'] = True
        ret['message'] = ''
        if 'LsaRights' in policy_data.policies[policy_class]['policies'][policy_name]:
            ret['rights_assignment'] = True
        return ret
    else:
        for pol in policy_data.policies[policy_class]['policies']:
            if policy_data.policies[policy_class]['policies'][pol]['Policy'].lower() == policy_name.lower():
                ret['policy_aliases'].append(pol)
                ret['policy_found'] = True
                ret['message'] = ''
                if 'LsaRights' in policy_data.policies[policy_class]['policies'][pol]:
                    ret['rights_assignment'] = True
                return ret
    success, policy_xml_item, policy_name_list, message = _lookup_admin_template(
            policy_name=policy_name,
            policy_class=policy_class,
            adml_language=adml_language)
    if success:
        for elements_item in ELEMENTS_XPATH(policy_xml_item):
            for child_item in elements_item.getchildren():
                this_element_name = _getFullPolicyName(
                    policy_item=child_item,
                    policy_name=child_item.attrib['id'],
                    return_full_policy_names=True,
                    adml_language=adml_language)
                ret['policy_elements'].append(
                        {'element_id': child_item.attrib['id'],
                         'element_aliases': [child_item.attrib['id'], this_element_name]})
        ret['policy_aliases'] = policy_name_list
        ret['policy_found'] = True
        ret['message'] = ''
        return ret
    else:
        ret['message'] = message

    return ret