Values

Search…
🌊
Aqua Book
Introduction
Values
Aqua is all about combining data and computations. The runtime for the compiled Aqua code, AquaVM, tracks what data comes from what origin, which constitutes the foundation for distributed systems security. That approach, driven by π-calculus and security considerations of open-by-default networks and distributed applications as custom application protocols, also puts constraints on the language that configures it.
Values in Aqua are backed by VDS (Verifiable Data Structures) in the runtime. All operations on values must keep the authenticity of data, prooved by signatures under the hood.
That's why values are immutable. Changing the value effectively makes a new one:
1
x = "hello"
2
y = "world"
3
​
4
-- despite the sources of x and y, z's origin is "peer 1"
5
-- and we can trust value of z as much as we trust "peer 1"
6
on "peer 1":
7
  z <- concat(x, y)
Copied!
More on that in the Security section. Now let's see how we can work with values inside the language.
Arguments
Function arguments are available within the whole function body.
1
func foo(arg: i32, log: string -> ()):
2
  -- Use data arguments
3
  bar(arg)
4
​
5
  -- Arguments can have arrow type and be used as strings
6
  log("Wrote arg to responses")
Copied!
Return values
You can assign the results of an arrow call to a name and use this returned value in the code below.
1
-- Imagine a Stringify service that's always available
2
service Stringify("stringify"):
3
  i32ToStr(arg: i32) -> string
4
​
5
-- Define the result type of a function
6
func bar(arg: i32) -> string:
7
  -- Make a value, name it x
8
  x <- Stringify.i32ToStr(arg)
9
  -- Starting from there, you can use x
10
  -- Pass x out of the function scope as the return value
11
  <- x
12
​
13
​
14
func foo(arg: i32, log: *string):
15
  -- Use bar to convert arg to string, push that string
16
  -- to logs stream, return nothing
17
  log <- bar(arg)
Copied!
Aqua functions may return more than one value.
1
-- Define return types as a comma separated list
2
func myFunc() -> bool, string:
3
  -- Function must return values for all defined types
4
  <- true, "successful execution"
5
  
6
func otherFunc():
7
  -- Call a function, don't use returns
8
  myFunc()  
9
  -- Get any number of results out of the function
10
  flag <- myFunc()
11
  
12
  -- Push results to a stream
13
  results: *string
14
  is_ok, results <- myFunc()
15
  if is_ok:
16
    -- We know that it contains successful result
17
    foo(results!)
Copied!
Literals
Aqua supports just a few literals: numbers, quoted strings, booleans, and nil. You cannot init a structure in Aqua, only obtain it as a result of a function call.
1
-- String literals cannot contain double quotes
2
-- No single-quoted strings allowed, no escape chars.
3
foo("double quoted string literal")
4
​
5
-- Booleans are true or false
6
if x == false:
7
  foo("false is a literal")
8
​
9
-- Numbers are different
10
-- Any number:
11
bar(1)  
12
​
13
-- Signed number:
14
bar(-1)
15
​
16
-- Float:
17
bar(-0.2)
18
​
19
func takesMaybe(arg: ?string): ...
20
​
21
-- nil can be passed in every place
22
-- where a read-only collection fits
23
takesMaybe(nil)
Copied!
Arithmetic operators
Aqua offers a list of arithmetic and logic operators, introduced in Aqua 0.7.1.
1
-- Addition
2
func foo(a: i32, b: i32) -> i32:
3
  c = a + b
4
  d = c - a
5
  e = d * c
6
  f = e / d
7
  -- power 3: unsigned number expected
8
  g = f ** 3
9
  -- remainder
10
  e = g % f
11
  
12
  -- Can use arithmetics anywhere
13
  -- Better use brackets to enforce ordering
14
  <- (a + b) - (c + d * (e - 6 ))
Copied!
Collections
With Aqua it is possible to create a stream, fill it with values, and use in place of any collection:
1
-- foo returns an array
2
func foo() -> []string:
3
  -- Initiate a typed stream
4
  ret: *string
5
  
6
  -- Push values into the stream
7
  ret <<- "first"
8
  ret <<- "second"
9
  
10
  -- Return the stream in place of the array
11
  <- ret
Copied!
Aqua provides syntax sugar for creating any of the collection types with [ ... ] for arrays, ?[ ... ] for optional values, *[ ... ] for streams.
1
func foo() -> []string, ?bool, *u32:
2
  <- ["string1", "string2"], ?[true, false], *[1, 3, 5]
