Merge pull request #321 from asteris-llc/feature/lists-in-params

Refactor deserializers

.gitignore

@@ -41,4 +41,4 @@ docs_source/public
 
 # examples
 terraform.tfstate*
-.vagrant
+.vagrant

docs_source/content/resource-authors-guide.md

@@ -101,31 +101,55 @@ type Preparer struct {
     Apply string `hcl:"apply"`
 }
 
-func (p *Preparer) Render(r *resource.Renderer) (resource.Task, error) {
-    check, err := render.Render("check", p.Check)
-    if err != nil {
-        return nil, err
-    }
-
-    apply, err := render.Render("apply", p.Apply)
-    if err != nil {
-        return nil, err
-    }
-
+func (p *Preparer) Prepare(resource.Renderer) (resource.Task, error) {
     return &MyShellTask{CheckStmt: check, ApplyStmt: apply}, nil
 }
 ```
 
-"What's the renderer doing there," you may ask, "and how can I accept non-string
-values?" If you need to accept non-string parameters directly, the fields should
-be `interface{}`s, and you should do all your type casting, conversion, and
-validation in Prepare before the values are passed down to your Task.
+To get values other than strings (bools, ints, et cetera), you just need to
+specify them. Converge will render the values and parse them from strings, if
+necessary.
+
+### Struct Tags
+
+Other than `hcl` (which is used to specify the field name you'll accept) the
+following struct tags control the values you get:
+
+- `doc_type`: control the exact printed type in the documentation. Example:
+  fields that accept
+  a [duration string](https://golang.org/pkg/time/#ParseDuration) (such
+  as [task.timeout]({{< ref "resources/task.md" >}})) are commonly strings
+  with a `doc_type` of "duration string"
+
+- `base`: used with numeric types to indicate a base for parsing. Does not work
+  with floats. Example: [file.mode]({{< ref "resources/file.mode.md" >}})
+  needs an octal number, and specifies that in this tag.
+
+We can also do some basic validation tasks with tags:
+
+- `required`: one valid value: `true`. If set, this field must be set in the
+  HCL, but may still have a zero value (for example, `int` can still be `0`.)
+  Example: [docker.container]{{< ref "resources/docker.container.md" >}} uses
+  this to require an image for the container.
+
+- `mutually_exclusive`: a comma-separated list of fields that cannot be set
+  together. Example: [user]({{< ref "resources/user.user.md" >}}) uses this
+  to disallow setting both `groupname` and `gid`.
+
+- `valid_values`: a comma-separated list of values that will be accepted for
+  this field.
+  Example: [docker.container]({{< ref "resources/docker.container.md" >}}) uses
+  this to enforce status is only `running` or `created`.
+
+### The Renderer
 
 The renderer is what allows your values to take input from the environment (like
-calls to `param` or `lookup`.) Normally you'll get a string value back, but when
-you get an error it is very important to return it exactly as received. Converge
-will automatically wrap the errors from Render to provide context to the user
-and to defer rendering of lookup nodes until they're resolved.
+calls to `param` or `lookup`.) Normally you won't need to use this, but if
+you're doing something extremely custom it will be handy. If you get an error
+while using the `Renderer`, return it exactly as received or wrap it with
+[`errors.Wrap` or `errors.Wrapf`](https://github.com/pkg/errors). Converge uses
+these signals to calculate execution order, so it needs to be able to inspect
+the returned error value.
 
 ## Registering
 

docs_source/content/resources/docker.container.md

@@ -1,7 +1,7 @@
 ---
 title: "docker.container"
 slug: "docker-container"
-date: "2016-09-20T14:45:55-05:00"
+date: "2016-09-28T10:46:11-05:00"
 menu:
   main:
     parent: resources
@@ -34,11 +34,11 @@ docker.container "nginx" {
 
 ## Parameters
 
-- `name` (string)
+- `name` (required string)
 
   name of the container
 
-- `image` (string)
+- `image` (required string)
 
   the image name or ID to use for the container
 
@@ -56,7 +56,7 @@ docker.container "nginx" {
 
 - `env` (map of string to string)
 
-  set environmnet variables in the container
+  set environment variables in the container
 
 - `expose` (list of strings)
 
@@ -94,7 +94,10 @@ Specified as a boolean value
 
 - `status` (string)
 
-  the desired status of the container. running|created
+
+  Valid values: `running` and `created`
+
+  the desired status of the container.
 
 - `force` (bool)
 

docs_source/content/resources/file.mode.md

@@ -1,7 +1,7 @@
 ---
 title: "file.mode"
 slug: "file-mode"
-date: "2016-09-08T23:18:02-07:00"
+date: "2016-09-27T18:19:08-05:00"
 menu:
   main:
     parent: resources
@@ -34,7 +34,7 @@ file.mode "render" {
 file must exist on the system (for example, having been created with
 `file.content`.)
 
-- `mode` (octal string)
+- `mode` (base 8 uint32)
 
   Mode is the mode of the file, specified in octal.
 

docs_source/content/resources/param.md

@@ -1,7 +1,7 @@
 ---
 title: "param"
 slug: "param"
-date: "2016-09-20T14:45:55-05:00"
+date: "2016-09-27T18:19:08-05:00"
 menu:
   main:
     parent: resources
@@ -34,7 +34,7 @@ task "render" {
 
 ## Parameters
 
-- `default` (anything scalar)
+- `default` (anything)
 
   Default is an optional field that provides a default value if none is
 provided to this parameter. If this field is not set, this param will be

docs_source/content/resources/task.query.md

@@ -1,7 +1,7 @@
 ---
 title: "task.query"
 slug: "task-query"
-date: "2016-09-08T23:26:25-07:00"
+date: "2016-09-27T18:19:08-05:00"
 menu:
   main:
     parent: resources
@@ -46,3 +46,6 @@ file.content "hostname data" {
 
 
 - `env` (map of string to string)
+
+
+

docs_source/content/resources/user.group.md

@@ -1,7 +1,7 @@
 ---
 title: "user.group"
 slug: "user-group"
-date: "2016-09-21T14:04:24-05:00"
+date: "2016-09-28T10:46:11-05:00"
 menu:
   main:
     parent: resources
@@ -24,17 +24,19 @@ user.group "group" {
 
 ## Parameters
 
-- `gid` (string)
+- `gid` (uint32)
 
   Gid is the group gid.
 
-- `name` (string)
+- `name` (required string)
 
   Name is the group name.
 
 - `state` (string)
 
+
+  Valid values: `present` and `absent`
+
   State is whether the group should be present.
-Options are present and absent; default is present.
 
 

docs_source/content/resources/user.user.md

@@ -1,7 +1,7 @@
 ---
 title: "user.user"
 slug: "user-user"
-date: "2016-09-26T09:00:07-05:00"
+date: "2016-09-28T10:46:11-05:00"
 menu:
   main:
     parent: resources
@@ -24,20 +24,26 @@ user.user "user" {
 
 ## Parameters
 
-- `username` (string)
+- `username` (required string)
 
   Username is the user login name.
 
-- `uid` (string)
+- `uid` (uint32)
 
   UID is the user ID.
 
 - `groupname` (string)
 
-  Groupname is the primary group for user and must already exist.
+
+  Only one of `gid` or `groupname` may be set.
+
+  GroupName is the primary group for user and must already exist.
 Only one of GID or Groupname may be indicated.
 
-- `gid` (string)
+- `gid` (uint32)
+
+
+  Only one of `gid` or `groupname` may be set.
 
   Gid is the primary group ID for user and must refer to an existing group.
 Only one of GID or Groupname may be indicated.
@@ -53,7 +59,9 @@ name is appended to the home directory.
 
 - `state` (string)
 
+
+  Valid values: `present` and `absent`
+
   State is whether the user should be present.
-Options are present and absent; default is present.