starlark/types: Resource documentation

_documentation/runtime/base64.md

@@ -2,7 +2,8 @@
 title: 'encoding/base64'
 ---
 
-base64 defines base64 encoding & decoding functions, often used to represent binary as text.
+base64 defines base64 encoding & decoding functions,
+often used to represent binary as text.
 
 ## Index
 

_documentation/runtime/csv.md

@@ -25,11 +25,11 @@ read all rows from a source string, returning a list of string lists
 | name | type | description |
 |------|------|-------------|
 | `source` | `string` | input string of csv data |
-| `comma` | `string` | comma is the field delimiter, defaults to "," (a comma). comma must be a valid character and must not be \r, \n, or the Unicode replacement character (0xFFFD). |
-| `comment` | `string` | comment, if not "", is the comment character. Lines beginning with the comment character without preceding whitespace are ignored. With leading whitespace the comment character becomes part of the field, even if trim_leading_space is True. comment must be a valid character and must not be \r, \n, or the Unicode replacement character (0xFFFD). It must also not be equal to comma. |
-| `lazy_quotes` | `bool` | If lazy_quotes is True, a quote may appear in an unquoted field and a non-doubled quote may appear in a quoted field. |
-| `trim_leading_space` | `bool` | If trim_leading_space is True, leading white space in a field is ignored. This is done even if the field delimiter, comma, is white space. |
-| `fields_per_record` | `int` | fields_per_record is the number of expected fields per record. If fields_per_record is positive, read_all requires each record to have the given number of fields. If fields_per_record is 0, read_all sets it to the number of fields in the first record, so that future records must have the same field count. If fields_per_record is negative, no check is made and records may have a variable number of fields. |
+| `comma` | `string` | comma is the field delimiter, defaults to "," (a comma).comma must be a valid character and must not be \r, \n,or the Unicode replacement character (0xFFFD). |
+| `comment` | `string` | comment, if not "", is the comment character. Lines beginning with thecomment character without preceding whitespace are ignored.With leading whitespace the comment character becomes part of thefield, even if trim_leading_space is True.comment must be a valid character and must not be \r, \n,or the Unicode replacement character (0xFFFD).It must also not be equal to comma. |
+| `lazy_quotes` | `bool` | If lazy_quotes is True, a quote may appear in an unquoted field anda non-doubled quote may appear in a quoted field. |
+| `trim_leading_space` | `bool` | If trim_leading_space is True, leading white space in a field is ignored.This is done even if the field delimiter, comma, is white space. |
+| `fields_per_record` | `int` | fields_per_record is the number of expected fields per record.If fields_per_record is positive, read_all requires each record tohave the given number of fields. If fields_per_record is 0, read_all sets it tothe number of fields in the first record, so that future records musthave the same field count. If fields_per_record is negative, no check ismade and records may have a variable number of fields. |
 | `skip` | `int` | number of rows to skip, omitting from returned rows |
 
 
@@ -45,7 +45,7 @@ write all rows from source to a csv-encoded string
 | name | type | description |
 |------|------|-------------|
 | `source` | `[][]string` | array of arrays of strings to write to csv |
-| `comma` | `string` | comma is the field delimiter, defaults to "," (a comma). comma must be a valid character and must not be \r, \n, or the Unicode replacement character (0xFFFD). |
+| `comma` | `string` | comma is the field delimiter, defaults to "," (a comma).comma must be a valid character and must not be \r, \n,or the Unicode replacement character (0xFFFD). |
 
 
 

_documentation/runtime/filepath.md

@@ -2,7 +2,8 @@
 title: 'path/filepath'
 ---
 
-filepath implements utility routines for manipulating filename paths in a way compatible with the target operating system-defined file path
+filepath implements utility routines for manipulating filename paths in a
+way compatible with the target operating system-defined file path
 
 ## Index
 
@@ -25,7 +26,9 @@ filepath implements utility routines for manipulating filename paths in a way co
 ```go
 filepath.abs(path) string
 ```
-returns an absolute representation of path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path.
+returns an absolute representation of path. If the path is not
+absolute it will be joined with the current working directory to turn
+it into an absolute path.
 
 ###### Arguments
 
@@ -39,7 +42,10 @@ returns an absolute representation of path. If the path is not absolute it will
 ```go
 filepath.base(path) string
 ```
