ROOT /

VDSL.md

History

573 lines | UTF-8 | 14 KB

Blame

VDSL Language Syntax

VDSL's syntax is designed to be familiar to Go developers while being a bit simpler and more streamlined.

You can test the VDSL code in CVE PoC IDE.

Values and Value Types

In VDSL, everything is a value, and, all values are associated with a type.

11 + 22               // int values
"aa" + `bb`           // string values
-1.22 + 3e9          // float values
true || false         // bool values
'七' > '7'              // char values
[33, false, "xx"]     // array value
{a: true, b: "oo"}  // map value
func() { /*...*/ }    // function value

Here's a list of all available value types in VDSL.

VDSL Type	Description	Equivalent Type in Go
int	signed 64-bit integer value	`int64`
float	64-bit floating point value	`float64`
bool	boolean value	`bool`
char	unicode character	`rune`
string	unicode string	`string`
bytes	byte array	`[]byte`
error	error value	-
time	time value	`time.Time`
array	value array (mutable)	`[]any`
const array	const array	-
map	value map with string keys (mutable)	`map[string]any`
const map	const map	-
nil	nil value	-
function	function value	-
user-defined	value of user-defined types	-

Error Values

In VDSL, an error can be represented using "error" typed values. An error value is created using error expression, and, it must have an underlying value. The underlying value of an error value can be access using .value selector.

err1 := error("oops")    // error with string value
err2 := error(1+2+3)     // error with int value
if is_error(err1) {      // 'is_error' builtin function
  err_val := err1.value  // get underlying value
}

Const Values

In VDSL, basically all values (except for array and map) are const.

s := "12345"
s[1] = 'b'    // illegal: String is const

a := [1, 2, 3]
a[1] = "two"  // ok: a is now [1, "two", 3]

An array or map value can be made const using const expression.

b := const([1, 2, 3])
b[1] = "foo"  // illegal: 'b' references to an const array.

Note that re-assigning a new value to the variable has nothing to do with the value immutability.

s := "abc"
s = "foo"                  // ok
a := const([1, 2, 3])
a = false                  // ok

Note that, if you copy (using copy builtin function) an const value, it will return a "mutable" copy. Also, immutability is not applied to the individual elements of the array or map value, unless they are explicitly made const.

a := const({b: 4, c: [1, 2, 3]})
a.b = 5        // illegal
a.c[1] = 5     // ok: because 'a.c' is not const

a = const({b: 4, c: const([1, 2, 3])})
a.c[1] = 5     // illegal

Nil Values

In VDSL, an "nil" value can be used to represent an unexpected or non-existing value:

A function that does not return a value explicitly considered to return nil value.
Indexer or selector on composite value types may return nil if the key or index does not exist.
Type conversion builtin functions without a default value will return nil if conversion fails.

a := func() { b := 4 }()    // a == nil
b := [1, 2, 3][10]          // b == nil
c := {a: "foo"}["b"]        // c == nil
d := int("foo")             // d == nil

Array Values

In VDSL, array is an ordered list of values of any types. Elements of an array can be accessed using indexer [].

[1, 2, 3][0]       // == 1
[1, 2, 3][2]       // == 3
[1, 2, 3][3]       // == nil

["foo", "bar", [1, 2, 3]]   // ok: array with an array element

Map Values

In VDSL, map is a set of key-value pairs where key is string and the value is of any value types. Value of a map can be accessed using indexer [] or selector '.' operators.

m := { a: 1, b: false, c: "foo" }
m["b"]                                // == false
m.c                                   // == "foo"
m.x                                   // == nil

{a: [1,2,3], b: {c: "foo", d: "bar"}} // ok: map with an array element and a map element

Function Values

In VDSL, function is a callable value with a number of function arguments and a return value. Just like any other values, functions can be passed into or returned from another function.

my_func := func(arg1, arg2) {
  return arg1 + arg2
}

adder := func(base) {
  return func(x) { return base + x }  // capturing 'base'
}
add5 := adder(5)
nine := add5(4)    // == 9

Unlike Go, VDSL does not have declarations. So the following code is illegal:

func my_func(arg1, arg2) {  // illegal
  return arg1 + arg2
}

VDSL also supports variadic functions/closures:

variadic := func (a, b, ...c) {
  return [a, b, c]
}
variadic(1, 2, 3, 4) // [1, 2, [3, 4]]

variadicClosure := func(a) {
  return func(b, ...c) {
    return [a, b, c]
  }
}
variadicClosure(1)(2, 3, 4) // [1, 2, [3, 4]]

Only the last parameter can be variadic. The following code is also illegal:

