spec outlining packages, namespaces, and imports
parent
9112031ea9
commit
24f1be808d
|
@ -94,7 +94,7 @@ Examples:
|
|||
The following keywords are reserved and may not be used as identifiers:
|
||||
|
||||
and import not return
|
||||
empty in or
|
||||
empty in or package
|
||||
|
||||
[IMPL#256](https://github.com/influxdata/platform/issues/256) Add in and empty operator support
|
||||
[IMPL#334](https://github.com/influxdata/platform/issues/334) Add "import" support
|
||||
|
@ -456,7 +456,7 @@ Flux is lexically scoped using blocks:
|
|||
1. The scope of an option identifier is the options block.
|
||||
2. The scope of a preassigned (non-option) identifier is in the universe block.
|
||||
3. The scope of an identifier denoting a variable or function at the top level (outside any function) is the package block.
|
||||
4. The scope of a package name of an imported package is the file block of the file containing the import declaration.
|
||||
4. The scope of the name of an imported package is the file block of the file containing the import declaration.
|
||||
5. The scope of an identifier denoting a function argument is the function body.
|
||||
6. The scope of a variable assigned inside a function is the innermost containing block.
|
||||
|
||||
|
@ -465,8 +465,6 @@ While the identifier of the inner assignment is in scope, it denotes the entity
|
|||
|
||||
Option identifiers have default assignments that are automatically defined in the _options block_.
|
||||
Because the _options block_ is the top-level block of a Flux program, options are visible/available to any and all other blocks.
|
||||
However option values may only be reassigned or overridden in the explicit block denoting the main (executable) package.
|
||||
Assignment of option identifiers in any non-executable package is strictly prohibited.
|
||||
|
||||
The package clause is not a assignment; the package name does not appear in any scope.
|
||||
Its purpose is to identify the files belonging to the same package and to specify the default package name for import declarations.
|
||||
|
@ -569,12 +567,66 @@ Examples:
|
|||
baz = (y=<-) => // function body elided
|
||||
foo() |> bar() |> baz() // equivalent to baz(x:bar(y:foo()))
|
||||
|
||||
### Program
|
||||
|
||||
A Flux program is a sequence of statements defined by
|
||||
|
||||
Program = [PackageStatement] [ImportList] StatementList .
|
||||
ImportList = { ImportStatement } .
|
||||
|
||||
### Statements
|
||||
|
||||
A statement controls execution.
|
||||
|
||||
Statement = OptionStatement | VarAssignment | ReturnStatement |
|
||||
ExpressionStatement | BlockStatment .
|
||||
Statement = OptionStatement | VarAssignment |
|
||||
ReturnStatement | ExpressionStatement | BlockStatment .
|
||||
|
||||
#### Package statement
|
||||
|
||||
PackageStatement = "package" identifier .
|
||||
|
||||
A package statement defines a package block.
|
||||
Package names must be valid Flux identifiers.
|
||||
The package statement must be the first statement of every Flux source file.
|
||||
If a file does not declare a package statement, all identifiers in that file will belong to the special _main_ package.
|
||||
|
||||
##### package main
|
||||
|
||||
The _main_ package is special for a few reasons:
|
||||
|
||||
1. It defines the entrypoint of a Flux program
|
||||
2. It cannot be imported
|
||||
3. All query specifications produced after evaluating the _main_ package are coerced into producing side effects
|
||||
|
||||
#### Import statement
|
||||
|
||||
ImportStatement = "import" [identifier] `"` unicode_char { unicode_char } `"`.
|
||||
|
||||
Associated with every package is a package name and an import path.
|
||||
The import statement takes a package's import path and brings all of the identifiers defined in that package into the current scope.
|
||||
The import statment defines a namespace through which to access the imported identifiers.
|
||||
By default the identifer of this namespace is the package name unless otherwise specified.
|
||||
For example, given a variable `x` declared in package `foo`, importing `foo` and referencing `x` would look like this:
|
||||
|
||||
```
|
||||
import "import/path/to/package/foo"
|
||||
|
||||
foo.x
|
||||
```
|
||||
|
||||
Or this:
|
||||
|
||||
```
|
||||
import bar "import/path/to/package/foo"
|
||||
|
||||
bar.x
|
||||
```
|
||||
|
||||
A package's import path is always absolute.
|
||||
Flux does not support relative imports.
|
||||
Assigment into the namespace of an imported package is not allowed.
|
||||
A package cannot access nor modify the identifiers belonging to the imported packages of its imported packages.
|
||||
Every statement contained in an imported package is evaluated.
|
||||
|
||||
#### Option statements
|
||||
|
||||
|
@ -651,6 +703,15 @@ Examples:
|
|||
f()
|
||||
a
|
||||
|
||||
### Side Effects
|
||||
|
||||
Side effects can occur in two ways.
|
||||
|
||||
1. By reassigning builtin options
|
||||
2. By calling a function that produces side effects
|
||||
|
||||
A function produces side effects when it is explicitly declared to have side effects or when it calls a function that itself produces side effects.
|
||||
|
||||
### Built-in functions
|
||||
|
||||
The following functions are preassigned in the universe block.
|
||||
|
@ -926,12 +987,13 @@ Examples:
|
|||
The execution of a query is separate and distinct from the execution of Flux the language.
|
||||
The input into the query engine is a query specification.
|
||||
|
||||
The output of an Flux program is a query specification, which then may be passed into the query execution engine.
|
||||
The output of a Flux program is a query specification, which then may be passed into the query execution engine.
|
||||
|
||||
### Query specification
|
||||
|
||||
A query specification consists of a set of operations and a set of edges between those operations.
|
||||
The operations and edges must form a directed acyclic graph (DAG).
|
||||
A query specification produces side effects when at least one of its operations produces side effects.
|
||||
|
||||
#### Encoding
|
||||
|
||||
|
@ -1047,6 +1109,8 @@ Most operations output one table for every table they receive from the input str
|
|||
|
||||
Operations that modify the group keys or values will need to regroup the tables in the output stream.
|
||||
|
||||
An operation produces side effects when it is constructed from a function that produces side effects.
|
||||
|
||||
### Built-in operations
|
||||
|
||||
#### From
|
||||
|
@ -1096,6 +1160,8 @@ Yield has the following properties:
|
|||
Example:
|
||||
`from(bucket: "telegraf/autogen") |> range(start: -5m) |> yield(name:"1")`
|
||||
|
||||
**Note:** The `yield` function produces side effects.
|
||||
|
||||
#### Aggregate operations
|
||||
|
||||
Aggregate operations output a table for every input table they receive.
|
||||
|
@ -2141,6 +2207,8 @@ _tag1=a hum=55.4,temp=99.3 0006
|
|||
_tag1=a hum=55.5,temp=99.9 0007
|
||||
```
|
||||
|
||||
**Note:** The `to` function produces side effects.
|
||||
|
||||
#### Type conversion operations
|
||||
|
||||
##### toBool
|
||||
|
|
Loading…
Reference in New Issue