-returns the last element of path. Trailing path separators are removed before extracting the last element. If the path is empty, `base` returns ".". If the path consists entirely of separators, `base` returns a single separator.
+returns the last element of path. Trailing path separators are
+removed before extracting the last element. If the path is empty,
+`base` returns ".". If the path consists entirely of separators,
+`base` returns a single separator.
 
 ###### Arguments
 
@@ -53,7 +59,8 @@ returns the last element of path. Trailing path separators are removed before ex
 ```go
 filepath.clean(path) string
 ```
-returns the shortest path name equivalent to path by purely lexical processing.
+returns the shortest path name equivalent to path by purely lexical
+processing.
 
 ###### Arguments
 
@@ -67,7 +74,12 @@ returns the shortest path name equivalent to path by purely lexical processing.
 ```go
 filepath.dir(path) string
 ```
-returns all but the last element of path, typically the path's directory. After dropping the final element, `dir` calls `clean` on the path and trailing slashes are removed. If the path is empty, `dir` returns ".". If the path consists entirely of separators, `dir` returns a single separator. The returned path does not end in a separator unless it is the root directory.
+returns all but the last element of path, typically the path's
+directory. After dropping the final element, `dir` calls `clean` on the
+path and trailing slashes are removed. If the path is empty, `dir`
+returns ".". If the path consists entirely of separators, `dir`
+returns a single separator. The returned path does not end in a
+separator unless it is the root directory.
 
 ###### Arguments
 
@@ -81,7 +93,9 @@ returns all but the last element of path, typically the path's directory. After
 ```go
 filepath.ext(path) string
 ```
-returns the file name extension used by path. The extension is the suffix beginning at the final dot in the final element of path; it is empty if there is no dot.
+returns the file name extension used by path. The extension is the
+suffix beginning at the final dot in the final element of path; it
+is empty if there is no dot.
 
 ###### Arguments
 
@@ -95,7 +109,8 @@ returns the file name extension used by path. The extension is the suffix beginn
 ```go
 filepath.glob(pattern) list
 ```
-returns the names of all files matching pattern or None if there is no matching file.
+returns the names of all files matching pattern or None if there is
+no matching file.
 
 ###### Arguments
 
@@ -123,7 +138,10 @@ reports whether the path is absolute.
 ```go
 filepath.join(elements) string
 ```
-joins any number of path elements into a single path, adding a `filepath.separator` if necessary. Join calls Clean on the result; in particular, all empty strings are ignored. On Windows, the result is a UNC path if and only if the first path element is a UNC path.
+joins any number of path elements into a single path, adding a
+`filepath.separator` if necessary. Join calls Clean on the result;
+in particular, all empty strings are ignored. On Windows, the result
+is a UNC path if and only if the first path element is a UNC path.
 
 ###### Arguments
 
