unarchive module: Add creates functionality.

Closes GH-5354.

Forklift copy logic into unarchive. Provides integration unit tests.

files/unarchive

@@ -43,7 +43,13 @@ options:
     required: false
     choices: [ "yes", "no" ]
     default: "yes"
-author: Dylan Martin 
+  creates:
+    description:
+      - a filename, when it already exists, this step will B(not) be run.
+    required: no
+    default: null
+    version_added: "1.6"
+author: Dylan Martin
 todo:
     - detect changed/unchanged for .zip files
     - handle common unarchive args, like preserve owner/timestamp etc...
@@ -168,6 +174,7 @@ def main():
             original_basename = dict(required=False), # used to handle 'dest is a directory' via template, a slight hack
             dest              = dict(required=True),
             copy              = dict(default=True, type='bool'),
+            creates           = dict(required=False),
         ),
         add_file_common_args=True,
     )
@@ -175,6 +182,7 @@ def main():
     src    = os.path.expanduser(module.params['src'])
     dest   = os.path.expanduser(module.params['dest'])
     copy   = module.params['copy']
+    creates = module.params['creates']
 
     # did tar file arrive?
     if not os.path.exists(src):
@@ -185,6 +193,20 @@ def main():
     if not os.access(src, os.R_OK):
         module.fail_json(msg="Source '%s' not readable" % src)
 
+    if creates:
+        # do not run the command if the line contains creates=filename
+        # and the filename already exists.  This allows idempotence
+        # of command executions.
+        v = os.path.expanduser(creates)
+        if os.path.exists(v):
+            module.exit_json(
+                stdout="skipped, since %s exists" % v,
+                skipped=True,
+                changed=False,
+                stderr=False,
+                rc=0
+            )
+
     # is dest OK to receive tar file?
     if not os.path.exists(os.path.dirname(dest)):
         module.fail_json(msg="Destination directory '%s' does not exist" % (os.path.dirname(dest)))