mirror/ascode
1
1
Fork 0
mirror of https://github.com/mcuadros/ascode synced 2024-11-26 06:01:08 +01:00
Code Issues

cmd/doc: provider documentation generator

Browse Source
This commit is contained in:
Máximo Cuadros 2019-07-11 18:37:38 +02:00
parent 0d9142cb86
commit 84e0ec6ff8
13 changed files with 656 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@ -18,7 +18,7 @@ RUNTIME_MODULES = \
documentation: $(RUNTIME_MODULES)
$(RUNTIME_MODULES): $(DOCUMENTATION_RUNTIME_PATH)
@$(OUTLINE_CMD) package $@ > $(DOCUMENTATION_RUNTIME_PATH)/`basename $@`.md
@$(OUTLINE_CMD) package -t _scripts/template.md $@ > $(DOCUMENTATION_RUNTIME_PATH)/`basename $@`.md
$(DOCUMENTATION_RUNTIME_PATH):
mkdir -p $@

25
_documentation/runtime/base64.md
View File

@ -1,27 +1,36 @@
# base64
base64 defines base64 encoding & decoding functions, often used to represent binary as text.
---
title: 'encoding/base64'
---
base64 defines base64 encoding & decoding functions, often used to represent binary as text.
## Functions
#### `decode(src,encoding="standard") string`
#### def <b>decode</b>
```go
decode(src,encoding="standard") string
```
parse base64 input, giving back the plain string representation
**parameters:**
| name | type | description |
|------|------|-------------|
| `src` | `string` | source string of base64-encoded text |
| `encoding` | `string` | optional. string to set decoding dialect. allowed values are: standard,standard_raw,url,url_raw |
| 'src' | 'string' | source string of base64-encoded text |
| 'encoding' | 'string' | optional. string to set decoding dialect. allowed values are: standard,standard_raw,url,url_raw |
#### `encode(src,encoding="standard") string`
#### def <b>encode</b>
```go
encode(src,encoding="standard") string
```
return the base64 encoding of src
**parameters:**
| name | type | description |
|------|------|-------------|
| `src` | `string` | source string to encode to base64 |
| `encoding` | `string` | optional. string to set encoding dialect. allowed values are: standard,standard_raw,url,url_raw |
| 'src' | 'string' | source string to encode to base64 |
| 'encoding' | 'string' | optional. string to set encoding dialect. allowed values are: standard,standard_raw,url,url_raw |

35
_documentation/runtime/csv.md
View File

@ -1,32 +1,41 @@
# csv
csv reads comma-separated values files
---
title: 'encoding/csv'
---
csv reads comma-separated values files
## Functions
#### `read_all(source, comma=",", comment="", lazy_quotes=False, trim_leading_space=False, fields_per_record=0, skip=0) [][]string`
#### def <b>read_all</b>
```go
read_all(source, comma=",", comment="", lazy_quotes=False, trim_leading_space=False, fields_per_record=0, skip=0) [][]string
```
read all rows from a source string, returning a list of string lists
**parameters:**
| 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. |
| `skip` | `int` | number of rows to skip, omitting from returned rows |
| '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. |
| 'skip' | 'int' | number of rows to skip, omitting from returned rows |
#### `write_all(source,comma=",") string`
#### def <b>write_all</b>
```go
write_all(source,comma=",") string
```
write all rows from source to a csv-encoded string
**parameters:**
| 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). |
| '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). |

72
_documentation/runtime/filepath.md
View File