@@ -137,7 +155,13 @@ joins any number of path elements into a single path, adding a `filepath.separat
 ```go
 filepath.rel(basepath, targpath) string
 ```
-returns a relative path that is lexically equivalent to targpath when joined to basepath with an intervening separator. That is, `filepath.join(basepath, filepath.rel(basepath, targpath))` is equivalent to targpath itself. On success, the returned path will always be relative to basepath, even if basepath and targpath share no elements. An error is returned if targpath can't be made relative to basepath or if knowing the current working directory would be necessary to compute it. Rel calls Clean on the result.
+returns a relative path that is lexically equivalent to targpath when
+joined to basepath with an intervening separator. That is, `filepath.join(basepath, filepath.rel(basepath, targpath))`
+is equivalent to targpath itself. On success, the returned path will
+always be relative to basepath, even if basepath and targpath share
+no elements. An error is returned if targpath can't be made relative
+to basepath or if knowing the current working directory would be
+necessary to compute it. Rel calls Clean on the result.
 
 ###### Arguments
 

_documentation/runtime/os.md

@@ -122,7 +122,8 @@ removes the named file or (empty) directory.
 ```go
 os.remove_all(path)
 ```
-removes path and any children it contains. It removes everything it can but returns the first error it encounters.
+removes path and any children it contains. It removes everything it
+can but returns the first error it encounters.
 
 ###### Arguments
 
@@ -136,7 +137,9 @@ removes path and any children it contains. It removes everything it can but retu
 ```go
 os.rename(oldpath, newpath)
 ```
-renames (moves) oldpath to newpath. If newpath already exists and is not a directory, Rename replaces it. OS-specific restrictions may apply when oldpath and newpath are in different directories.
+renames (moves) oldpath to newpath. If newpath already exists and is
+not a directory, Rename replaces it. OS-specific restrictions may
+apply when oldpath and newpath are in different directories.
 
 ###### Arguments
 

_documentation/runtime/re.md

@@ -2,7 +2,8 @@
 title: ''
 ---
 
-re defines regular expression functions, it's intended to be a drop-in subset of python's re module for starlark: https://docs.python.org/3/library/re.html
+re defines regular expression functions, it's intended to be a drop-in
+subset of python's re module for starlark: https://docs.python.org/3/library/re.html
 
 ## Index
 
@@ -19,7 +20,11 @@ re defines regular expression functions, it's intended to be a drop-in subset of
 ```go
 re.findall(pattern, text, flags=0)
 ```
-Returns all non-overlapping matches of pattern in string, as a list of strings. The string is scanned left-to-right, and matches are returned in the order found. If one or more groups are present in the pattern, return a list of groups; this will be a list of tuples if the pattern has more than one group. Empty matches are included in the result.
+Returns all non-overlapping matches of pattern in string, as a list of strings.
+The string is scanned left-to-right, and matches are returned in the order found.
+If one or more groups are present in the pattern, return a list of groups;
+this will be a list of tuples if the pattern has more than one group.
+Empty matches are included in the result.
 
 ###### Arguments
 
@@ -35,7 +40,10 @@ Returns all non-overlapping matches of pattern in string, as a list of strings.
 ```go
 re.split(pattern, text, maxsplit=0, flags=0)
 ```
-Split text by the occurrences of pattern. If capturing parentheses are used in pattern, then the text of all groups in the pattern are also returned as part of the resulting list. If maxsplit is nonzero, at most maxsplit splits occur, and the remainder of the string is returned as the final element of the list.
+Split text by the occurrences of pattern. If capturing parentheses are used in pattern,
+then the text of all groups in the pattern are also returned as part of the resulting list.
+If maxsplit is nonzero, at most maxsplit splits occur, and the remainder of the string
+is returned as the final element of the list.
 
 ###### Arguments
 
@@ -52,7 +60,10 @@ Split text by the occurrences of pattern. If capturing parentheses are used in p
 ```go
 re.sub(pattern, repl, text, count=0, flags=0)
 ```
-Return the string obtained by replacing the leftmost non-overlapping occurrences of pattern in string by the replacement repl. If the pattern isn’t found, string is returned unchanged. repl can be a string or a function; if it is a string, any backslash escapes in it are processed. That is, \n is converted to a single newline character, \r is converted to a carriage return, and so forth.
+Return the string obtained by replacing the leftmost non-overlapping occurrences of pattern
+in string by the replacement repl. If the pattern isn’t found, string is returned unchanged.
+repl can be a string or a function; if it is a string, any backslash escapes in it are processed.
+That is, \n is converted to a single newline character, \r is converted to a carriage return, and so forth.
 
 ###### Arguments
 

_scripts/template.md

@@ -25,7 +25,7 @@
 | name | type | description |
 |------|------|-------------|
 {{ range .Params -}}
-| `{{ .Name }}` | `{{ .Type }}` | {{ .Description }} |
+| `{{ .Name }}` | `{{ .Type }}` | {{ (replace_all .Description "\n" "") }} |
 {{ end -}}
 
 {{- end -}}
@@ -52,7 +52,7 @@
 
 {{- define "index" -}}
 ## Index
-
+<div class="toc">
 {{ range .Functions }}
 {{ template "indexFunctionName" . }}
 {{- end -}}
@@ -63,7 +63,7 @@
     {{ template "indexFunctionName" . -}}
 {{- end -}}
 {{- end }}
-
+</div>
 {{ end -}}
 
 
@@ -98,7 +98,7 @@ title: '{{ .Path }}'
 | name | type | description |
 |------|------|-------------|
 {{ range .Fields -}}
-| `{{ .Name }}` | `{{ .Type }}` | {{ .Description }} |
+| `{{ .Name }}` | `{{ .Type }}` | {{ (replace_all .Description "\n" "") }} |
 {{ end -}}
 
 {{ end }}

starlark/types/collection.go

@@ -125,7 +125,7 @@ func (c *ResourceCollection) String() string {
 
 // Type honors the starlark.Value interface.
 func (c *ResourceCollection) Type() string {
-	return "ResourceCollection"
+	return fmt.Sprintf("ResourceCollection<%s>", c.kind)
 }
 
 // Truth honors the starlark.Value interface.

starlark/types/provider.go

@@ -271,8 +271,8 @@ func (g *ResourceCollectionGroup) String() string {
 }
 
 // Type honors the starlark.Value interface.
-func (*ResourceCollectionGroup) Type() string {
-	return "ResourceCollectionGroup"
+func (g *ResourceCollectionGroup) Type() string {
+	return fmt.Sprintf("ResourceCollectionGroup<%s>", g.kind)
 }
 
 // Freeze honors the starlark.Value interface.

starlark/types/resource.go

@@ -137,6 +137,23 @@ func unpackResourceArgs(
 //         usually provides resources to manage a single cloud or on-premises
 //         infrastructure platform.
 //
+//         Following the schema of HCL Terraform resources each type of
+//         arguments and blocks are transformed in native AsCode elements:
+//
+//         * [Blocks](https://www.terraform.io/docs/glossary.html#block) defined
+//           as a list of Resources are transformed into: `ResourceCollection<nested>`,
+//           if the `Block` is a list capped to one item, its represented as
+//           `Resource<nested>`.
+//
+//         * [Arguments](https://www.terraform.io/docs/glossary.html#argument)
+//           are transformed as basic scalar types.
+//
+//         * [Attributes](https://www.terraform.io/docs/glossary.html#attribute)
+//           aka computed arguments are transformed in `Attributes`
+//
+//         examples:
+//           resource.star
+//
 //         fields:
 //           __provider__ Provider
 //             Provider of this resource if any.
@@ -153,7 +170,7 @@ func unpackResourceArgs(
 //           <argument> <scalar>/Computed
 //             Arguments defined by the resource schema, thus can be of any
 //             scalar type or Computed values.
-//           <block> Resource
+//           <block> Resource/ResourceCollection
 //             Blocks defined by the resource schema, thus are nested resources,
 //             containing other arguments and/or blocks.
 //

starlark/types/testdata/examples/resource.star

@@ -0,0 +1,53 @@
+# Create a new instance of the latest Ubuntu 14.04 on an
+# t2.micro node with an AWS Tag naming it "HelloWorld"
+
+aws = tf.provider("aws")
+aws.region = "us-west-2"
+
+ubuntu_filter = "ubuntu/images/*/ubuntu-xenial-16.04-amd64-server-*"
+canonical = "099720109477"
+
+ami = aws.data.ami("ubuntu")
+ami.most_recent = True
+ami.filter(name="name", values=[ubuntu_filter])
+ami.filter(name="virtualization-type", values=["hvm"])
+ami.owners = [canonical]
+
+
+instance = aws.resource.instance("web")
+instance.instance_type = "t2.micro"
+instance.ami = ami.id
+instance.tags = {
+    "name": "HelloWorld"
+}
+
+print(hcl(tf))
+# Output:
+# provider "aws" {
+#   alias   = "id_1"
+#   version = "2.54.0"
+#   region  = "us-west-2"
+# }
+#
+# data "aws_ami" "ubuntu" {
+#   provider    = aws.id_1
+#   most_recent = true
+#   owners      = ["099720109477"]
+# 
+#   filter {
+#     name   = "name"
+#     values = ["ubuntu/images/*/ubuntu-xenial-16.04-amd64-server-*"]
+#   }
+# 
+#   filter {
+#     name   = "virtualization-type"
+#     values = ["hvm"]
+#   }
+# }
+# 
+# resource "aws_instance" "web" {
+#   provider      = aws.id_1
+#   ami           = "${data.aws_ami.ubuntu.id}"
+#   instance_type = "t2.micro"
+#   tags          = { name = "HelloWorld" }
+# }

starlark/types/testdata/nested.star

@@ -3,7 +3,7 @@ load("assert.star", "assert")
 p = tf.provider("aws", "2.13.0")
 d = p.data.ami()
 
-assert.eq(type(d.filter), "ResourceCollection")
+assert.eq(type(d.filter), "ResourceCollection<nested>")
 
 bar = d.filter(name="bar", values=["qux"])
 

starlark/types/testdata/provider.star

@@ -23,8 +23,8 @@ assert.contains(resources, "instance")
 
 # types
 assert.eq(type(p), "Provider")
-assert.eq(type(p.resource), "ResourceCollectionGroup")
-assert.eq(type(p.resource.instance), "ResourceCollection")
+assert.eq(type(p.resource), "ResourceCollectionGroup<resource>")
+assert.eq(type(p.resource.instance), "ResourceCollection<resource>")
 assert.eq(type(p.resource.instance()), "Resource<resource>")
 assert.eq(type(p.data.ami().filter()), "Resource<nested>")