// illegal, because a is variadic and is not the last parameter
illegal := func(a..., b) { /*... */ }

When calling a function, the number of passing arguments must match that of function definition.

f := func(a, b) {}
f(1, 2, 3) // Runtime Error: wrong number of arguments: want=2, got=3

Like Go, you can use ellipsis ... to pass array-type value as its last parameter:

f1 := func(a, b, c) { return a + b + c }
f1([1, 2, 3]...)    // => 6
f1(1, [2, 3]...)    // => 6
f1(1, 2, [3]...)    // => 6
f1([1, 2]...)       // Runtime Error: wrong number of arguments: want=3, got=2

f2 := func(a, ...b) {}
f2(1)               // valid; a = 1, b = []
f2(1, 2)            // valid; a = 1, b = [2]
f2(1, 2, 3)         // valid; a = 1, b = [2, 3]
f2([1, 2, 3]...)    // valid; a = 1, b = [2, 3]

Variables and Scopes

A value can be assigned to a variable using assignment operator := and =.

:= operator defines a new variable in the scope and assigns a value.
= operator assigns a new value to an existing variable in the scope.

Variables are defined either in global scope (defined outside function) or in local scope (defined inside function).

a := "foo"      // define 'a' in global scope

func() {        // function scope A
  b := 52       // define 'b' in function scope A

  func() {      // function scope B
    c := 19.84  // define 'c' in function scope B

    a = "bee"   // ok: assign new value to 'a' from global scope
    b = 20      // ok: assign new value to 'b' from function scope A

    b := true   // ok: define new 'b' in function scope B
                //     (shadowing 'b' from function scope A)
  }

  a = "bar"     // ok: assigne new value to 'a' from global scope
  b = 10        // ok: assigne new value to 'b'
  a := -100     // ok: define new 'a' in function scope A
                //     (shadowing 'a' from global scope)

  c = -9.1      // illegal: 'c' is not defined
  b := [1, 2]   // illegal: 'b' is already defined in the same scope
}

b = 25          // illegal: 'b' is not defined
a := {d: 2}     // illegal: 'a' is already defined in the same scope

Unlike Go, a variable can be assigned a value of different types.

a := 123        // assigned    'int'
a = "123"       // re-assigned 'string'
a = [1, 2, 3]   // re-assigned 'array'

Type Conversions

Although the type is not directly specified in VDSL, one can use type conversion builtin functions to convert between value types.

s1 := string(1984)    // "1984"
i2 := int("-999")     // -999
f3 := float(-51)      // -51.0
b4 := bool(1)         // true
c5 := char("X")       // 'X'

See Operators for more details on type coercions.

Operators

Unary Operators

Operator	Usage	Types
`+`	same as `0 + x`	int, float
`-`	same as `0 - x`	int, float
`!`	logical NOT	all types*
`^`	bitwise complement	int

In VDSL, all values can be either truthy or falsy.

Binary Operators

Operator	Usage	Types
`==`	equal	all types
`!=`	not equal	all types
`&&`	logical AND	all types
`\\|\\|`	logical OR	all types
`+`	add/concat	int, float, string, char, time, array
`-`	subtract	int, float, char, time
`*`	multiply	int, float
`/`	divide	int, float
`&`	bitwise AND	int
`\\|`	bitwise OR	int
`^`	bitwise XOR	int
`&^`	bitclear (AND NOT)	int
`<<`	shift left	int
`>>`	shift right	int
`<`	less than	int, float, char, time, string
`<=`	less than or equal to	int, float, char, time, string
`>`	greater than	int, float, char, time, string
`>=`	greater than or equal to	int, float, char, time, string

See Operators for more details.

Ternary Operators

VDSL has a ternary conditional operator (condition expression) ? (true expression) : (false expression).

a := true ? 1 : -1    // a == 1

min := func(a, b) {
  return a < b ? a : b
}
b := min(5, 10)      // b == 5

Assignment and Increment Operators

Operator	Usage
`+=`	`(lhs) = (lhs) + (rhs)`
`-=`	`(lhs) = (lhs) - (rhs)`
`*=`	`(lhs) = (lhs) * (rhs)`
`/=`	`(lhs) = (lhs) / (rhs)`
`%=`	`(lhs) = (lhs) % (rhs)`
`&=`	`(lhs) = (lhs) & (rhs)`
`\\|=`	`(lhs) = (lhs) \\| (rhs)`
`&^=`	`(lhs) = (lhs) &^ (rhs)`
`^=`	`(lhs) = (lhs) ^ (rhs)`
`<<=`	`(lhs) = (lhs) << (rhs)`
`>>=`	`(lhs) = (lhs) >> (rhs)`
`++`	`(lhs) = (lhs) + 1`
`--`	`(lhs) = (lhs) - 1`

