documentation: some examples, links review and gh-actions

_documentation/_index.md

@@ -5,7 +5,7 @@ weight: 1
 
 ## AsCode - Terraform Alternative Syntax 
 
-**AsCode** is a tool to define infrastructure as code using the [Starlark](https://github.com/google/starlark-go/blob/master/doc/spec.md) language on top of Ter[Terraform](https://github.com/hashicorp/terraform)raform. It allows to describe your infrastructure using an expressive language in Terraform without writing a single line of HCL, meanwhile, you have the complete ecosystem of [providers](https://www.terraform.io/docs/providers/index.html) 
+**AsCode** is a tool to define infrastructure as code using the [Starlark](https://github.com/google/starlark-go/blob/master/doc/spec.md) language on top of [Terraform](https://github.com/hashicorp/terraform). It allows to describe your infrastructure using an expressive language in Terraform without writing a single line of HCL, meanwhile, you have the complete ecosystem of [providers](https://www.terraform.io/docs/providers/index.html) 
 
 ### Why?
 
@@ -13,4 +13,4 @@ Terraform is a great tool, with support for almost everything you can imagine, m
 
 ### What is Starlark?
 
-> Starlark is a dialect of Python intended for use as a configuration language. A Starlark interpreter is typically embedded within a larger application, and this application may define additional domain-specific functions and data types beyond those provided by the core language. For example, Starlark is embedded within (and was originally developed for) the Bazel build tool, and Bazel's build language is based on Starlark.
+Starlark is a dialect of Python intended for use as a configuration language. A Starlark interpreter is typically embedded within a larger application, and this application may define additional domain-specific functions and data types beyond those provided by the core language. For example, Starlark is embedded within (and was originally developed for) the Bazel build tool, and Bazel's build language is based on Starlark.

_documentation/github-action.md

@@ -3,4 +3,71 @@ title: 'GitHub Action'
 weight: 40
 ---
 
-TODO
+AsCode Github Action allows to execute AsCode `run` command in response to a GitHub event such as updating a pull request or pushing a new commit on a specific branch. 
+
+This used in combination with the [Terraform GitHub Actions](https://www.terraform.io/docs/github-actions/getting-started.html) allows to execute the different terraform commands `init`, `plan` and `apply` inside of a [GitHub Workflow](https://help.github.com/en/actions/configuring-and-managing-workflows).
+
+## Parameters
+
+| Parameter | **Mandatory**/**Optional** | Description | 
+| --------- | -------- | ----------- |
+| file | **Mandatory** | Starlark file to execute. Default value: `main.star` |
+| hcl | **Mandatory** | HCL output file. Default value: `generated.tf` |
+
+## Recommended Workflow
+
+
+```yaml
+name: 'Terraform & AsCode'
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  terraform:
+    name: 'Deploy'
+    runs-on: ubuntu-latest
+    env:
+        TF_VERSION: latest
+        TF_WORKING_DIR: . 
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@master
+
+      - name: 'AsCode Run'
+        uses: mcuadros/ascode@gh-action
+     
+      - name: 'Terraform Init'
+        uses: hashicorp/terraform-github-actions@master
+        with:
+          tf_actions_version: ${{ env.TF_VERSION }}
+          tf_actions_subcommand: 'init'
+          tf_actions_working_dir: ${{ env.TF_WORKING_DIR }}
+          tf_actions_comment: true
+
+      - name: 'Terraform Validate'
+        uses: hashicorp/terraform-github-actions@master
+        with:
+          tf_actions_version: ${{ env.TF_VERSION }}
+          tf_actions_subcommand: 'validate'
+          tf_actions_working_dir: ${{ env.TF_WORKING_DIR }}
+          tf_actions_comment: true
+
+      - name: 'Terraform Plan'
+        uses: hashicorp/terraform-github-actions@master
+        with:
+          tf_actions_version: ${{ env.TF_VERSION }}
+          tf_actions_subcommand: 'plan'
+          tf_actions_working_dir: ${{ env.TF_WORKING_DIR }}
+          tf_actions_comment: true
+
+      - name: 'Terraform Apply'
+        uses: hashicorp/terraform-github-actions@master
+        if: github.event_name == 'push'
+        with:
+          tf_actions_version: ${{ env.TF_VERSION }}
+          tf_actions_subcommand: 'apply'
+          tf_actions_working_dir: ${{ env.TF_WORKING_DIR }}
+```

_documentation/starlark/_index.md

@@ -9,15 +9,15 @@ application, and this application may define additional
 domain-specific functions and data types beyond those provided by the
 core language.  For example, Starlark is embedded within (and was
 originally developed for) the [Bazel build tool](https://bazel.build),
-and [Bazel's build language](https://docs.bazel.build/versions/master/starlark/language.html) is based on Starlark.
+and [Bazel's build language](https://docs.bazel.build/versions/2.0.0/skylark/language.html) is based on Starlark.
 
 This document describes the Go implementation of Starlark
 at go.starlark.net/starlark.
 The language it defines is similar but not identical to
-[the Java-based implementation](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/starlark/Starlark.java)
+[the Java-based implementation](https://github.com/bazelbuild/starlark)
 used by Bazel.
 We identify places where their behaviors differ, and an
-[appendix](#dialect-differences) provides a summary of those
+[appendix](/docs/starlark/dialect-differences/) provides a summary of those
 differences.
 We plan to converge both implementations on a single specification.
 

_documentation/starlark/built-in-methods.md

@@ -7,7 +7,7 @@ toc: true
 ## Overview
 
 This section lists the methods of built-in types.  Methods are selected
-using [dot expressions](#dot-expressions).
+using [dot expressions](/docs/starlark/expressions/#dot-expressions).
 For example, strings have a `count` method that counts
 occurrences of a substring; `"banana".count("a")` yields `3`.
 
@@ -193,7 +193,7 @@ The optional `start` and `end` parameters restrict the portion of
 list L that is inspected.  If provided and not `None`, they must be list
 indices of type `int`. If an index is negative, `len(L)` is effectively
 added to it, then if the index is outside the range `[0:len(L)]`, the
-nearest value within that range is used; see [Indexing](#indexing).
+nearest value within that range is used; see [Indexing](/docs/starlark/value-concepts/#indexing).
 
 `index` fails if `x` is not found in L, or if `start` or `end`
 is not a valid index (`int` or `None`).
@@ -328,7 +328,7 @@ See also: `string·codepoints`.
 `S.count(sub[, start[, end]])` returns the number of occcurences of
 `sub` within the string S, or, if the optional substring indices
 `start` and `end` are provided, within the designated substring of S.
-They are interpreted according to Starlark's [indexing conventions](#indexing).
+They are interpreted according to Starlark's [indexing conventions](/docs/starlark/value-concepts/#indexing).
 
 ```python
 "hello, world!".count("o")              # 2
@@ -359,7 +359,7 @@ occurrence of the substring `sub` within S.
 
 If either or both of `start` or `end` are specified,
 they specify a subrange of S to which the search should be restricted.
-They are interpreted according to Starlark's [indexing conventions](#indexing).
+They are interpreted according to Starlark's [indexing conventions](/docs/starlark/value-concepts/#indexing).
 
 If no occurrence is found, `found` returns -1.
 

_documentation/starlark/data-types.md

@@ -39,7 +39,7 @@ expression `str(x)`, or to a Boolean truth value using the expression
 `bool(x)`.  Other operations apply only to certain types.  For
 example, the indexing operation `a[i]` works only with strings, lists,
 and tuples, and any application-defined types that are _indexable_.
-The [_value concepts_](#value-concepts) section explains the groupings of
+The [_value concepts_](/docs/starlark/value-concepts/) section explains the groupings of
 types by the operators they support.
 
 
@@ -48,14 +48,14 @@ types by the operators they support.
 `None` is a distinguished value used to indicate the absence of any other value.
 For example, the result of a call to a function that contains no return statement is `None`.
 
-`None` is equal only to itself.  Its [type](#type) is `"NoneType"`.
+`None` is equal only to itself.  Its [type](/docs/starlark/built-in-constants-and-functions/#type) is `"NoneType"`.
 The truth value of `None` is `False`.
 
 
 ## Booleans
 
 There are two Boolean values, `True` and `False`, representing the
-truth or falsehood of a predicate.  The [type](#type) of a Boolean is `"bool"`.
+truth or falsehood of a predicate.  The [type](/docs/starlark/built-in-constants-and-functions/#type) of a Boolean is `"bool"`.
 
 Boolean values are typically used as conditions in `if`-statements,
 although any Starlark value used as a condition is implicitly
@@ -79,7 +79,7 @@ else:
 
 ## Integers
 
-The Starlark integer type represents integers.  Its [type](#type) is `"int"`.
+The Starlark integer type represents integers.  Its [type](/docs/starlark/built-in-constants-and-functions/#type) is `"int"`.
 
 Integers may be positive or negative, and arbitrarily large.
 Integer arithmetic is exact.
@@ -129,7 +129,7 @@ The Java implementation currently supports only signed 32-bit integers.
 ## Floating-point numbers
 
 The Starlark floating-point data type represents an IEEE 754
-double-precision floating-point number.  Its [type](#type) is `"float"`.
+double-precision floating-point number.  Its [type](/docs/starlark/built-in-constants-and-functions/#type) is `"float"`.
 
 Arithmetic on floats using the `+`, `-`, `*`, `/`, `//`, and `%`
  operators follows the IEE 754 standard.
@@ -183,7 +183,7 @@ The Java implementation does not yet support floating-point numbers.
 ## Strings
 
 A string represents an immutable sequence of bytes.
-The [type](#type) of a string is `"string"`.
+The [type](/docs/starlark/built-in-constants-and-functions/#type) of a string is `"string"`.
 
 Strings can represent arbitrary binary data, including zero bytes, but
 most strings contain text, encoded by convention using UTF-8.
@@ -217,39 +217,39 @@ non-empty.
 
 Strings have several built-in methods:
 
-* [`capitalize`](#string·capitalize)
-* [`codepoint_ords`](#string·codepoint_ords)
-* [`codepoints`](#string·codepoints)
-* [`count`](#string·count)
-* [`elem_ords`](#string·elem_ords)
-* [`elems`](#string·elems)
-* [`endswith`](#string·endswith)
-* [`find`](#string·find)
-* [`format`](#string·format)
-* [`index`](#string·index)
-* [`isalnum`](#string·isalnum)
-* [`isalpha`](#string·isalpha)
-* [`isdigit`](#string·isdigit)
-* [`islower`](#string·islower)
-* [`isspace`](#string·isspace)
-* [`istitle`](#string·istitle)
-* [`isupper`](#string·isupper)
-* [`join`](#string·join)
-* [`lower`](#string·lower)
-* [`lstrip`](#string·lstrip)
-* [`partition`](#string·partition)
-* [`replace`](#string·replace)
-* [`rfind`](#string·rfind)
-* [`rindex`](#string·rindex)
-* [`rpartition`](#string·rpartition)
-* [`rsplit`](#string·rsplit)
-* [`rstrip`](#string·rstrip)
-* [`split`](#string·split)
-* [`splitlines`](#string·splitlines)
-* [`startswith`](#string·startswith)
-* [`strip`](#string·strip)
-* [`title`](#string·title)
-* [`upper`](#string·upper)
+* [`capitalize`](/docs/starlark/built-in-methods/#stringcapitalize)
+* [`codepoint_ords`](/docs/starlark/built-in-methods/#stringcodepoint_ords)
+* [`codepoints`](/docs/starlark/built-in-methods/#stringcodepoints)
+* [`count`](/docs/starlark/built-in-methods/#stringcount)
+* [`elem_ords`](/docs/starlark/built-in-methods/#stringelem_ords)
+* [`elems`](/docs/starlark/built-in-methods/#stringelems)
+* [`endswith`](/docs/starlark/built-in-methods/#stringendswith)
+* [`find`](/docs/starlark/built-in-methods/#stringfind)
+* [`format`](/docs/starlark/built-in-methods/#stringformat)
+* [`index`](/docs/starlark/built-in-methods/#stringindex)
+* [`isalnum`](/docs/starlark/built-in-methods/#stringisalnum)
+* [`isalpha`](/docs/starlark/built-in-methods/#stringisalpha)
+* [`isdigit`](/docs/starlark/built-in-methods/#stringisdigit)
+* [`islower`](/docs/starlark/built-in-methods/#stringislower)
+* [`isspace`](/docs/starlark/built-in-methods/#stringisspace)
+* [`istitle`](/docs/starlark/built-in-methods/#stringistitle)
+* [`isupper`](/docs/starlark/built-in-methods/#stringisupper)
+* [`join`](/docs/starlark/built-in-methods/#stringjoin)
+* [`lower`](/docs/starlark/built-in-methods/#stringlower)
+* [`lstrip`](/docs/starlark/built-in-methods/#stringlstrip)
+* [`partition`](/docs/starlark/built-in-methods/#stringpartition)
+* [`replace`](/docs/starlark/built-in-methods/#stringreplace)
+* [`rfind`](/docs/starlark/built-in-methods/#stringrfind)
+* [`rindex`](/docs/starlark/built-in-methods/#stringrindex)
+* [`rpartition`](/docs/starlark/built-in-methods/#stringrpartition)
+* [`rsplit`](/docs/starlark/built-in-methods/#stringrsplit)
+* [`rstrip`](/docs/starlark/built-in-methods/#stringrstrip)
+* [`split`](/docs/starlark/built-in-methods/#stringsplit)
+* [`splitlines`](/docs/starlark/built-in-methods/#stringsplitlines)
+* [`startswith`](/docs/starlark/built-in-methods/#stringstartswith)
+* [`strip`](/docs/starlark/built-in-methods/#stringstrip)
+* [`title`](/docs/starlark/built-in-methods/#stringtitle)
+* [`upper`](/docs/starlark/built-in-methods/#stringupper)
 
 <b>Implementation note:</b>
 The type of a string element varies across implementations.
@@ -316,13 +316,13 @@ result of some expression applied to each element of another sequence.
 
 A list value has these methods:
 
-* [`append`](#list·append)
-* [`clear`](#list·clear)
-* [`extend`](#list·extend)
-* [`index`](#list·index)
-* [`insert`](#list·insert)
-* [`pop`](#list·pop)
-* [`remove`](#list·remove)
+* [`append`](/docs/starlark/built-in-methods/#listappend)
+* [`clear`](/docs/starlark/built-in-methods/#listclear)
+* [`extend`](/docs/starlark/built-in-methods/#listextend)
+* [`index`](/docs/starlark/built-in-methods/#listindex)
+* [`insert`](/docs/starlark/built-in-methods/#listinsert)
+* [`pop`](/docs/starlark/built-in-methods/#listpop)
+* [`remove`](/docs/starlark/built-in-methods/#listremove)
 
 ## Tuples
 
@@ -470,15 +470,15 @@ two dictionaries with `<`.
 
 A dictionary value has these methods:
 
-* [`clear`](#dict·clear)
-* [`get`](#dict·get)
-* [`items`](#dict·items)
-* [`keys`](#dict·keys)
-* [`pop`](#dict·pop)
-* [`popitem`](#dict·popitem)
-* [`setdefault`](#dict·setdefault)
-* [`update`](#dict·update)
-* [`values`](#dict·values)
+* [`clear`](/docs/starlark/built-in-methods/#dictclear)
+* [`get`](/docs/starlark/built-in-methods/#dictget)
+* [`items`](/docs/starlark/built-in-methods/#dictitems)
+* [`keys`](/docs/starlark/built-in-methods/#dictkeys)
+* [`pop`](/docs/starlark/built-in-methods/#dictpop)
+* [`popitem`](/docs/starlark/built-in-methods/#dictpopitem)
+* [`setdefault`](/docs/starlark/built-in-methods/#dictsetdefault)
+* [`update`](/docs/starlark/built-in-methods/#dictupdate)
+* [`values`](/docs/starlark/built-in-methods/#dictvalues)
 
 ## Sets
 
@@ -729,7 +729,7 @@ Turing complete unless the `-recursion` flag is specified.
 A built-in function is a function or method implemented in Go by the interpreter
 or the application into which the interpreter is embedded.
 
-The [type](#type) of a built-in function is `"builtin_function_or_method"`.
+The [type](/docs/starlark/built-in-constants-and-functions/#type) of a built-in function is `"builtin_function_or_method"`.
 <b>Implementation note:</b>
 The Java implementation of `type(x)` returns `"function"` for all
 functions, whether built in or defined in Starlark,
@@ -737,8 +737,7 @@ even though applications distinguish these two types.
 
 A built-in function value used in a Boolean context is always considered true.
 
-Many built-in functions are predeclared in the environment
-(see [Name Resolution](#name-resolution)).
+Many built-in functions are predeclared in the environment.
 Some built-in functions such as `len` are _universal_, that is,
 available to all Starlark programs.
 The host application may predeclare additional built-in functions

_documentation/starlark/expressions.md

@@ -138,7 +138,7 @@ Examples:
 The key and value expressions are evaluated in left-to-right order.
 Evaluation fails if the same key is used multiple times.
 
-Only [hashable](#hashing) values may be used as the keys of a dictionary.
+Only [hashable](/docs/starlark/value-concepts/#hashing) values may be used as the keys of a dictionary.
 This includes all built-in types except dictionaries, sets, and lists;
 a tuple is hashable only if its elements are hashable.
 
@@ -680,11 +680,11 @@ A method call such as `filename.endswith(".star")` is the composition
 of two operations, `m = filename.endswith` and `m(".star")`.
 The first, a dot operation, yields a _bound method_, a function value
 that pairs a receiver value (the `filename` string) with a choice of
-method ([string·endswith](#string·endswith)).
+method ([string·endswith](/docs/starlark/built-in-methods/#stringendswith)).
 
 Only built-in or application-defined types may have methods.
 
-See [Functions](#functions) for an explanation of function parameter passing.
+See [Functions](/docs/starlark/data-types/#functions) for an explanation of function parameter passing.
 
 ## Dot expressions
 

_documentation/starlark/lexical-elements.md

@@ -6,7 +6,7 @@ weight: 2
 A Starlark program consists of one or more modules.
 Each module is defined by a single UTF-8-encoded text file.
 
-A complete grammar of Starlark can be found in [grammar.txt](../syntax/grammar.txt).
+A complete grammar of Starlark can be found in [grammar.txt](https://github.com/google/starlark-go/blob/master/syntax/grammar.txt).
 That grammar is presented piecemeal throughout this document
 in boxes such as this one, which explains the notation:
 

_documentation/starlark/name-binding-and-variables.md

@@ -184,6 +184,6 @@ omission can be worked around by using a list of a single element.)
 
 A name appearing after a dot, such as `split` in
 `get_filename().split('/')`, is not resolved statically.
-The [dot expression](#dot-expressions) `.split` is a dynamic operation
+The [dot expression](/docs/starlark/expressions/#dot-expressions) `.split` is a dynamic operation
 on the value returned by `get_filename()`.
 

_documentation/starlark/value-concepts.md

@@ -6,7 +6,7 @@ toc: true
 
 ## Overview
 
-Starlark has eleven core [data types](#data-types).  An application
+Starlark has eleven core [data types](/docs/starlark/data-types/).  An application
 that embeds the Starlark intepreter may define additional types that
 behave like Starlark values.  All values, whether core or
 application-defined, implement a few basic behaviors:
@@ -112,7 +112,7 @@ Thus `("localhost", 80)` is hashable but `([127, 0, 0, 1], 80)` is not.
 Values of the types `function` and `builtin_function_or_method` are also hashable.
 Although functions are not necessarily immutable, as they may be
 closures that refer to mutable variables, instances of these types
-are compared by reference identity (see [Comparisons](#comparisons)),
+are compared by reference identity (see [Comparisons](/docs/starlark/expressions/#comparisons)),
 so their hash values are derived from their identity.
 
 

starlark/types/doc.go

@@ -1,6 +1,8 @@
 package types
 
 //   outline: types
+//     builtin package represents the predefined, Terraform domain-specific,
+//     functions and types in the scope of any thread of AsCode. This means
+//     that is not required to use the `load` statement, and any of the function
+//     can be called without any prefix.
 //     path: built-in
-
-

starlark/types/evaluate.go

@@ -15,6 +15,9 @@ import (
 //       evaluate(filename, predeclared=None) dict
 //         Evaluates a Starlark file and returns its global context. Kwargs may
 //         be used to set predeclared.
+//         examples:
+//           evaluable.star
+//           evaluate.star
 //         params:
 //           filename string
 //             Name of the file to execute.

starlark/types/examples_test.go

@@ -25,6 +25,10 @@ func TestExamples(t *testing.T) {
 	assert.NoError(t, err)
 
 	for _, test := range tests {
+		if test == "evaluable.star" {
+			continue
+		}
+
 		doTestExample(t, test)
 	}
 }

starlark/types/provider_test.go

@@ -5,6 +5,7 @@ import (
 	"io/ioutil"
 	"log"
 	stdos "os"
+	"path/filepath"
 	"testing"
 
 	"github.com/mcuadros/ascode/starlark/module/os"
@@ -64,11 +65,12 @@ func doTest(t *testing.T, filename string) {
 func doTestPrint(t *testing.T, filename string, print func(*starlark.Thread, string)) {
 	id = 0
 
+	dir, _ := filepath.Split(filename)
 	pm := &terraform.PluginManager{".providers"}
 
 	log.SetOutput(ioutil.Discard)
 	thread := &starlark.Thread{Load: load, Print: print}
-	thread.SetLocal("base_path", "testdata")
+	thread.SetLocal("base_path", dir)
 	thread.SetLocal(PluginManagerLocal, pm)
 
 	test.SetReporter(thread, t)

starlark/types/testdata/examples/evaluable.star

@@ -0,0 +1,3 @@
+# evaluable.star file
+print("Print from evaluable.star: '%s'" % foo)
+bar="bar"

starlark/types/testdata/examples/evaluate.star

@@ -0,0 +1,9 @@
+# Evaluate execute the given file, with the given context, in this case `foo`
+values = evaluate("evaluable.star", foo="foo")
+
+# The context it's a module, in this case contains the key `bar`
+print("Print from main: '%s'" % values.bar)
+
+# Output:
+# Print from evaluable.star: 'foo'
+# Print from main: 'bar'