openbsd_pkg: add upgrade argument.

Running the module with the argument "upgrade=yes" invokes an upgrade of
all installed packages.

While here clean up some comments.

Functionality requested by @qbit.

lib/ansible/modules/extras/packaging/openbsd_pkg.py

@@ -59,6 +59,9 @@ EXAMPLES = '''
 
 # Specify the default flavour to avoid ambiguity errors
 - openbsd_pkg: name=vim-- state=present
+
+# Make sure all packages are upgraded
+- openbsd_pkg: upgrade=yes
 '''
 
 # Control if we write debug information to syslog.
@@ -266,8 +269,8 @@ def package_absent(name, installed_state, module):
 
     return (rc, stdout, stderr, changed)
 
-# Function used to parse the package name based on packages-specs(7)
-# The general name structure is "stem-version[-flavors]"
+# Function used to parse the package name based on packages-specs(7).
+# The general name structure is "stem-version[-flavors]".
 def parse_package_name(name, pkg_spec, module):
     # Do some initial matches so we can base the more advanced regex on that.
     version_match = re.search("-[0-9]", name)
@@ -321,20 +324,55 @@ def parse_package_name(name, pkg_spec, module):
         if match:
             module.fail_json(msg="Trailing dash in flavor: " + pkg_spec['flavor'])
 
+# Function used for upgrading all installed packages.
+def upgrade_packages(module):
+    if module.check_mode:
+        upgrade_cmd = 'pkg_add -Imnu'
+    else:
+        upgrade_cmd = 'pkg_add -Imu'
+
+    # Attempt to upgrade all packages.
+    rc, stdout, stderr = execute_command("%s" % upgrade_cmd, module)
+
+    # Try to find any occurance of a package changing version like:
+    # "bzip2-1.0.6->1.0.6p0: ok".
+    match = re.search("\W\w.+->.+: ok\W", stdout)
+    if match:
+        if module.check_mode:
+            module.exit_json(changed=True)
+
+        changed=True
+
+    else:
+        changed=False
+
+    # It seems we can not trust the return value, so depend on the presence of
+    # stderr to know if something failed.
+    if stderr:
+        rc = 1
+    else:
+        rc = 0
+
+    return (rc, stdout, stderr, changed)
+
 # ===========================================
-# Main control flow
+# Main control flow.
 
 def main():
     module = AnsibleModule(
         argument_spec = dict(
-            name = dict(required=True),
-            state = dict(required=True, choices=['absent', 'installed', 'latest', 'present', 'removed']),
+            name = dict(),
+            state = dict(choices=['absent', 'installed', 'latest', 'present', 'removed']),
+            upgrade = dict(choices=['yes']),
         ),
+        mutually_exclusive = [['name', 'upgrade']],
+        required_one_of = [['name', 'upgrade']],
         supports_check_mode = True
     )
 
     name      = module.params['name']
     state     = module.params['state']
+    upgrade   = module.params['upgrade']
 
     rc = 0
     stdout = ''
@@ -342,6 +380,11 @@ def main():
     result = {}
     result['name'] = name
     result['state'] = state
+    result['upgrade'] = upgrade
+
+    if name:
+        if not state:
+            module.fail_json(msg="missing required arguments: state")
 
         # Parse package name and put results in the pkg_spec dictionary.
         pkg_spec = {}
@@ -357,6 +400,11 @@ def main():
             (rc, stdout, stderr, changed) = package_absent(name, installed_state, module)
         elif state == 'latest':
             (rc, stdout, stderr, changed) = package_latest(name, installed_state, pkg_spec, module)
+    elif upgrade:
+        # Perform an upgrade of all installed packages.
+        (rc, stdout, stderr, changed) = upgrade_packages(module)
+    else:
+        module.fail_json(msg="Something is broken, you should never end up here")
 
     if rc != 0:
         if stderr:
@@ -368,6 +416,6 @@ def main():
 
     module.exit_json(**result)
 
-# import module snippets
+# Import module snippets.
 from ansible.module_utils.basic import *
 main()