Operator Precedences

Unary operators have the highest precedence, and, ternary operator has the lowest precedence. There are five precedence levels for binary operators. Multiplication operators bind strongest, followed by addition operators, comparison operators, && (logical AND), and finally || (logical OR):

Precedence	Operator
5	`*` `/` `%` `<<` `>>` `&` `&^`
4	`+` `-` `\\|` `^`
3	`==` `!=` `<` `<=` `>` `>=`
2	`&&`
1	`\\|\\|`

Like Go, ++ and -- operators form statements, not expressions, they fall outside the operator hierarchy.

Selector and Indexer

One can use selector (.) and indexer ([]) operators to read or write elements of composite types (array, map, string, bytes).

["one", "two", "three"][1]  // == "two"

m := {
  a: 1,
  b: [2, 3, 4],
  c: func() { return 10 }
}
m.a              // == 1
m["b"][1]        // == 3
m.c()            // == 10
m.x = 5          // add 'x' to map 'm'
m["b"][5]        // == nil
m["b"][5].d      // == nil
m.b[5] = 0       // == nil
m.x.y.z          // == nil

Like Go, one can use slice operator [:] for sequence value types such as array, string, bytes.

a := [1, 2, 3, 4, 5][1:3]    // == [2, 3]
b := [1, 2, 3, 4, 5][3:]     // == [4, 5]
c := [1, 2, 3, 4, 5][:3]     // == [1, 2, 3]
d := "hello world"[2:10]     // == "llo worl"
c := [1, 2, 3, 4, 5][-1:10]  // == [1, 2, 3, 4, 5]

Note: Keywords cannot be used as selectors.

a := {in: true} // Parse Error: expected map key, found 'in'
a.func = ""     // Parse Error: expected selector, found 'func'

Use double quotes and indexer to use keywords with maps.

a := {"in": true}
a["func"] = ""

Statements

If Statement

"If" statement is very similar to Go.

if a < 0 {
  // execute if 'a' is negative
} else if a == 0 {
  // execute if 'a' is zero
} else {
  // execute if 'a' is positive
}

Like Go, the condition expression may be preceded by a simple statement, which executes before the expression is evaluated.

if a := foo(); a < 0 {
  // execute if 'a' is negative
}

For Statement

"For" statement is very similar to Go.

// for (init); (condition); (post) {}
for a:=0; a<10; a++ {
  // ...
}

// for (condition) {}
for a < 10 {
  // ...
}

// for {}
for {
  // ...
}

For-In Statement

"For-In" statement is new in VDSL. It's similar to Go's for range statement. "For-In" statement can iterate any iterable value types (array, map, bytes, string, nil).

for v in [1, 2, 3] {          // array: element
  // 'v' is value
}
for i, v in [1, 2, 3] {       // array: index and element
  // 'i' is index
  // 'v' is value
}
for k, v in {k1: 1, k2: 2} {  // map: key and value
  // 'k' is key
  // 'v' is value
}

Modules

Module is the basic compilation unit in VDSL. A module can import another module using import expression.

Main module:

sum := import("./sum")  // load module from a local file
fmt.print(sum(10))      // module function

Another module in sum.dsl file:

base := 5

export func(x) {
  return x + base
}

By default, import solves the missing extension name of a module file as ".dsl"[^note]. Thus, sum := import("./sum") is equivalent to sum := import("./sum.dsl").

[^note]: If using VDSL as a library in Go, the file extension name ".dsl" can be customized. In that case, use the SetImportFileExt function of the Compiler type. See the Go reference for details.

In VDSL, modules are very similar to functions.

import expression loads the module code and execute it like a function.
Module should return a value using export statement.
- Module can return export a value of any types: int, map, function, etc.
- export in a module is like return in a function: it stops execution and return a value to the importing code.
- export-ed values are always const.
- If the module does not have any export statement, import expression simply returns nil. (Just like the function that has no return.)
- Note that export statement is completely ignored and not evaluated if the code is executed as a main module.

Also, you can use import expression to load the Standard Library as well.

math := import("math")
a := math.abs(-19.84)  // == 19.84

Comments

Like Go, VDSL supports line comments (//...) and block comments (/* ... */).

/*
  multi-line block comments
*/

a := 5    // line comments

Differences from Go

Unlike Go, VDSL does not have the following:

Declarations
Imaginary values
Structs
Pointers
Channels
Goroutines
Tuple assignment
Variable parameters
Switch statement
Goto statement
Defer statement
Panic
Type assertion