mirror/ascode
1
1
Fork 0
mirror of https://github.com/mcuadros/ascode synced 2024-11-29 21:11:22 +01:00
Code Issues

documentation: runtime modules

Browse Source 
Signed-off-by: Máximo Cuadros <mcuadros@gmail.com>
This commit is contained in:
Máximo Cuadros 2019-07-10 01:54:15 +02:00
parent 72c20c9609
commit 0d9142cb86
8 changed files with 478 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
Makefile Normal file
View File

@ -0,0 +1,24 @@
OUTLINE_CMD ?= outline
DOCUMENTATION_PATH ?= _documentation
DOCUMENTATION_RUNTIME_PATH ?= $(DOCUMENTATION_PATH)/runtime
RUNTIME_MODULES = \
github.com/ascode-dev/ascode/starlark/module/os \
github.com/ascode-dev/ascode/starlark/module/filepath \
github.com/qri-io/starlib/encoding/base64 \
github.com/qri-io/starlib/encoding/csv \
github.com/qri-io/starlib/encoding/json \
github.com/qri-io/starlib/re \
github.com/qri-io/starlib/http
# Rules
.PHONY: $(RUNTIME_MODULES) documentation
documentation: $(RUNTIME_MODULES)
$(RUNTIME_MODULES): $(DOCUMENTATION_RUNTIME_PATH)
@$(OUTLINE_CMD) package $@ > $(DOCUMENTATION_RUNTIME_PATH)/`basename $@`.md
$(DOCUMENTATION_RUNTIME_PATH):
mkdir -p $@

27
_documentation/runtime/base64.md Normal file
View File

@ -0,0 +1,27 @@
# base64
base64 defines base64 encoding & decoding functions, often used to represent binary as text.
## Functions
#### `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 |
#### `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 |

32
_documentation/runtime/csv.md Normal file
View File

@ -0,0 +1,32 @@
# 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`
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 |
#### `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). |

96
_documentation/runtime/filepath.md Normal file
View File

@ -0,0 +1,96 @@
# 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`
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 |
#### `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 |
#### `clean(path) string`
returns the shortest path name equivalent to path by purely lexical processing.
**parameters:**
| name | type | description |
|------|------|-------------|
| `path` | `string` | input path |
#### `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 |
#### `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 |
#### `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)) |
#### `is_abs(path) bool`
reports whether the path is absolute.
**parameters:**
| name | type | description |
|------|------|-------------|
| `path` | `string` | input path |
#### `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 |
#### `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 |

114
_documentation/runtime/http.md Normal file
View File

@ -0,0 +1,114 @@
# http
http defines an HTTP client implementation
## Functions
#### `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 |
#### `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 |
#### `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 |
#### `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 |
#### `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 |
#### `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 |
## Types
### `response`
the result of performing a http request
**Fields**
| name | type | description |
|------|------|-------------|
| url | string | the url that was ultimately requested (may change after redirects) |
| status_code | int | response status code (for example: 200 == OK) |
| headers | dict | dictionary of response headers |
| encoding | string | transfer encoding. example: "octet-stream" or "application/json" |
**Methods**
#### `body() string`
output response body as a string
#### `json()`
attempt to parse resonse body as json, returning a JSON-decoded result

25
_documentation/runtime/json.md Normal file
View File

@ -0,0 +1,25 @@
# json
json provides functions for working with json data
## Functions
#### `dumps(obj) string`
serialize obj to a JSON string
**parameters:**
| name | type | description |
|------|------|-------------|
| `obj` | `object` | input object |
#### `loads(source) object`
read a source JSON string to a starlark object
**parameters:**
| name | type | description |
|------|------|-------------|
| `source` | `string` | input string of json data |

116
_documentation/runtime/os.md Normal file
View File

@ -0,0 +1,116 @@
# os
os provides a platform-independent interface to operating system functionality.
## Functions
#### `chdir(dir)`
changes the current working directory to the named directory.
**parameters:**
| name | type | description |
|------|------|-------------|
| `dir` | `string` | target dir |
#### `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 |
#### `getwd() dir`
returns a rooted path name corresponding to the current directory.
#### `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 |
#### `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 |
#### `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 |
#### `remove(name)`
removes the named file or (empty) directory.
**parameters:**
| name | type | description |
|------|------|-------------|
| `name` | `string` | name of the file or directory to be deleted |
#### `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 |
#### `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 |
#### `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 |
#### `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 |

44
_documentation/runtime/re.md Normal file
View File

@ -0,0 +1,44 @@
# 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
## Functions
#### `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 |
#### `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 |
#### `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 |