pkgutil: add update all, check-mode, squashing and examples (#799)

* pkgutil: add update all, check-mode, squashing and examples

Taken from https://github.com/ansible/ansible/pull/51651 by dagwieers, which was taken from https://github.com/ansible/ansible/pull/27866 by scathatheworm.  Let’s have one last attempt to get this merged.

> ##### SUMMARY
>
> Original PR #27866 from scathatheworm
>
> When working with Solaris pkgutil CSW packages, I came across this module being very basic in functionality, in particular, that I could not use it to update all CSW packages.
>
> When going into details into the code I also found it did not incorporate a possibility of doing dry-run from the underlying utility, or supported to specify multiple packages for operations.
>
> This module probably sees very little use, but it seemed like nice functionality to add and make it behave a little more like other package modules.
> ##### ISSUE TYPE
>
>     * Feature Pull Request
>
>
> ##### COMPONENT NAME
>
> pkgutil module
> ##### ANSIBLE VERSION
>
> ```
> ansible 2.3.1.0
>   config file = /etc/ansible/ansible.cfg
>   configured module search path = Default w/o overrides
>   python version = 2.7.5 (default, Aug  2 2016, 04:20:16) [GCC 4.8.5 20150623 (Red Hat 4.8.5-4)]
> ```
>
> ##### ADDITIONAL INFORMATION
>
>     * Added ability to upgrade all packages:
>
>
> ```yaml
> - pkgutil:
>     name: '*'
>     state: latest
> ```
>
>     * Added ability to modify state of a list of packages:
>
>
> ```yaml
> - pkgutil:
>     name:
>     - CSWtop
>     - CSWwget
>     - CSWlsof
>     state: present
> ```
>
>     * Added ability to have underlying tool perform a dry-run when using check mode, pkgutil -n
>
>     * Added ability to configure force option to force packages to state determined by repository (downgrade for example)
>
>
> ```yaml
> - pkgutil:
>     name: CSWtop
>     state: latest
>     force: yes
> ```
>
>     * Added more examples and documentation to show the new functionality

* Add changelog fragment.

* Observe changelog style guide

https://docs.ansible.com/ansible/devel/community/development_process.html#changelogs

Co-authored-by: Felix Fontein <felix@fontein.de>

* Since module split, version_added no-longer refers to core Ansbile

Co-authored-by: Felix Fontein <felix@fontein.de>

* Tweak documentation

* Apply the new `elements` feature for specifying list types

Co-authored-by: Felix Fontein <felix@fontein.de>

* Set version_added

Co-authored-by: Felix Fontein <felix@fontein.de>

* Document `pkg` alias for `name`

* Be explicit about the purpose of states `installed` and `removed`.

* Force the user to specify their desired state.

* Review documentation for pkgutil module.

* Fully qualify svr4pkg module name

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Felix Fontein <felix@fontein.de>

tests/integration/targets/pkgutil/aliases

@@ -0,0 +1,2 @@
+destructive
+unsupported

tests/integration/targets/pkgutil/tasks/main.yml

@@ -0,0 +1,116 @@
+# Test code for the pkgutil module
+
+# Copyright: (c) 2019, Dag Wieers (@dagwieers) <dag@wieers.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+# CLEAN ENVIRONMENT
+- name: Remove CSWtop
+  pkgutil:
+    name: CSWtop
+    state: absent
+  register: originally_installed
+
+
+# ADD PACKAGE
+- name: Add package (check_mode)
+  pkgutil:
+    name: CSWtop
+    state: present
+  check_mode: yes
+  register: cm_add_package
+
+- name: Verify cm_add_package
+  assert:
+    that:
+    - cm_add_package is changed
+
+- name: Add package (normal mode)
+  pkgutil:
+    name: CSWtop
+    state: present
+  register: nm_add_package
+
+- name: Verify nm_add_package
+  assert:
+    that:
+    - nm_add_package is changed
+
+- name: Add package again (check_mode)
+  pkgutil:
+    name: CSWtop
+    state: present
+  check_mode: yes
+  register: cm_add_package_again
+
+- name: Verify cm_add_package_again
+  assert:
+    that:
+    - cm_add_package_again is not changed
+
+- name: Add package again (normal mode)
+  pkgutil:
+    name: CSWtop
+    state: present
+  register: nm_add_package_again
+
+- name: Verify nm_add_package_again
+  assert:
+    that:
+    - nm_add_package_again is not changed
+
+
+# REMOVE PACKAGE
+- name: Remove package (check_mode)
+  pkgutil:
+    name: CSWtop
+    state: absent
+  check_mode: yes
+  register: cm_remove_package
+
+- name: Verify cm_remove_package
+  assert:
+    that:
+    - cm_remove_package is changed
+
+- name: Remove package (normal mode)
+  pkgutil:
+    name: CSWtop
+    state: absent
+  register: nm_remove_package
+
+- name: Verify nm_remove_package
+  assert:
+    that:
+    - nm_remove_package is changed
+
+- name: Remove package again (check_mode)
+  pkgutil:
+    name: CSWtop
+    state: absent
+  check_mode: yes
+  register: cm_remove_package_again
+
+- name: Verify cm_remove_package_again
+  assert:
+    that:
+    - cm_remove_package_again is not changed
+
+- name: Remove package again (normal mode)
+  pkgutil:
+    name: CSWtop
+    state: absent
+  register: nm_remove_package_again
+
+- name: Verify nm_remove_package_again
+  assert:
+    that:
+    - nm_remove_package_again is not changed
+
+
+# RESTORE ENVIRONMENT
+- name: Reinstall CSWtop
+  pkgutil:
+    name: CSWtop
+    state: present
+  when: originally_installed is changed