@ -1,96 +1,126 @@
# filepath
filepath implements utility routines for manipulating filename paths in a way compatible with the target operating system-defined file path
---
title: 'path/filepath'
---
filepath implements utility routines for manipulating filename paths in a way compatible with the target operating system-defined file path
## Functions
#### `abs(path) string`
#### def <b>abs</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `path` | `string` | relative or absolute path |
| 'path' | 'string' | relative or absolute path |
#### `base(path) string`
#### def <b>base</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `path` | `string` | input path |
| 'path' | 'string' | input path |
#### `clean(path) string`
#### def <b>clean</b>
```go
clean(path) string
```
returns the shortest path name equivalent to path by purely lexical processing.
**parameters:**
| name | type | description |
|------|------|-------------|
| `path` | `string` | input path |
| 'path' | 'string' | input path |
#### `dir(path) string`
#### def <b>dir</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `path` | `string` | input path |
| 'path' | 'string' | input path |
#### `ext(path) string`
#### def <b>ext</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `path` | `string` | input path |
| 'path' | 'string' | input path |
#### `glob(pattern) list`
#### def <b>glob</b>
```go
glob(pattern) list
```
returns the names of all files matching pattern or None if there is no matching file.
**parameters:**
| name | type | description |
|------|------|-------------|
| `pattern` | `string` | pattern ([syntax](https://golang.org/pkg/path/filepath/#Match)) |
| 'pattern' | 'string' | pattern ([syntax](https://golang.org/pkg/path/filepath/#Match)) |
#### `is_abs(path) bool`
#### def <b>is_abs</b>
```go
is_abs(path) bool
```
reports whether the path is absolute.
**parameters:**
| name | type | description |
|------|------|-------------|
| `path` | `string` | input path |
| 'path' | 'string' | input path |
#### `join(elements) string`
#### def <b>join</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `elements` | `lists` | list of path elements to be joined |
| 'elements' | 'lists' | list of path elements to be joined |
#### `rel(basepath, targpath) string`
#### def <b>rel</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `basepath` | `string` | relative or absolute path |
| `targpath` | `string` | relative or absolute path |
| 'basepath' | 'string' | relative or absolute path |
| 'targpath' | 'string' | relative or absolute path |

117
_documentation/runtime/http.md
View File

@ -1,99 +1,119 @@
# http
http defines an HTTP client implementation
---
title: ''
---
http defines an HTTP client implementation
## Functions
#### `delete(url,params={},headers={},body="",form_body={},json_body={},auth=()) response`
#### def <b>delete</b>
```go
delete(url,params={},headers={},body="",form_body={},json_body={},auth=()) response
```
perform an HTTP DELETE request, returning a response
**parameters:**
| name | type | description |
|------|------|-------------|
| `url` | `string` | url to request |
| `headers` | `dict` | optional. dictionary of headers to add to request |
| `body` | `string` | optional. raw string body to provide to the request |
| `form_body` | `dict` | optional. dict of values that will be encoded as form data |
| `json_body` | `any` | optional. json data to supply as a request. handy for working with JSON-API's |
| `auth` | `tuple` | optional. (username,password) tuple for http basic authorization |
| 'url' | 'string' | url to request |
| 'headers' | 'dict' | optional. dictionary of headers to add to request |
| 'body' | 'string' | optional. raw string body to provide to the request |
| 'form_body' | 'dict' | optional. dict of values that will be encoded as form data |
| 'json_body' | 'any' | optional. json data to supply as a request. handy for working with JSON-API's |
| 'auth' | 'tuple' | optional. (username,password) tuple for http basic authorization |
#### `get(url,params={},headers={},auth=()) response`
#### def <b>get</b>
```go
get(url,params={},headers={},auth=()) response
```
perform an HTTP GET request, returning a response
**parameters:**
| name | type | description |
|------|------|-------------|
| `url` | `string` | url to request |
| `headers` | `dict` | optional. dictionary of headers to add to request |
| `auth` | `tuple` | optional. (username,password) tuple for http basic authorization |
| 'url' | 'string' | url to request |
| 'headers' | 'dict' | optional. dictionary of headers to add to request |
| 'auth' | 'tuple' | optional. (username,password) tuple for http basic authorization |
#### `options(url,params={},headers={},body="",form_body={},json_body={},auth=()) response`
#### def <b>options</b>
```go
options(url,params={},headers={},body="",form_body={},json_body={},auth=()) response
```
perform an HTTP OPTIONS request, returning a response
**parameters:**
| name | type | description |
|------|------|-------------|
| `url` | `string` | url to request |
| `headers` | `dict` | optional. dictionary of headers to add to request |
| `body` | `string` | optional. raw string body to provide to the request |
| `form_body` | `dict` | optional. dict of values that will be encoded as form data |
| `json_body` | `any` | optional. json data to supply as a request. handy for working with JSON-API's |
| `auth` | `tuple` | optional. (username,password) tuple for http basic authorization |
| 'url' | 'string' | url to request |
| 'headers' | 'dict' | optional. dictionary of headers to add to request |
| 'body' | 'string' | optional. raw string body to provide to the request |
| 'form_body' | 'dict' | optional. dict of values that will be encoded as form data |
| 'json_body' | 'any' | optional. json data to supply as a request. handy for working with JSON-API's |
| 'auth' | 'tuple' | optional. (username,password) tuple for http basic authorization |
#### `patch(url,params={},headers={},body="",form_body={},json_body={},auth=()) response`
#### def <b>patch</b>
```go
patch(url,params={},headers={},body="",form_body={},json_body={},auth=()) response
```
perform an HTTP PATCH request, returning a response
**parameters:**
| name | type | description |
|------|------|-------------|
| `url` | `string` | url to request |
| `headers` | `dict` | optional. dictionary of headers to add to request |
| `body` | `string` | optional. raw string body to provide to the request |
| `form_body` | `dict` | optional. dict of values that will be encoded as form data |
| `json_body` | `any` | optional. json data to supply as a request. handy for working with JSON-API's |
| `auth` | `tuple` | optional. (username,password) tuple for http basic authorization |
| 'url' | 'string' | url to request |
| 'headers' | 'dict' | optional. dictionary of headers to add to request |
| 'body' | 'string' | optional. raw string body to provide to the request |
| 'form_body' | 'dict' | optional. dict of values that will be encoded as form data |
| 'json_body' | 'any' | optional. json data to supply as a request. handy for working with JSON-API's |
| 'auth' | 'tuple' | optional. (username,password) tuple for http basic authorization |
#### `post(url,params={},headers={},body="",form_body={},json_body={},auth=()) response`
#### def <b>post</b>
```go
post(url,params={},headers={},body="",form_body={},json_body={},auth=()) response
```
perform an HTTP POST request, returning a response
**parameters:**
| name | type | description |
|------|------|-------------|
| `url` | `string` | url to request |
| `headers` | `dict` | optional. dictionary of headers to add to request |
| `body` | `string` | optional. raw string body to provide to the request |
| `form_body` | `dict` | optional. dict of values that will be encoded as form data |
| `json_body` | `any` | optional. json data to supply as a request. handy for working with JSON-API's |
| `auth` | `tuple` | optional. (username,password) tuple for http basic authorization |
| 'url' | 'string' | url to request |
| 'headers' | 'dict' | optional. dictionary of headers to add to request |
| 'body' | 'string' | optional. raw string body to provide to the request |
| 'form_body' | 'dict' | optional. dict of values that will be encoded as form data |
| 'json_body' | 'any' | optional. json data to supply as a request. handy for working with JSON-API's |
| 'auth' | 'tuple' | optional. (username,password) tuple for http basic authorization |
#### `put(url,params={},headers={},body="",form_body={},json_body={},auth=()) response`
#### def <b>put</b>
```go
put(url,params={},headers={},body="",form_body={},json_body={},auth=()) response
```
perform an HTTP PUT request, returning a response
**parameters:**
| name | type | description |
|------|------|-------------|
| `url` | `string` | url to request |
| `headers` | `dict` | optional. dictionary of headers to add to request |
| `body` | `string` | optional. raw string body to provide to the request |
| `form_body` | `dict` | optional. dict of values that will be encoded as form data |
| `json_body` | `any` | optional. json data to supply as a request. handy for working with JSON-API's |
| `auth` | `tuple` | optional. (username,password) tuple for http basic authorization |
| 'url' | 'string' | url to request |
| 'headers' | 'dict' | optional. dictionary of headers to add to request |
| 'body' | 'string' | optional. raw string body to provide to the request |
| 'form_body' | 'dict' | optional. dict of values that will be encoded as form data |
| 'json_body' | 'any' | optional. json data to supply as a request. handy for working with JSON-API's |
| 'auth' | 'tuple' | optional. (username,password) tuple for http basic authorization |
## Types
### `response`
### 'response'
the result of performing a http request
**Fields**
@ -105,10 +125,17 @@ the result of performing a http request
| headers | dict | dictionary of response headers |
| encoding | string | transfer encoding. example: "octet-stream" or "application/json" |
**Methods**
#### `body() string`
#### def <b>body</b>
```go
body() string
```
output response body as a string
#### `json()`
#### def <b>json</b>
```go
json()
```
attempt to parse resonse body as json, returning a JSON-decoded result

21
_documentation/runtime/json.md
View File

@ -1,25 +1,34 @@
# json
json provides functions for working with json data
---
title: 'encoding/json'
---
json provides functions for working with json data
## Functions
#### `dumps(obj) string`
#### def <b>dumps</b>
```go
dumps(obj) string
```
serialize obj to a JSON string
**parameters:**
| name | type | description |
|------|------|-------------|
| `obj` | `object` | input object |
| 'obj' | 'object' | input object |
#### `loads(source) object`
#### def <b>loads</b>
```go
loads(source) object
```
read a source JSON string to a starlark object
**parameters:**
| name | type | description |
|------|------|-------------|
| `source` | `string` | input string of json data |
| 'source' | 'string' | input string of json data |

98
_documentation/runtime/os.md
View File

@ -1,116 +1,152 @@
# os
os provides a platform-independent interface to operating system functionality.
---
title: 'os'
---
os provides a platform-independent interface to operating system functionality.
## Functions
#### `chdir(dir)`
#### def <b>chdir</b>
```go
chdir(dir)
```
changes the current working directory to the named directory.
**parameters:**
| name | type | description |
|------|------|-------------|
| `dir` | `string` | target dir |
| 'dir' | 'string' | target dir |
#### `getenv(key) dir`
#### def <b>getenv</b>
```go
getenv(key) dir
```
retrieves the value of the environment variable named by the key.
**parameters:**
| name | type | description |
|------|------|-------------|
| `key` | `string` | name of the environment variable |
| 'key' | 'string' | name of the environment variable |
#### `getwd() dir`
#### def <b>getwd</b>
```go
getwd() dir
```
returns a rooted path name corresponding to the current directory.
#### `mkdir(name, perms=0o777)`
#### def <b>mkdir</b>
```go
mkdir(name, perms=0o777)
```
creates a new directory with the specified name and permission bits (before umask).
**parameters:**
| name | type | description |
|------|------|-------------|
| `name` | `string` | name of the folder to be created |
| `perms` | `int` | optional, permission of the folder |
| 'name' | 'string' | name of the folder to be created |
| 'perms' | 'int' | optional, permission of the folder |
#### `mkdir_all(name, perms=0o777)`
#### def <b>mkdir_all</b>
```go
mkdir_all(name, perms=0o777)
```
creates a new directory with the specified name and permission bits (before umask).
**parameters:**
| name | type | description |
|------|------|-------------|
| `name` | `string` | name of the folder to be created |
| `perms` | `int` | optional, permission of the folder |
| 'name' | 'string' | name of the folder to be created |
| 'perms' | 'int' | optional, permission of the folder |
#### `read_file(filename) string`
#### def <b>read_file</b>
```go
read_file(filename) string
```
reads the file named by filename and returns the contents.
**parameters:**
| name | type | description |
|------|------|-------------|
| `filename` | `string` | name of the file to be written |
| `data` | `string` | content to be witten to the file |
| `perms` | `int` | optional, permission of the file |
| 'filename' | 'string' | name of the file to be written |
| 'data' | 'string' | content to be witten to the file |
| 'perms' | 'int' | optional, permission of the file |
#### `remove(name)`
#### def <b>remove</b>
```go
remove(name)
```
removes the named file or (empty) directory.
**parameters:**
| name | type | description |
|------|------|-------------|
| `name` | `string` | name of the file or directory to be deleted |
| 'name' | 'string' | name of the file or directory to be deleted |
#### `remove_all(path)`
#### def <b>remove_all</b>
```go
remove_all(path)
```
removes path and any children it contains. It removes everything it can but returns the first error it encounters.
**parameters:**
| name | type | description |
|------|------|-------------|
| `name` | `string` | path to be deleted |
| 'name' | 'string' | path to be deleted |
#### `rename(oldpath, newpath)`
#### def <b>rename</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `oldpath` | `string` | old path |
| `newpath` | `string` | new path |
| 'oldpath' | 'string' | old path |
| 'newpath' | 'string' | new path |
#### `setenv(key, value) dir`
#### def <b>setenv</b>
```go
setenv(key, value) dir
```
sets the value of the environment variable named by the key.
**parameters:**
| name | type | description |
|------|------|-------------|
| `key` | `string` | name of the environment variable |
| `value` | `string` | value of the environment variable |
| 'key' | 'string' | name of the environment variable |
| 'value' | 'string' | value of the environment variable |
#### `write_file(filename, data, perms=0o644)`
#### def <b>write_file</b>
```go
write_file(filename, data, perms=0o644)
```
retrieves the value of the environment variable named by the key.
**parameters:**
| name | type | description |
|------|------|-------------|
| `filename` | `string` | name of the file to be written |
| `data` | `string` | content to be witten to the file |
| `perms` | `int` | optional, permission of the file |
| 'filename' | 'string' | name of the file to be written |
| 'data' | 'string' | content to be witten to the file |
| 'perms' | 'int' | optional, permission of the file |

46
_documentation/runtime/re.md
View File

@ -1,44 +1,56 @@
# re
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
---
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
## Functions
#### `findall(pattern, text, flags=0)`
#### def <b>findall</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `pattern` | `string` | regular expression pattern string |
| `text` | `string` | string to find within |
| `flags` | `int` | integer flags to control regex behaviour. reserved for future use |
| 'pattern' | 'string' | regular expression pattern string |
| 'text' | 'string' | string to find within |
| 'flags' | 'int' | integer flags to control regex behaviour. reserved for future use |
#### `split(pattern, text, maxsplit=0, flags=0)`
#### def <b>split</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `pattern` | `string` | regular expression pattern string |
| `text` | `string` | input string to split |
| `maxsplit` | `int` | maximum number of splits to make. default 0 splits all matches |
| `flags` | `int` | integer flags to control regex behaviour. reserved for future use |
| 'pattern' | 'string' | regular expression pattern string |
| 'text' | 'string' | input string to split |
| 'maxsplit' | 'int' | maximum number of splits to make. default 0 splits all matches |
| 'flags' | 'int' | integer flags to control regex behaviour. reserved for future use |
#### `sub(pattern, repl, text, count=0, flags=0)`
#### def <b>sub</b>
```go
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.
**parameters:**
| name | type | description |
|------|------|-------------|
| `pattern` | `string` | regular expression pattern string |
| `repl` | `string` | string to replace matches with |
| `text` | `string` | input string to replace |
| `count` | `int` | number of replacements to make, default 0 means replace all matches |
| `flags` | `int` | integer flags to control regex behaviour. reserved for future use |
| 'pattern' | 'string' | regular expression pattern string |
| 'repl' | 'string' | string to replace matches with |
| 'text' | 'string' | input string to replace |
| 'count' | 'int' | number of replacements to make, default 0 means replace all matches |
| 'flags' | 'int' | integer flags to control regex behaviour. reserved for future use |

BIN
cmd/ascode-doc/doc/.providers/terraform-provider-ignition_v1.1.0_x4 Executable file
View File

Binary file not shown.

81
cmd/ascode-doc/doc/fixtures/ignition_file.md Normal file
View File

@ -0,0 +1,81 @@
---
layout: "ignition"
page_title: "Ignition: ignition_file"
sidebar_current: "docs-ignition-datasource-file"
description: |-
Describes a file to be written in a particular filesystem.
---
# ignition\_file
Describes a file to be written in a particular filesystem.
## Example Usage
File with inline content:
```hcl
data "ignition_file" "hello" {
filesystem = "foo"
path = "/hello.txt"
content {
content = "Hello World!"
}
}
```
File with remote content:
```hcl
data "ignition_file" "hello" {
filesystem = "qux"
path = "/hello.txt"
source {
source = "http://example.com/hello.txt.gz"
compression = "gzip"
verification = "sha512-0123456789abcdef0123456789...456789abcdef"
}
}
```
## Argument Reference
The following arguments are supported:
* `filesystem` - (Required) The internal identifier of the filesystem. This matches the last filesystem with the given identifier. This should be a valid name from a _ignition\_filesystem_ resource.
* `path` - (Required) The absolute path to the file.
* `content` - (Optional) Block to provide the file content inline.
* `source` - (Optional) Block to retrieve the file content from a remote location.
__Note__: `content` and `source` are mutually exclusive.
* `mode` - (Optional) The file's permission mode. The mode must be properly specified as a decimal value (i.e. 0644 -> 420).
* `uid` - (Optional) The user ID of the owner.
* `gid` - (Optional) The group ID of the owner.
The `content` block supports:
* `mime` - (Required) MIME format of the content (default _text/plain_).
* `content` - (Required) Content of the file.
The `source` block supports:
* `source` - (Required) The URL of the file contents. Supported schemes are http, https, tftp, s3, and [data][rfc2397]. When using http, it is advisable to use the verification option to ensure the contents haven't been modified.
* `compression` - (Optional) The type of compression used on the contents (null or gzip). Compression cannot be used with S3.
* `verification` - (Optional) The hash of the config, in the form _\<type\>-\<value\>_ where type is sha512.
## Attributes Reference
The following attributes are exported:
* `id` - ID used to reference this resource in _ignition_config_.
[rfc2397]: https://tools.ietf.org/html/rfc2397

225
cmd/ascode-doc/doc/provider.go Normal file
View File

@ -0,0 +1,225 @@
package doc
import (
"bufio"
"fmt"
"io"
"os"
"regexp"
"strings"
"github.com/ascode-dev/ascode/starlark/types"
"github.com/b5/outline/lib"
"github.com/hashicorp/terraform/configs/configschema"
"github.com/hashicorp/terraform/providers"
"gopkg.in/src-d/go-git.v4"
"gopkg.in/src-d/go-git.v4/plumbing/object"
"gopkg.in/src-d/go-git.v4/storage/memory"
)
type ResourceDocumentation struct {
Name string
Type string
Attribs map[string]string
Blocks map[string]map[string]string
}
func NewResourceDocumentation(typ, name string) *ResourceDocumentation {
return &ResourceDocumentation{
Name: name,
Type: typ,
Attribs: make(map[string]string, 0),
Blocks: make(map[string]map[string]string, 0),
}
}
var re = regexp.MustCompile(`\*[. ][\x60](.*)[\x60].*\) (.*)`)
// https://regex101.com/r/hINfBI/2
var blockRe = regexp.MustCompile(`^[^\*].*\x60(.*)\x60 block(?:s?)`)
func (r *ResourceDocumentation) Decode(doc io.Reader) error {
var block string
buf := bufio.NewReader(doc)
for {
line, err := buf.ReadString('\n')
if err == io.EOF {
return nil
}
if err != nil {
return err
}
line = strings.TrimSpace(line)
if len(line) == 0 {
continue
}
parts := re.FindStringSubmatch(line)
if len(parts) == 3 {
if block == "" {
r.AddAttrib(parts[1], parts[2])
continue
}
r.AddBlockAttrib(block, parts[1], parts[2])
continue
}
parts = blockRe.FindStringSubmatch(line)
if len(parts) == 2 {
block = parts[1]
}
}
return nil
}
func (r *ResourceDocumentation) AddAttrib(name, desc string) {
r.Attribs[name] = desc
}
func (r *ResourceDocumentation) AddBlockAttrib(block, name, desc string) {
if _, ok := r.Blocks[block]; !ok {
r.Blocks[block] = make(map[string]string, 0)
}
r.Blocks[block][name] = desc
}
type Documentation struct {
name string
repository *git.Repository
head *object.Commit
resources map[string]map[string]string
}
func NewDocumentation(name string) (*Documentation, error) {
d := &Documentation{
name: name,
resources: make(map[string]map[string]string, 0),
}
return d, d.initRepository()
}
func (d *Documentation) initRepository() error {
storer := memory.NewStorage()
var err error
d.repository, err = git.Clone(storer, nil, &git.CloneOptions{
URL: fmt.Sprintf("https://github.com/terraform-providers/terraform-provider-%s.git", d.name),
Depth: 1,
// as git does, when you make a clone, pull or some other operations the
// server sends information via the sideband, this information can being
// collected provinding a io.Writer to the CloneOptions options
Progress: os.Stdout,
})
h, err := d.repository.Head()
if err != nil {
return err
}
d.head, err = d.repository.CommitObject(h.Hash())
return err
}
func (d *Documentation) Resource(typ, name string) (*ResourceDocumentation, error) {
parts := strings.SplitN(name, "_", 2)
name = parts[1]
filename := fmt.Sprintf("website/docs/%s/%s.html.md", typ, name)
file, err := d.head.File(filename)
if err != nil {
return nil, err
}
r, err := file.Reader()
if err != nil {
return nil, err
}
resource := NewResourceDocumentation(typ, name)
return resource, resource.Decode(r)
}
func (d *Documentation) Do(name string, schema providers.GetSchemaResponse) *lib.Doc {
doc := &lib.Doc{}
doc.Name = name
doc.Path = name
for name, schema := range schema.DataSources {
doc.Types = append(doc.Types, d.schemaToDoc(name, &schema)...)
}
return doc
}
func (d *Documentation) schemaToDoc(resource string, s *providers.Schema) []*lib.Type {
rd, err := d.Resource("d", resource)
if err != nil {
panic(err)
}
fmt.Println(resource, rd)
typ := &lib.Type{}
typ.Name = resource
for name, attr := range s.Block.Attributes {
typ.Fields = append(typ.Fields, d.attributeToField(rd.Attribs, name, attr))
}
types := []*lib.Type{typ}
for name, block := range s.Block.BlockTypes {
types = append(types, d.blockToType(rd, resource, name, block))
typ.Fields = append(typ.Fields, d.blockToField(rd, resource, name, block))
}
return types
}
func (d *Documentation) blockToType(rd *ResourceDocumentation, resource, name string, block *configschema.NestedBlock) *lib.Type {
typ := &lib.Type{}
typ.Name = fmt.Sprintf("%s.%s", resource, name)
for n, attr := range block.Attributes {
//fmt.Println(rd.Blocks[name])
typ.Fields = append(typ.Fields, d.attributeToField(rd.Blocks[name], n, attr))
}
return typ
}
func (d *Documentation) blockToField(rd *ResourceDocumentation, resource, name string, block *configschema.NestedBlock) *lib.Field {
field := &lib.Field{}
nested := fmt.Sprintf("%s.%s", resource, name)
field.Name = name
if block.MaxItems != 1 {
field.Type = fmt.Sprintf("collection<%s>", nested)
} else {
field.Type = nested
}
return field
}
func (d *Documentation) attributeToField(doc map[string]string, name string, attr *configschema.Attribute) *lib.Field {
field := &lib.Field{}
field.Name = name
field.Description, _ = doc[name]
if attr.Computed && !attr.Optional {
field.Type = "computed"
} else {
field.Type = types.MustTypeFromCty(attr.Type).Starlark()
}
return field
}

71
cmd/ascode-doc/doc/provider_test.go Normal file
View File

@ -0,0 +1,71 @@
package doc
import (
"fmt"
"io/ioutil"
"os"
"strings"
"testing"
"text/template"
"github.com/ascode-dev/ascode/terraform"
"github.com/hashicorp/terraform/plugin"
"github.com/stretchr/testify/assert"
)
func TestDocumentation(t *testing.T) {
f, err := os.Open("fixtures/ignition_file.md")
assert.NoError(t, err)
res := NewResourceDocumentation("d", "ignition_file")
res.Decode(f)
assert.Len(t, res.Attribs, 7)
assert.Len(t, res.Blocks["content"], 2)
assert.Len(t, res.Blocks["source"], 3)
}
func TestDo(t *testing.T) {
pm := &terraform.PluginManager{".providers"}
cli, meta := pm.Get("ignition", "1.1.0")
fmt.Println(meta)
rpc, err := cli.Client()
if err != nil {
panic(err)
}
raw, err := rpc.Dispense(plugin.ProviderPluginName)
if err != nil {
panic(err)
}
provider := raw.(*plugin.GRPCProvider)
response := provider.GetSchema()
rd, err := NewDocumentation("ignition")
assert.NoError(t, err)
doc := rd.Do(meta.Name, response)
str, err := ioutil.ReadFile("../../_scripts/template.md")
if err != nil {
fmt.Println(err)
os.Exit(1)
}
tplFuncMap := make(template.FuncMap)
tplFuncMap["split"] = strings.Split
temp, err := template.New("foo").Funcs(tplFuncMap).Parse(string(str))
if err != nil {
fmt.Println(err)
os.Exit(1)
}
if err := temp.Execute(os.Stdout, []interface{}{doc}); err != nil {
fmt.Println(err.Error())
os.Exit(1)
}
}

6
examples/encoding.star
View File

@ -1,5 +1,7 @@
load("encoding/json", "json")
load("encoding/base64", "base64")
load("os", "os")
load("path/filepath", "filepath")
ignition = provider("ignition", "1.1.0")
@ -10,4 +12,6 @@ user.groups = ["foo", "bar"]
user.system = True
print(json.dumps(user.__dict__))
print(base64.encode("foo"))
print(base64.encode("foo"))
print(filepath.base(os.getwd()))