Copied!
The ?[] expression takes any number of arguments, but returns an optional value that contains only 0 or 1 value. This is done by trying to yield these values one by one. The first value that yields without an error will be added to the resulting option.
1
func getFlag(maybeFlagA: ?bool, maybeFlagB: ?bool, default: bool) -> bool:
2
  res = ?[maybeFlagA!, maybeFlagB!, default]
3
  <- res!
Copied!
As of Aqua 0.6.3, it is not possible to get an element by index directly from the collection creation expression.
Getters
In Aqua, you can use a getter to peek into a field of a product or indexed element in an array.
1
data Sub:
2
  sub: string
3
​
4
data Example:
5
  field: u32
6
  arr: []Sub
7
  child: Sub
8
​
9
func foo(e: Example):
10
  bar(e.field) -- u32
11
  bar(e.child) -- Sub
12
  bar(e.child.sub) -- string
13
  bar(e.arr) -- []Sub
14
  bar(e.arr!) -- gets the 0 element
15
  bar(e.arr!.sub) -- string
16
  bar(e.arr!2) -- gets the 2nd element
17
  bar(e.arr!2.sub) -- string
18
  bar(e.arr[2]) -- gets the 2nd element
19
  bar(e.arr[2].sub) -- string
20
  bar(e.arr[e.field]) -- can use any scalar as index with [] syntax
Copied!
Note that the ! operator may fail or halt:
If it is called on an immutable collection, it will fail if the collection is shorter and has no given index; you can handle the error with try or otherwise.
If it is called on an appendable stream, it will wait for some parallel append operation to fulfill, see Join behavior.
The ! operator can currently only be used with literal indices.
That is,!2 is valid but!x is not valid.
To access an index with non-literal, use the brackets index, like [x].
Assignments
Assignments, =, only give a name to a value with an applied getter or to a literal.
1
func foo(arg: bool, e: Example):
2
  -- Rename the argument
3
  a = arg
4
  -- Assign the name b to value of e.child
5
  b = e.child
6
  -- Create a named literal
7
  c = "just string value"
Copied!
Constants
Constants are like assignments but in the root scope. They can be used in all function bodies, textually below the place of const definition. Constant values must resolve to a literal.
You can change the compilation results by overriding a constant but the override needs to be of the same type or subtype.
Constants are always UPPER_CASE.
1
-- This FLAG is always true
2
const FLAG = true
3
​
4
-- This SETTING can be overwritten via CLI flag
5
const SETTING ?= "value"
6
​
7
func foo(arg: string): ...
8
​
9
func bar():
10
  -- Type of SETTING is string
11
  foo(SETTING)
Copied!
Visibility scopes
Visibility scopes follow the contracts of execution flow.
By default, everything defined textually above is available below. With some exceptions.
Functions have isolated scopes:
1
func foo():
2
   a = 5
3
​
4
func bar():
5
   -- a is not defined in this function scope
6
   a = 7   
7
   foo() -- a inside fo is 5
Copied!
​For loop does not export anything from it:
1
func foo():
2
  x = 5
3
  for y <- ys:
4
    -- Can use what was defined above
5
    z <- bar(x)
6
​
7
  -- z is not defined in scope  
8
  z = 7
Copied!
​Parallel branches have no access to each other's data:
1
-- This will deadlock, as foo branch of execution will
2
-- never send x to a parallel bar branch
3
x <- foo()
4
par y <- bar(x)
5
​
6
-- After par is executed, all the can be used
7
baz(x, y)
Copied!
Recovery branches in conditional flow have no access to the main branch as the main branch exports values, whereas the recovery branch does not:
1
try:
2
  x <- foo()
3
otherwise:
4
  -- this is not possible – will fail
5
  bar(x)  
6
  y <- baz()
7
​
8
-- y is not available below  
9
willFail(y)
Copied!
Streams as literals
Stream is a special data structure that allows many writes. It has a dedicated article.
To use a stream, you need to initiate it at first:
1
-- Initiate an (empty) appendable collection of strings
2
resp: *string
3
​
4
-- Write strings to resp in parallel
5
resp <- foo()
6
par resp <- bar()
7
​
8
for x <- xs:
9
  -- Write to a stream that's defined above
10
  resp <- baz()
11
​
12
try:
13
  resp <- baz()
14
otherwise:
15
  on "other peer":
16
    resp <- baz()
17
​
18
-- Now resp can be used in place of arrays and optional values
19
-- assume fn: []string -> ()
20
fn(resp) 
21
​
22
-- Can call fn with empty stream: you can use it
23
-- to construct empty values of any collection types
24
nilString: *string
25
fn(nilString)
Copied!
One of the most frequently used patterns for streams is Conditional return.
You can create a stream with Collection creation operators.
Types
Topology
Last modified 13d ago
Copy link
Contents