v / doc /
# V Documentation

## Introduction

V is a statically typed compiled programming language designed for building maintainable software.

It's similar to Go and its design has also been influenced by Oberon, Rust, Swift,
Kotlin, and Python.

V is a very simple language. Going through this documentation will take you about an hour,
and by the end of it you will have pretty much learned the entire language.

The language promotes writing simple and clear code with minimal abstraction.

Despite being simple, V gives the developer a lot of power.
Anything you can do in other languages, you can do in V.

## Install from source
The major way to get the latest and greatest V, is to __install it from source__.
It is __easy__, and it usually takes __only a few seconds__.

### Linux, macOS, FreeBSD, etc:
You need `git`, and a C compiler like `tcc`, `gcc` or `clang`, and `make`:
```bash
git clone https://github.com/vlang/v
cd v
make
```

### Windows:
You need `git`, and a C compiler like `tcc`, `gcc`, `clang` or `msvc`:
```bash
git clone https://github.com/vlang/v
cd v
make.bat -tcc
```
NB: You can also pass one of `-gcc`, `-msvc`, `-clang` to `make.bat` instead,
if you do prefer to use a different C compiler, but -tcc is small, fast, and
easy to install (V will download a prebuilt binary automatically).

It is recommended to add this folder to the PATH of your environment variables.
This can be done with the command `v.exe symlink`.

### Android
Running V graphical apps on Android is also possible via [vab](https://github.com/vlang/vab).

V Android dependencies: **V**, **Java JDK** >= 8, Android **SDK + NDK**.

  1. Install dependencies (see [vab](https://github.com/vlang/vab))
  2. Connect your Android device
  3. Run:
  ```bash
  git clone https://github.com/vlang/vab && cd vab && v vab.v
  ./vab --device auto run /path/to/v/examples/sokol/particles
  ```
For more details and troubleshooting, please visit the [vab GitHub repository](https://github.com/vlang/vab).

## Table of Contents

* [Hello world](#hello-world) * [Running a project folder](#running-a-project-folder-with-several-files) * [Comments](#comments) * [Functions](#functions) * [Returning multiple values](#returning-multiple-values) * [Symbol visibility](#symbol-visibility) * [Variables](#variables) * [Types](#types) * [Strings](#strings) * [Numbers](#numbers) * [Arrays](#arrays) * [Fixed size arrays](#fixed-size-arrays) * [Maps](#maps) * [Module imports](#module-imports) * [Statements & expressions](#statements--expressions) * [If](#if) * [In operator](#in-operator) * [For loop](#for-loop) * [Match](#match) * [Defer](#defer) * [Structs](#structs) * [Embedded structs](#embedded-structs) * [Default field values](#default-field-values) * [Short struct literal syntax](#short-struct-initialization-syntax) * [Access modifiers](#access-modifiers) * [Methods](#methods) * [Unions](#unions) * [Functions 2](#functions-2) * [Pure functions by default](#pure-functions-by-default) * [Mutable arguments](#mutable-arguments) * [Variable number of arguments](#variable-number-of-arguments) * [Anonymous & high order functions](#anonymous--high-order-functions) * [References](#references) * [Constants](#constants) * [Builtin functions](#builtin-functions) * [Printing custom types](#printing-custom-types) * [Modules](#modules) * [Module/package management](#modulepackage-management) * [Types 2](#types-2) * [Interfaces](#interfaces) * [Enums](#enums) * [Sum types](#sum-types) * [Type aliases](#type-aliases) * [Option/Result types & error handling](#optionresult-types-and-error-handling) * [Generics](#generics) * [Concurrency](#concurrency) * [Spawning Concurrent Tasks](#spawning-concurrent-tasks) * [Channels](#channels) * [Shared Objects](#shared-objects) * [Decoding JSON](#decoding-json) * [Testing](#testing) * [Memory management](#memory-management) * [ORM](#orm) * [Writing documentation](#writing-documentation) * [Tools](#tools) * [v fmt](#v-fmt) * [Profiling](#profiling) * [Advanced Topics](#advanced-topics) * [Dumping expressions at runtime](#dumping-expressions-at-runtime) * [Memory-unsafe code](#memory-unsafe-code) * [Structs with reference fields](#structs-with-reference-fields) * [sizeof and __offsetof](#sizeof-and-__offsetof) * [Calling C from V](#calling-c-from-v) * [Debugging generated C code](#debugging-generated-c-code) * [Conditional compilation](#conditional-compilation) * [Compile time pseudo variables](#compile-time-pseudo-variables) * [Compile-time reflection](#compile-time-reflection) * [Limited operator overloading](#limited-operator-overloading) * [Inline assembly](#inline-assembly) * [Translating C to V](#translating-c-to-v) * [Hot code reloading](#hot-code-reloading) * [Cross compilation](#cross-compilation) * [Cross-platform shell scripts in V](#cross-platform-shell-scripts-in-v) * [Attributes](#attributes) * [Goto](#goto) * [Appendices](#appendices) * [Keywords](#appendix-i-keywords) * [Operators](#appendix-ii-operators)
## Hello World ```v fn main() { println('hello world') } ``` Save this snippet into a file named `hello.v`. Now do: `v run hello.v`. > That is assuming you have symlinked your V with `v symlink`, as described [here](https://github.com/vlang/v/blob/master/README.md#symlinking). If you haven't yet, you have to type the path to V manually. Congratulations - you just wrote and executed your first V program! You can compile a program without execution with `v hello.v`. See `v help` for all supported commands. From the example above, you can see that functions are declared with the `fn` keyword. The return type is specified after the function name. In this case `main` doesn't return anything, so there is no return type. As in many other languages (such as C, Go, and Rust), `main` is the entry point of your program. `println` is one of the few built-in functions. It prints the value passed to it to standard output. `fn main()` declaration can be skipped in one file programs. This is useful when writing small programs, "scripts", or just learning the language. For brevity, `fn main()` will be skipped in this tutorial. This means that a "hello world" program in V is as simple as ```v println('hello world') ``` ## Running a project folder with several files Suppose you have a folder with several .v files in it, where one of them contains your `main()` function, and the other files have other helper functions. They may be organized by topic, but still *not yet* structured enough to be their own separate reusable modules, and you want to compile them all into one program. In other languages, you would have to use includes or a build system to enumerate all files, compile them separately to object files, then link them into one final executable. In V however, you can compile and run the whole folder of .v files together, using just `v run .`. Passing parameters also works, so you can do: `v run . --yourparam some_other_stuff` The above will first compile your files into a single program (named after your folder/project), and then it will execute the program with `--yourparam some_other_stuff` passed to it as CLI parameters. Your program can then use the CLI parameters like this: ```v import os println(os.args) ``` NB: after a successful run, V will delete the generated executable. If you want to keep it, use `v -keepc run .` instead, or just compile manually with `v .` . NB: any V compiler flags should be passed *before* the `run` command. Everything after the source file/folder, will be passed to the program as is - it will not be processed by V. ## Comments ```v // This is a single line comment. /* This is a multiline comment. /* It can be nested. */ */ ``` ## Functions ```v fn main() { println(add(77, 33)) println(sub(100, 50)) } fn add(x int, y int) int { return x + y } fn sub(x int, y int) int { return x - y } ``` Again, the type comes after the argument's name. Just like in Go and C, functions cannot be overloaded. This simplifies the code and improves maintainability and readability. Functions can be used before their declaration: `add` and `sub` are declared after `main`, but can still be called from `main`. This is true for all declarations in V and eliminates the need for header files or thinking about the order of files and declarations. ### Returning multiple values ```v fn foo() (int, int) { return 2, 3 } a, b := foo() println(a) // 2 println(b) // 3 c, _ := foo() // ignore values using `_` ``` ## Symbol visibility ```v pub fn public_function() { } fn private_function() { } ``` Functions are private (not exported) by default. To allow other modules to use them, prepend `pub`. The same applies to constants and types. Note: `pub` can only be used from a named module. For information about creating a module, see [Modules](#modules). ## Variables ```v name := 'Bob' age := 20 large_number := i64(9999999999) println(name) println(age) println(large_number) ``` Variables are declared and initialized with `:=`. This is the only way to declare variables in V. This means that variables always have an initial value. The variable's type is inferred from the value on the right hand side. To choose a different type, use type conversion: the expression `T(v)` converts the value `v` to the type `T`. Unlike most other languages, V only allows defining variables in functions. Global (module level) variables are not allowed. There's no global state in V (see [Pure functions by default](#pure-functions-by-default) for details). For consistency across different code bases, all variable and function names must use the `snake_case` style, as opposed to type names, which must use `PascalCase`. ### Mutable variables ```v mut age := 20 println(age) age = 21 println(age) ``` To change the value of the variable use `=`. In V, variables are immutable by default. To be able to change the value of the variable, you have to declare it with `mut`. Try compiling the program above after removing `mut` from the first line. ### Initialization vs assignment Note the (important) difference between `:=` and `=`. `:=` is used for declaring and initializing, `=` is used for assigning. ```v failcompile fn main() { age = 21 } ``` This code will not compile, because the variable `age` is not declared. All variables need to be declared in V. ```v fn main() { age := 21 } ``` The values of multiple variables can be changed in one line. In this way, their values can be swapped without an intermediary variable. ```v mut a := 0 mut b := 1 println('$a, $b') // 0, 1 a, b = b, a println('$a, $b') // 1, 0 ``` ### Declaration errors In development mode the compiler will warn you that you haven't used the variable (you'll get an "unused variable" warning). In production mode (enabled by passing the `-prod` flag to v – `v -prod foo.v`) it will not compile at all (like in Go). ```v failcompile nofmt fn main() { a := 10 if true { a := 20 // error: redefinition of `a` } // warning: unused variable `a` } ``` Unlike most languages, variable shadowing is not allowed. Declaring a variable with a name that is already used in a parent scope will cause a compilation error. You can shadow imported modules though, as it is very useful in some situations: ```v ignore import ui import gg fn draw(ctx &gg.Context) { gg := ctx.parent.get_ui().gg gg.draw_rect(10, 10, 100, 50) } ``` ## Types ### Primitive types ```v ignore bool string i8 i16 int i64 i128 (soon) byte u16 u32 u64 u128 (soon) rune // represents a Unicode code point f32 f64 voidptr, size_t // these are mostly used for C interoperability any // similar to C's void* and Go's interface{} ``` Please note that unlike C and Go, `int` is always a 32 bit integer. There is an exception to the rule that all operators in V must have values of the same type on both sides. A small primitive type on one side can be automatically promoted if it fits completely into the data range of the type on the other side. These are the allowed possibilities: ```v ignore i8 → i16 → int → i64 ↘ ↘ f32 → f64 ↗ ↗ byte → u16 → u32 → u64 ⬎ ↘ ↘ ↘ ptr i8 → i16 → int → i64 ⬏ ``` An `int` value for example can be automatically promoted to `f64` or `i64` but not to `u32`. (`u32` would mean loss of the sign for negative values). Promotion from `int` to `f32`, however, is currently done automatically (but can lead to precision loss for large values). Literals like `123` or `4.56` are treated in a special way. They do not lead to type promotions, however they default to `int` and `f64` respectively, when their type has to be decided: ```v nofmt u := u16(12) v := 13 + u // v is of type `u16` - no promotion x := f32(45.6) y := x + 3.14 // x is of type `f32` - no promotion a := 75 // a is of type `int` - default for int literal b := 14.7 // b is of type `f64` - default for float literal c := u + a // c is of type `int` - automatic promotion of `u`'s value d := b + x // d is of type `f64` - automatic promotion of `x`'s value ``` ### Strings ```v name := 'Bob' println(name.len) println(name[0]) // indexing gives a byte B println(name[1..3]) // slicing gives a string 'ob' windows_newline := '\r\n' // escape special characters like in C assert windows_newline.len == 2 ``` In V, a string is a read-only array of bytes. String data is encoded using UTF-8. String values are immutable. You cannot mutate elements: ```v failcompile mut s := 'hello 🌎' s[0] = `H` // not allowed ``` > error: cannot assign to `s[i]` since V strings are immutable Note that indexing a string will produce a `byte`, not a `rune`. Indexes correspond to bytes in the string, not Unicode code points. Character literals have type `rune`. To denote them, use ` ```v rocket := `🚀` assert 'aloha!'[0] == `a` ``` Both single and double quotes can be used to denote strings. For consistency, `vfmt` converts double quotes to single quotes unless the string contains a single quote character. For raw strings, prepend `r`. Raw strings are not escaped: ```v s := r'hello\nworld' println(s) // "hello\nworld" ``` Strings can be easily converted to integers: ```v s := '42' n := s.int() // 42 ``` ### String interpolation Basic interpolation syntax is pretty simple - use `$` before a variable name. The variable will be converted to a string and embedded into the literal: ```v name := 'Bob' println('Hello, $name!') // Hello, Bob! ``` It also works with fields: `'age = $user.age'`. If you need more complex expressions, use `${}`: `'can register = ${user.age > 13}'`. Format specifiers similar to those in C's `printf()` are also supported. `f`, `g`, `x`, etc. are optional and specify the output format. The compiler takes care of the storage size, so there is no `hd` or `llu`. ```v x := 123.4567 println('x = ${x:4.2f}') println('[${x:10}]') // pad with spaces on the left => [ 123.457] println('[${int(x):-10}]') // pad with spaces on the right => [123 ] println('[${int(x):010}]') // pad with zeros on the left => [0000000123] ``` ### String operators ```v name := 'Bob' bobby := name + 'by' // + is used to concatenate strings println(bobby) // "Bobby" mut s := 'hello ' s += 'world' // `+=` is used to append to a string println(s) // "hello world" ``` All operators in V must have values of the same type on both sides. You cannot concatenate an integer to a string: ```v failcompile age := 10 println('age = ' + age) // not allowed ``` > error: infix expr: cannot use `int` (right expression) as `string` We have to either convert `age` to a `string`: ```v age := 11 println('age = ' + age.str()) ``` or use string interpolation (preferred): ```v age := 12 println('age = $age') ``` ### Numbers ```v a := 123 ``` This will assign the value of 123 to `a`. By default `a` will have the type `int`. You can also use hexadecimal, binary or octal notation for integer literals: ```v a := 0x7B b := 0b01111011 c := 0o173 ``` All of these will be assigned the same value, 123. They will all have type `int`, no matter what notation you used. V also supports writing numbers with `_` as separator: ```v num := 1_000_000 // same as 1000000 three := 0b0_11 // same as 0b11 float_num := 3_122.55 // same as 3122.55 hexa := 0xF_F // same as 255 oct := 0o17_3 // same as 0o173 ``` If you want a different type of integer, you can use casting: ```v a := i64(123) b := byte(42) c := i16(12345) ``` Assigning floating point numbers works the same way: ```v f := 1.0 f1 := f64(3.14) f2 := f32(3.14) ``` If you do not specify the type explicitly, by default float literals will have the type of `f64`. ### Arrays ```v mut nums := [1, 2, 3] println(nums) // "[1, 2, 3]" println(nums[1]) // "2" nums[1] = 5 println(nums) // "[1, 5, 3]" println(nums.len) // "3" nums = [] // The array is now empty println(nums.len) // "0" // Declare an empty array: users := []int{} ``` The type of an array is determined by the first element: * `[1, 2, 3]` is an array of ints (`[]int`). * `['a', 'b']` is an array of strings (`[]string`). The user can explicitly specify the type for the first element: `[byte(16), 32, 64, 128]`. V arrays are homogeneous (all elements must have the same type). This means that code like `[1, 'a']` will not compile. The `.len` field returns the length of the array. Note that it's a read-only field, and it can't be modified by the user. Exported fields are read-only by default in V. See [Access modifiers](#access-modifiers). #### Array operations ```v mut nums := [1, 2, 3] nums << 4 println(nums) // "[1, 2, 3, 4]" // append array nums << [5, 6, 7] println(nums) // "[1, 2, 3, 4, 5, 6, 7]" mut names := ['John'] names << 'Peter' names << 'Sam' // names << 10 <-- This will not compile. `names` is an array of strings. println(names.len) // "3" println('Alex' in names) // "false" ``` `<<` is an operator that appends a value to the end of the array. It can also append an entire array. `val in array` returns true if the array contains `val`. See [`in` operator](#in-operator). #### Initializing array properties During initialization you can specify the capacity of the array (`cap`), its initial length (`len`), and the default element (`init`): ```v arr := []int{len: 5, init: -1} // `[-1, -1, -1, -1, -1]` ``` Setting the capacity improves performance of insertions, as it reduces the number of reallocations needed: ```v mut numbers := []int{cap: 1000} println(numbers.len) // 0 // Now appending elements won't reallocate for i in 0 .. 1000 { numbers << i } ``` Note: The above code uses a [range `for`](#range-for) statement. #### Array methods All arrays can be easily printed with `println(arr)` and converted to a string with `s := arr.str()`. Copying the data from the array is done with `.clone()`: ```v nums := [1, 2, 3] nums_copy := nums.clone() ``` Arrays can be efficiently filtered and mapped with the `.filter()` and `.map()` methods: ```v nums := [1, 2, 3, 4, 5, 6] even := nums.filter(it % 2 == 0) println(even) // [2, 4, 6] // filter can accept anonymous functions even_fn := nums.filter(fn (x int) bool { return x % 2 == 0 }) println(even_fn) words := ['hello', 'world'] upper := words.map(it.to_upper()) println(upper) // ['HELLO', 'WORLD'] // map can also accept anonymous functions upper_fn := words.map(fn (w string) string { return w.to_upper() }) println(upper_fn) // ['HELLO', 'WORLD'] ``` `it` is a builtin variable which refers to element currently being processed in filter/map methods. Additionally, `.any()` and `.all()` can be used to conveniently test for elements that satisfy a condition. ```v nums := [1, 2, 3] println(nums.any(it == 2)) // true println(nums.all(it >= 2)) // false ``` #### Multidimensional Arrays Arrays can have more than one dimension. 2d array example: ```v mut a := [][]int{len: 2, init: []int{len: 3}} a[0][1] = 2 println(a) // [[0, 2, 0], [0, 0, 0]] ``` 3d array example: ```v mut a := [][][]int{len: 2, init: [][]int{len: 3, init: []int{len: 2}}} a[0][1][1] = 2 println(a) // [[[0, 0], [0, 2], [0, 0]], [[0, 0], [0, 0], [0, 0]]] ``` #### Sorting arrays Sorting arrays of all kinds is very simple and intuitive. Special variables `a` and `b` are used when providing a custom sorting condition. ```v mut numbers := [1, 3, 2] numbers.sort() // 1, 2, 3 numbers.sort(a > b) // 3, 2, 1 ``` ```v struct User { age int name string } mut users := [User{21, 'Bob'}, User{20, 'Zarkon'}, User{25, 'Alice'}] users.sort(a.age < b.age) // sort by User.age int field users.sort(a.name > b.name) // reverse sort by User.name string field ``` #### Array Slices Slices are partial arrays. They represent every element between two indices separated by a .. operator. The right-side index must be greater than or equal to the left side index. If a right-side index is absent, it is assumed to be the array length. If a left-side index is absent, it is assumed to be 0. ```v nums := [0, 10, 20, 30, 40] println(nums[1..4]) // [10, 20, 30] println(nums[..4]) // [0, 10, 20, 30] println(nums[1..]) // [10, 20, 30, 40] ``` All array operations may be performed on slices. Slices can be pushed onto an array of the same type. ```v array_1 := [3, 5, 4, 7, 6] mut array_2 := [0, 1] array_2 << array_1[..3] println(array_2) // [0, 1, 3, 5, 4] ``` ### Fixed size arrays V also supports arrays with fixed size. Unlike ordinary arrays, their length is constant. You cannot append elements to them, nor shrink them. You can only modify their elements in place. However, access to the elements of fixed size arrays is more efficient, they need less memory than ordinary arrays, and unlike ordinary arrays, their data is on the stack, so you may want to use them as buffers if you do not want additional heap allocations. Most methods are defined to work on ordinary arrays, not on fixed size arrays. You can convert a fixed size array to an ordinary array with slicing: ```v mut fnums := [3]int{} // fnums is a fixed size array with 3 elements. fnums[0] = 1 fnums[1] = 10 fnums[2] = 100 println(fnums) // => [1, 10, 100] println(typeof(fnums).name) // => [3]int fnums2 := [1, 10, 100]! // short init syntax that does the same (the syntax will probably change) anums := fnums[0..fnums.len] println(anums) // => [1, 10, 100] println(typeof(anums).name) // => []int ``` Note that slicing will cause the data of the fixed size array to be copied to the newly created ordinary array. ### Maps ```v mut m := map[string]int{} // a map with `string` keys and `int` values m['one'] = 1 m['two'] = 2 println(m['one']) // "1" println(m['bad_key']) // "0" println('bad_key' in m) // Use `in` to detect whether such key exists m.delete('two') ``` Maps can have keys of type string, rune, integer, float or voidptr. The whole map can be initialized using this short syntax: ```v numbers := map{ 'one': 1 'two': 2 } println(numbers) ``` If a key is not found, a zero value is returned by default: ```v sm := map{ 'abc': 'xyz' } val := sm['bad_key'] println(val) // '' ``` ```v intm := map{ 1: 1234 2: 5678 } s := intm[3] println(s) // 0 ``` It's also possible to use an `or {}` block to handle missing keys: ```v mm := map[string]int{} val := mm['bad_key'] or { panic('key not found') } ``` The same optional check applies to arrays: ```v arr := [1, 2, 3] large_index := 999 val := arr[large_index] or { panic('out of bounds') } ``` ## Module imports For information about creating a module, see [Modules](#modules). Modules can be imported using the `import` keyword: ```v import os fn main() { // read text from stdin name := os.input('Enter your name: ') println('Hello, $name!') } ``` This program can use any public definitions from the `os` module, such as the `input` function. See the [standard library](https://modules.vlang.io/) documentation for a list of common modules and their public symbols. By default, you have to specify the module prefix every time you call an external function. This may seem verbose at first, but it makes code much more readable and easier to understand - it's always clear which function from which module is being called. This is especially useful in large code bases. Cyclic module imports are not allowed, like in Go. ### Selective imports You can also import specific functions and types from modules directly: ```v import os { input } fn main() { // read text from stdin name := input('Enter your name: ') println('Hello, $name!') } ``` Note: This is not allowed for constants - they must always be prefixed. You can import several specific symbols at once: ```v import os { input, user_os } name := input('Enter your name: ') println('Name: $name') os := user_os() println('Your OS is ${os}.') ``` ### Module import aliasing Any imported module name can be aliased using the `as` keyword: NOTE: this example will not compile unless you have created `mymod/sha256.v` ```v failcompile import crypto.sha256 import mymod.sha256 as mysha256 fn main() { v_hash := mysha256.sum('hi'.bytes()).hex() my_hash := mysha256.sum('hi'.bytes()).hex() assert my_hash == v_hash } ``` You cannot alias an imported function or type. However, you _can_ redeclare a type. ```v import time import math type MyTime = time.Time fn (mut t MyTime) century() int { return int(1.0 + math.trunc(f64(t.year) * 0.009999794661191)) } fn main() { mut my_time := MyTime{ year: 2020 month: 12 day: 25 } println(time.new_time(my_time).utc_string()) println('Century: $my_time.century()') } ``` ## Statements & expressions ### If ```v a := 10 b := 20 if a < b { println('$a < $b') } else if a > b { println('$a > $b') } else { println('$a == $b') } ``` `if` statements are pretty straightforward and similar to most other languages. Unlike other C-like languages, there are no parentheses surrounding the condition and the braces are always required. `if` can be used as an expression: ```v num := 777 s := if num % 2 == 0 { 'even' } else { 'odd' } println(s) // "odd" ``` #### Type checks and casts You can check the current type of a sum type using `is` and its negated form `!is`. You can do it either in an `if`: ```v struct Abc { val string } struct Xyz { foo string } type Alphabet = Abc | Xyz x := Alphabet(Abc{'test'}) // sum type if x is Abc { // x is automatically casted to Abc and can be used here println(x) } if x !is Abc { println('Not Abc') } ``` or using `match`: ```v oksyntax match x { Abc { // x is automatically casted to Abc and can be used here println(x) } Xyz { // x is automatically casted to Xyz and can be used here println(x) } } ``` This works also with struct fields: ```v struct MyStruct { x int } struct MyStruct2 { y string } type MySumType = MyStruct | MyStruct2 struct Abc { bar MySumType } x := Abc{ bar: MyStruct{123} // MyStruct will be converted to MySumType type automatically } if x.bar is MyStruct { // x.bar is automatically casted println(x.bar) } match x.bar { MyStruct { // x.bar is automatically casted println(x.bar) } else {} } ``` Mutable variables can change, and doing a cast would be unsafe. However, sometimes it's useful to type cast despite mutability. In such cases the developer must mark the expression with the `mut` keyword to tell the compiler that they know what they're doing. It works like this: ```v oksyntax mut x := MySumType(MyStruct{123}) if mut x is MyStruct { // x is casted to MyStruct even if it's mutable // without the mut keyword that wouldn't work println(x) } // same with match match mut x { MyStruct { // x is casted to MyStruct even it's mutable // without the mut keyword that wouldn't work println(x) } } ``` ### In operator `in` allows to check whether an array or a map contains an element. To do the opposite, use `!in`. ```v nums := [1, 2, 3] println(1 in nums) // true println(4 !in nums) // true m := map{ 'one': 1 'two': 2 } println('one' in m) // true println('three' !in m) // true ``` It's also useful for writing boolean expressions that are clearer and more compact: ```v enum Token { plus minus div mult } struct Parser { token Token } parser := Parser{} if parser.token == .plus || parser.token == .minus || parser.token == .div || parser.token == .mult { // ... } if parser.token in [.plus, .minus, .div, .mult] { // ... } ``` V optimizes such expressions, so both `if` statements above produce the same machine code and no arrays are created. ### For loop V has only one looping keyword: `for`, with several forms. #### `for`/`in` This is the most common form. You can use it with an array, map or numeric range. ##### Array `for` ```v numbers := [1, 2, 3, 4, 5] for num in numbers { println(num) } names := ['Sam', 'Peter'] for i, name in names { println('$i) $name') // Output: 0) Sam // 1) Peter } ``` The `for value in arr` form is used for going through elements of an array. If an index is required, an alternative form `for index, value in arr` can be used. Note, that the value is read-only. If you need to modify the array while looping, you need to declare the element as mutable: ```v mut numbers := [0, 1, 2] for mut num in numbers { num++ } println(numbers) // [1, 2, 3] ``` When an identifier is just a single underscore, it is ignored. ##### Map `for` ```v m := map{ 'one': 1 'two': 2 } for key, value in m { println('$key -> $value') // Output: one -> 1 // two -> 2 } ``` Either key or value can be ignored by using a single underscore as the identifier. ```v m := map{ 'one': 1 'two': 2 } // iterate over keys for key, _ in m { println(key) // Output: one // two } // iterate over values for _, value in m { println(value) // Output: 1 // 2 } ``` ##### Range `for` ```v // Prints '01234' for i in 0 .. 5 { print(i) } ``` `low..high` means an *exclusive* range, which represents all values from `low` up to *but not including* `high`. #### Condition `for` ```v mut sum := 0 mut i := 0 for i <= 100 { sum += i i++ } println(sum) // "5050" ``` This form of the loop is similar to `while` loops in other languages. The loop will stop iterating once the boolean condition evaluates to false. Again, there are no parentheses surrounding the condition, and the braces are always required. #### Bare `for` ```v mut num := 0 for { num += 2 if num >= 10 { break } } println(num) // "10" ``` The condition can be omitted, resulting in an infinite loop. #### C `for` ```v for i := 0; i < 10; i += 2 { // Don't print 6 if i == 6 { continue } println(i) } ``` Finally, there's the traditional C style `for` loop. It's safer than the `while` form because with the latter it's easy to forget to update the counter and get stuck in an infinite loop. Here `i` doesn't need to be declared with `mut` since it's always going to be mutable by definition. #### Labelled break & continue `break` and `continue` control the innermost `for` loop by default. You can also use `break` and `continue` followed by a label name to refer to an outer `for` loop: ```v outer: for i := 4; true; i++ { println(i) for { if i < 7 { continue outer } else { break outer } } } ``` The label must immediately precede the outer loop. The above code prints: ``` 4 5 6 7 ``` ### Match ```v os := 'windows' print('V is running on ') match os { 'darwin' { println('macOS.') } 'linux' { println('Linux.') } else { println(os) } } ``` A match statement is a shorter way to write a sequence of `if - else` statements. When a matching branch is found, the following statement block will be run. The else branch will be run when no other branches match. ```v number := 2 s := match number { 1 { 'one' } 2 { 'two' } else { 'many' } } ``` A match expression returns the value of the final expression from the matching branch. ```v enum Color { red blue green } fn is_red_or_blue(c Color) bool { return match c { .red, .blue { true } // comma can be used to test multiple values .green { false } } } ``` A match statement can also be used to branch on the variants of an `enum` by using the shorthand `.variant_here` syntax. An `else` branch is not allowed when all the branches are exhaustive. ```v c := `v` typ := match c { `0`...`9` { 'digit' } `A`...`Z` { 'uppercase' } `a`...`z` { 'lowercase' } else { 'other' } } println(typ) // 'lowercase' ``` You can also use ranges as `match` patterns. If the value falls within the range of a branch, that branch will be executed. Note that the ranges use `...` (three dots) rather than `..` (two dots). This is because the range is *inclusive* of the last element, rather than exclusive (as `..` ranges are). Using `..` in a match branch will throw an error. Note: `match` as an expression is not usable in `for` loop and `if` statements. ### Defer A defer statement defers the execution of a block of statements until the surrounding function returns. ```v import os fn read_log() { mut ok := false mut f := os.open('log.txt') or { panic(err.msg) } defer { f.close() } // ... if !ok { // defer statement will be called here, the file will be closed return } // ... // defer statement will be called here, the file will be closed } ``` If the function returns a value the `defer` block is executed *after* the return expression is evaluated: ```v import os enum State { normal write_log return_error } // write log file and return number of bytes written fn write_log(s State) ?int { mut f := os.create('log.txt') ? defer { f.close() } if s == .write_log { // `f.close()` will be called after `f.write()` has been // executed, but before `write_log()` finally returns the // number of bytes written to `main()` return f.writeln('This is a log file') } else if s == .return_error { // the file will be closed after the `error()` function // has returned - so the error message will still report // it as open return error('nothing written; file open: $f.is_opened') } // the file will be closed here, too return 0 } fn main() { n := write_log(.return_error) or { println('Error: $err') 0 } println('$n bytes written') } ``` ## Structs ```v struct Point { x int y int } mut p := Point{ x: 10 y: 20 } println(p.x) // Struct fields are accessed using a dot // Alternative literal syntax for structs with 3 fields or fewer p = Point{10, 20} assert p.x == 10 ``` ### Heap structs Structs are allocated on the stack. To allocate a struct on the heap and get a reference to it, use the `&` prefix: ```v struct Point { x int y int } p := &Point{10, 10} // References have the same syntax for accessing fields println(p.x) ``` The type of `p` is `&Point`. It's a [reference](#references) to `Point`. References are similar to Go pointers and C++ references. ### Embedded structs V doesn't allow subclassing, but it supports embedded structs: ```v struct Widget { mut: x int y int } struct Button { Widget title string } mut button := Button{ title: 'Click me' } button.x = 3 ``` Without embedding we'd have to name the `Widget` field and do: ```v oksyntax button.widget.x = 3 ``` ### Default field values ```v struct Foo { n int // n is 0 by default s string // s is '' by default a []int // a is `[]int{}` by default pos int = -1 // custom default value } ``` All struct fields are zeroed by default during the creation of the struct. Array and map fields are allocated. It's also possible to define custom default values. ### Required fields ```v struct Foo { n int [required] } ``` You can mark a struct field with the `[required]` attribute, to tell V that that field must be initialized when creating an instance of that struct. This example will not compile, since the field `n` isn't explicitly initialized: ```v failcompile _ = Foo{} ``` ### Short struct literal syntax ```v struct Point { x int y int } mut p := Point{ x: 10 y: 20 } // you can omit the struct name when it's already known p = { x: 30 y: 4 } assert p.y == 4 ``` Omitting the struct name also works for returning a struct literal or passing one as a function argument. #### Trailing struct literal arguments V doesn't have default function arguments or named arguments, for that trailing struct literal syntax can be used instead: ```v struct ButtonConfig { text string is_disabled bool width int = 70 height int = 20 } struct Button { text string width int height int } fn new_button(c ButtonConfig) &Button { return &Button{ width: c.width height: c.height text: c.text } } button := new_button(text: 'Click me', width: 100) // the height is unset, so it's the default value assert button.height == 20 ``` As you can see, both the struct name and braces can be omitted, instead of: ```v oksyntax nofmt new_button(ButtonConfig{text:'Click me', width:100}) ``` This only works for functions that take a struct for the last argument. ### Access modifiers Struct fields are private and immutable by default (making structs immutable as well). Their access modifiers can be changed with `pub` and `mut`. In total, there are 5 possible options: ```v struct Foo { a int // private immutable (default) mut: b int // private mutable c int // (you can list multiple fields with the same access modifier) pub: d int // public immutable (readonly) pub mut: e int // public, but mutable only in parent module __global: // (not recommended to use, that's why the 'global' keyword starts with __) f int // public and mutable both inside and outside parent module } ``` For example, here's the `string` type defined in the `builtin` module: ```v ignore struct string { str &byte pub: len int } ``` It's easy to see from this definition that `string` is an immutable type. The byte pointer with the string data is not accessible outside `builtin` at all. The `len` field is public, but immutable: ```v failcompile fn main() { str := 'hello' len := str.len // OK str.len++ // Compilation error } ``` This means that defining public readonly fields is very easy in V, no need in getters/setters or properties. ## Methods ```v struct User { age int } fn (u User) can_register() bool { return u.age > 16 } user := User{ age: 10 } println(user.can_register()) // "false" user2 := User{ age: 20 } println(user2.can_register()) // "true" ``` V doesn't have classes, but you can define methods on types. A method is a function with a special receiver argument. The receiver appears in its own argument list between the `fn` keyword and the method name. Methods must be in the same module as the receiver type. In this example, the `can_register` method has a receiver of type `User` named `u`. The convention is not to use receiver names like `self` or `this`, but a short, preferably one letter long, name. ## Unions Just like structs, unions support embedding. ```v struct Rgba32_Component { r byte g byte b byte a byte } union Rgba32 { Rgba32_Component value u32 } clr1 := Rgba32{ value: 0x008811FF } clr2 := Rgba32{ Rgba32_Component: { a: 128 } } sz := sizeof(Rgba32) unsafe { println('Size: ${sz}B,clr1.b: $clr1.b,clr2.b: $clr2.b') } ``` Output: `Size: 4B, clr1.b: 136, clr2.b: 0` Union member access must be performed in an `unsafe` block. Note that the embedded struct arguments are not necessarily stored in the order listed. ## Functions 2 ### Pure functions by default V functions are pure by default, meaning that their return values are a function of their arguments only, and their evaluation has no side effects (besides I/O). This is achieved by a lack of global variables and all function arguments being immutable by default, even when [references](#references) are passed. V is not a purely functional language however. There is a compiler flag to enable global variables (`-enable-globals`), but this is intended for low-level applications like kernels and drivers. ### Mutable arguments It is possible to modify function arguments by using the keyword `mut`: ```v struct User { name string mut: is_registered bool } fn (mut u User) register() { u.is_registered = true } mut user := User{} println(user.is_registered) // "false" user.register() println(user.is_registered) // "true" ``` In this example, the receiver (which is simply the first argument) is marked as mutable, so `register()` can change the user object. The same works with non-receiver arguments: ```v fn multiply_by_2(mut arr []int) { for i in 0 .. arr.len { arr[i] *= 2 } } mut nums := [1, 2, 3] multiply_by_2(mut nums) println(nums) // "[2, 4, 6]" ``` Note, that you have to add `mut` before `nums` when calling this function. This makes it clear that the function being called will modify the value. It is preferable to return values instead of modifying arguments. Modifying arguments should only be done in performance-critical parts of your application to reduce allocations and copying. For this reason V doesn't allow the modification of arguments with primitive types (e.g. integers). Only more complex types such as arrays and maps may be modified. Use `user.register()` or `user = register(user)` instead of `register(mut user)`. #### Struct update syntax V makes it easy to return a modified version of an object: ```v struct User { name string age int is_registered bool } fn register(u User) User { return { ...u is_registered: true } } mut user := User{ name: 'abc' age: 23 } user = register(user) println(user) ``` ### Variable number of arguments ```v fn sum(a ...int) int { mut total := 0 for x in a { total += x } return total } println(sum()) // 0 println(sum(1)) // 1 println(sum(2, 3)) // 5 // using array decomposition a := [2, 3, 4] println(sum(...a)) // <-- using prefix ... here. output: 9 b := [5, 6, 7] println(sum(...b)) // output: 18 ``` ### Anonymous & high order functions ```v fn sqr(n int) int { return n * n } fn cube(n int) int { return n * n * n } fn run(value int, op fn (int) int) int { return op(value) } fn main() { // Functions can be passed to other functions println(run(5, sqr)) // "25" // Anonymous functions can be declared inside other functions: double_fn := fn (n int) int { return n + n } println(run(5, double_fn)) // "10" // Functions can be passed around without assigning them to variables: res := run(5, fn (n int) int { return n + n }) println(res) // "10" // You can even have an array/map of functions: fns := [sqr, cube] println(fns[0](10)) // "100" fns_map := map{ 'sqr': sqr 'cube': cube } println(fns_map['cube'](2)) // "8" } ``` ## References ```v struct Foo {} fn (foo Foo) bar_method() { // ... } fn bar_function(foo Foo) { // ... } ``` If a function argument is immutable (like `foo` in the examples above) V can pass it either by value or by reference. The compiler will decide, and the developer doesn't need to think about it. You no longer need to remember whether you should pass the struct by value or by reference. You can ensure that the struct is always passed by reference by adding `&`: ```v struct Foo { abc int } fn (foo &Foo) bar() { println(foo.abc) } ``` `foo` is still immutable and can't be changed. For that, `(mut foo Foo)` must be used. In general, V's references are similar to Go pointers and C++ references. For example, a generic tree structure definition would look like this: ```v wip struct Node { val T left &Node right &Node } ``` ## Constants ```v const ( pi = 3.14 world = '世界' ) println(pi) println(world) ``` Constants are declared with `const`. They can only be defined at the module level (outside of functions). Constant values can never be changed. You can also declare a single constant separately: ```v const e = 2.71828 ``` V constants are more flexible than in most languages. You can assign more complex values: ```v struct Color { r int g int b int } fn rgb(r int, g int, b int) Color { return Color{ r: r g: g b: b } } const ( numbers = [1, 2, 3] red = Color{ r: 255 g: 0 b: 0 } // evaluate function call at compile-time* blue = rgb(0, 0, 255) ) println(numbers) println(red) println(blue) ``` \* WIP - for now function calls are evaluated at program start-up Global variables are not normally allowed, so this can be really useful. ### Required module prefix When naming constants, `snake_case` must be used. In order to distinguish consts from local variables, the full path to consts must be specified. For example, to access the PI const, full `math.pi` name must be used both outside the `math` module, and inside it. That restriction is relaxed only for the `main` module (the one containing your `fn main()`), where you can use the unqualified name of constants defined there, i.e. `numbers`, rather than `main.numbers`. vfmt takes care of this rule, so you can type `println(pi)` inside the `math` module, and vfmt will automatically update it to `println(math.pi)`. ## Builtin functions Some functions are builtin like `println`. Here is the complete list: ```v ignore fn print(s string) // print anything on sdtout fn println(s string) // print anything and a newline on sdtout fn eprint(s string) // same as print(), but use stderr fn eprintln(s string) // same as println(), but use stderr fn exit(code int) // terminate the program with a custom error code fn panic(s string) // print a message and backtraces on stderr, and terminate the program with error code 1 fn print_backtrace() // print backtraces on stderr ``` `println` is a simple yet powerful builtin function, that can print anything: strings, numbers, arrays, maps, structs. ```v struct User { name string age int } println(1) // "1" println('hi') // "hi" println([1, 2, 3]) // "[1, 2, 3]" println(User{ name: 'Bob', age: 20 }) // "User{name:'Bob', age:20}" ``` ## Printing custom types If you want to define a custom print value for your type, simply define a `.str() string` method: ```v struct Color { r int g int b int } pub fn (c Color) str() string { return '{$c.r, $c.g, $c.b}' } red := Color{ r: 255 g: 0 b: 0 } println(red) ``` ## Modules Every file in the root of a folder is part of the same module. Simple programs don't need to specify module name, in which case it defaults to 'main'. V is a very modular language. Creating reusable modules is encouraged and is quite easy to do. To create a new module, create a directory with your module's name containing .v files with code: ```shell cd ~/code/modules mkdir mymodule vim mymodule/myfile.v ``` ```v failcompile // myfile.v module mymodule // To export a function we have to use `pub` pub fn say_hi() { println('hello from mymodule!') } ``` You can now use `mymodule` in your code: ```v failcompile import mymodule fn main() { mymodule.say_hi() } ``` * Module names should be short, under 10 characters. * Module names must use `snake_case`. * Circular imports are not allowed. * You can have as many .v files in a module as you want. * You can create modules anywhere. * All modules are compiled statically into a single executable. ### `init` functions If you want a module to automatically call some setup/initialization code when it is imported, you can use a module `init` function: ```v fn init() { // your setup code here ... } ``` The `init` function cannot be public - it will be called automatically. This feature is particularly useful for initializing a C library. ### Module/package management Briefly: ```powershell v [module option] [param] ``` ###### module options: ``` install Install a module from VPM. remove Remove a module that was installed from VPM. search Search for a module from VPM. update Update an installed module from VPM. upgrade Upgrade all the outdated modules. list List all installed modules. outdated Show installed modules that need updates. ``` Read more: You can also install modules already created by someone else with [VPM](https://vpm.vlang.io/): ```powershell v install [module] ``` ###### Example: ```powershell v install ui ``` Removing a module with v: ```powershell v remove [module] ``` ###### Example: ```powershell v remove ui ``` Updating an installed module from [VPM](https://vpm.vlang.io/): ```powershell v update [module] ``` ###### Example: ```powershell v update ui ``` Or you can update all your modules: ```powershell v update ``` To see all the modules you have installed, you can use: ```powershell v list ``` ###### Example ```powershell > v list Installed modules: markdown ui ``` To see all the modules you have installed, you can use: outdated Show installed modules that need updates. ```powershell v outdated ``` ###### Example ```powershell > v outdated Modules are up to date. ``` You can also add your module to VPM by following the instructions on the website https://vpm.vlang.io/new ## Types 2 ### Interfaces ```v struct Dog { breed string } struct Cat { breed string } fn (d Dog) speak() string { return 'woof' } fn (c Cat) speak() string { return 'meow' } // unlike Go and like TypeScript, V's interfaces can define fields, not just methods. interface Speaker { breed string speak() string } dog := Dog{'Leonberger'} cat := Cat{'Siamese'} mut arr := []Speaker{} arr << dog arr << cat for item in arr { println('a $item.breed says: $item.speak()') } ``` A type implements an interface by implementing its methods and fields. There is no explicit declaration of intent, no "implements" keyword. #### Casting an interface We can test the underlying type of an interface using dynamic cast operators: ```v oksyntax interface Something {} fn announce(s Something) { if s is Dog { println('a $s.breed dog') // `s` is automatically cast to `Dog` (smart cast) } else if s is Cat { println('a $s.breed cat') } else { println('something else') } } ``` For more information, see [Dynamic casts](#dynamic-casts). #### Interface method definitions Also unlike Go, an interface may implement a method. These methods are not implemented by structs which implement that interface. When a struct is wrapped in an interface that has implemented a method with the same name as one implemented by this struct, only the method implemented on the interface is called. ```v struct Cat {} fn (c Cat) speak() string { return 'meow!' } interface Adoptable {} fn (a Adoptable) speak() string { return 'adopt me!' } fn new_adoptable() Adoptable { return Cat{} } fn main() { cat := Cat{} assert cat.speak() == 'meow!' a := new_adoptable() assert a.speak() == 'adopt me!' if a is Cat { println(a.speak()) // meow! } } ``` ### Enums ```v enum Color { red green blue } mut color := Color.red // V knows that `color` is a `Color`. No need to use `color = Color.green` here. color = .green println(color) // "green" match color { .red { println('the color was red') } .green { println('the color was green') } .blue { println('the color was blue') } } ``` Enum match must be exhaustive or have an `else` branch. This ensures that if a new enum field is added, it's handled everywhere in the code. Enum fields cannot re-use reserved keywords. However, reserved keywords may be escaped with an @. ```v enum Color { @none red green blue } color := [email protected] println(color) ``` Integers may be assigned to enum fields. ```v enum Grocery { apple orange = 5 pear } g1 := int(Grocery.apple) g2 := int(Grocery.orange) g3 := int(Grocery.pear) println('Grocery IDs: $g1, $g2, $g3') ``` Output: `Grocery IDs: 0, 5, 6`. Operations are not allowed on enum variables; they must be explicity cast to `int`. ### Sum types A sum type instance can hold a value of several different types. Use the `type` keyword to declare a sum type: ```v struct Moon {} struct Mars {} struct Venus {} type World = Mars | Moon | Venus sum := World(Moon{}) assert sum.type_name() == 'Moon' println(sum) ``` The built-in method `type_name` returns the name of the currently held type. With sum types you could build recursive structures and write concise but powerful code on them. ```v // V's binary tree struct Empty {} struct Node { value f64 left Tree right Tree } type Tree = Empty | Node // sum up all node values fn sum(tree Tree) f64 { return match tree { Empty { f64(0) } // TODO: as match gets smarter just remove f64() Node { tree.value + sum(tree.left) + sum(tree.right) } } } fn main() { left := Node{0.2, Empty{}, Empty{}} right := Node{0.3, Empty{}, Node{0.4, Empty{}, Empty{}}} tree := Node{0.5, left, right} println(sum(tree)) // 0.2 + 0.3 + 0.4 + 0.5 = 1.4 } ``` #### Dynamic casts To check whether a sum type instance holds a certain type, use `sum is Type`. To cast a sum type to one of its variants you can use `sum as Type`: ```v struct Moon {} struct Mars {} struct Venus {} type World = Mars | Moon | Venus fn (m Mars) dust_storm() bool { return true } fn main() { mut w := World(Moon{}) assert w is Moon w = Mars{} // use `as` to access the Mars instance mars := w as Mars if mars.dust_storm() { println('bad weather!') } } ``` `as` will panic if `w` doesn't hold a `Mars` instance. A safer way is to use a smart cast. #### Smart casting ```v oksyntax if w is Mars { assert typeof(w).name == 'Mars' if w.dust_storm() { println('bad weather!') } } ``` `w` has type `Mars` inside the body of the `if` statement. This is known as *flow-sensitive typing*. If `w` is a mutable identifier, it would be unsafe if the compiler smart casts it without a warning. That's why you have to declare a `mut` before the `is` expression: ```v ignore if mut w is Mars { assert typeof(w).name == 'Mars' if w.dust_storm() { println('bad weather!') } } ``` Otherwise `w` would keep its original type. > This works for both, simple variables and complex expressions like `user.name` #### Matching sum types You can also use `match` to determine the variant: ```v struct Moon {} struct Mars {} struct Venus {} type World = Mars | Moon | Venus fn open_parachutes(n int) { println(n) } fn land(w World) { match w { Moon {} // no atmosphere Mars { // light atmosphere open_parachutes(3) } Venus { // heavy atmosphere open_parachutes(1) } } } ``` `match` must have a pattern for each variant or have an `else` branch. ```v ignore struct Moon {} struct Mars {} struct Venus {} type World = Moon | Mars | Venus fn (m Moon) moon_walk() {} fn (m Mars) shiver() {} fn (v Venus) sweat() {} fn pass_time(w World) { match w { // using the shadowed match variable, in this case `w` (smart cast) Moon { w.moon_walk() } Mars { w.shiver() } else {} } } ``` ### Type aliases To define a new type `NewType` as an alias for `ExistingType`, do `type NewType = ExistingType`.
This is a special case of a [sum type](#sum-types) declaration. ### Option/Result types and error handling Option types are declared with `?Type`: ```v struct User { id int name string } struct Repo { users []User } fn (r Repo) find_user_by_id(id int) ?User { for user in r.users { if user.id == id { // V automatically wraps this into an option type return user } } return error('User $id not found') } fn main() { repo := Repo{ users: [User{1, 'Andrew'}, User{2, 'Bob'}, User{10, 'Charles'}] } user := repo.find_user_by_id(10) or { // Option types must be handled by `or` blocks return } println(user.id) // "10" println(user.name) // "Charles" } ``` V combines `Option` and `Result` into one type, so you don't need to decide which one to use. The amount of work required to "upgrade" a function to an optional function is minimal; you have to add a `?` to the return type and return an error when something goes wrong. If you don't need to return an error message, you can simply `return none` (this is a more efficient equivalent of `return error("")`). This is the primary mechanism for error handling in V. They are still values, like in Go, but the advantage is that errors can't be unhandled, and handling them is a lot less verbose. Unlike other languages, V does not handle exceptions with `throw/try/catch` blocks. `err` is defined inside an `or` block and is set to the string message passed to the `error()` function. `err` is empty if `none` was returned. ```v oksyntax user := repo.find_user_by_id(7) or { println(err) // "User 7 not found" return } ``` ### Handling optionals There are four ways of handling an optional. The first method is to propagate the error: ```v import net.http fn f(url string) ?string { resp := http.get(url) ? return resp.text } ``` `http.get` returns `?http.Response`. Because `?` follows the call, the error will be propagated to the caller of `f`. When using `?` after a function call producing an optional, the enclosing function must return an optional as well. If error propagation is used in the `main()` function it will `panic` instead, since the error cannot be propagated any further. The body of `f` is essentially a condensed version of: ```v ignore resp := http.get(url) or { return err } return resp.text ``` --- The second method is to break from execution early: ```v oksyntax user := repo.find_user_by_id(7) or { return } ``` Here, you can either call `panic()` or `exit()`, which will stop the execution of the entire program, or use a control flow statement (`return`, `break`, `continue`, etc) to break from the current block. Note that `break` and `continue` can only be used inside a `for` loop. V does not have a way to forcibly "unwrap" an optional (as other languages do, for instance Rust's `unwrap()` or Swift's `!`). To do this, use `or { panic(err.msg) }` instead. --- The third method is to provide a default value at the end of the `or` block. In case of an error, that value would be assigned instead, so it must have the same type as the content of the `Option` being handled. ```v fn do_something(s string) ?string { if s == 'foo' { return 'foo' } return error('invalid string') // Could be `return none` as well } a := do_something('foo') or { 'default' } // a will be 'foo' b := do_something('bar') or { 'default' } // b will be 'default' println(a) println(b) ``` --- The fourth method is to use `if` unwrapping: ```v import net.http if resp := http.get('https://google.com') { println(resp.text) // resp is a http.Response, not an optional } else { println(err) } ``` Above, `http.get` returns a `?http.Response`. `resp` is only in scope for the first `if` branch. `err` is only in scope for the `else` branch. ## Generics ```v wip struct Repo { db DB } struct User { id int name string } struct Post { id int user_id int title string body string } fn new_repo(db DB) Repo { return Repo{db: db} } // This is a generic function. V will generate it for every type it's used with. fn (r Repo) find_by_id(id int) ?T { table_name := T.name // in this example getting the name of the type gives us the table name return r.db.query_one('select * from $table_name where id = ?', id) } db := new_db() users_repo := new_repo(db) // returns Repo posts_repo := new_repo(db) // returns Repo user := users_repo.find_by_id(1)? // find_by_id post := posts_repo.find_by_id(1)? // find_by_id ``` Currently generic function definitions must declare their type parameters, but in future V will infer generic type parameters from single-letter type names in runtime parameter types. This is why `find_by_id` can omit ``, because the receiver argument `r` uses a generic type `T`. Another example: ```v fn compare(a T, b T) int { if a < b { return -1 } if a > b { return 1 } return 0 } // compare println(compare(1, 0)) // Outputs: 1 println(compare(1, 1)) // 0 println(compare(1, 2)) // -1 // compare println(compare('1', '0')) // Outputs: 1 println(compare('1', '1')) // 0 println(compare('1', '2')) // -1 // compare println(compare(1.1, 1.0)) // Outputs: 1 println(compare(1.1, 1.1)) // 0 println(compare(1.1, 1.2)) // -1 ``` ## Concurrency ### Spawning Concurrent Tasks V's model of concurrency is very similar to Go's. To run `foo()` concurrently in a different thread, just call it with `go foo()`: ```v import math fn p(a f64, b f64) { // ordinary function without return value c := math.sqrt(a * a + b * b) println(c) } fn main() { go p(3, 4) // p will be run in parallel thread } ``` Sometimes it is necessary to wait until a parallel thread has finished. This can be done by assigning a *handle* to the started thread and calling the `wait()` method to this handle later: ```v import math fn p(a f64, b f64) { // ordinary function without return value c := math.sqrt(a * a + b * b) println(c) // prints `5` } fn main() { h := go p(3, 4) // p() runs in parallel thread h.wait() // p() has definitely finished } ``` This approach can also be used to get a return value from a function that is run in a parallel thread. There is no need to modify the function itself to be able to call it concurrently. ```v import math { sqrt } fn get_hypot(a f64, b f64) f64 { // ordinary function returning a value c := sqrt(a * a + b * b) return c } fn main() { g := go get_hypot(54.06, 2.08) // spawn thread and get handle to it h1 := get_hypot(2.32, 16.74) // do some other calculation here h2 := g.wait() // get result from spawned thread println('Results: $h1, $h2') // prints `Results: 16.9, 54.1` } ``` If there is a large number of tasks, it might be easier to manage them using an array of threads. ```v import time fn task(id int, duration int) { println('task $id begin') time.sleep(duration * time.millisecond) println('task $id end') } fn main() { mut threads := []thread{} threads << go task(1, 500) threads << go task(2, 900) threads << go task(3, 100) threads.wait() println('done') } // Output: // task 1 begin // task 2 begin // task 3 begin // task 3 end // task 1 end // task 2 end // done ``` Additionally for threads that return the same type, calling `wait()` on the thread array will return all computed values. ```v fn expensive_computing(i int) int { return i * i } fn main() { mut threads := []thread int{} for i in 1 .. 10 { threads << go expensive_computing(i) } // Join all tasks r := threads.wait() println('All jobs finished: $r') } // Output: All jobs finished: [1, 4, 9, 16, 25, 36, 49, 64, 81] ``` ### Channels Channels are the preferred way to communicate between coroutines. V's channels work basically like those in Go. You can push objects into a channel on one end and pop objects from the other end. Channels can be buffered or unbuffered and it is possible to `select` from multiple channels. #### Syntax and Usage Channels have the type `chan objtype`. An optional buffer length can specified as the `cap` property in the declaration: ```v ch := chan int{} // unbuffered - "synchronous" ch2 := chan f64{cap: 100} // buffer length 100 ``` Channels do not have to be declared as `mut`. The buffer length is not part of the type but a property of the individual channel object. Channels can be passed to coroutines like normal variables: ```v fn f(ch chan int) { // ... } fn main() { ch := chan int{} go f(ch) // ... } ``` Objects can be pushed to channels using the arrow operator. The same operator can be used to pop objects from the other end: ```v // make buffered channels so pushing does not block (if there is room in the buffer) ch := chan int{cap: 1} ch2 := chan f64{cap: 1} n := 5 // push ch <- n ch2 <- 7.3 mut y := f64(0.0) m := <-ch // pop creating new variable y = <-ch2 // pop into existing variable ``` A channel can be closed to indicate that no further objects can be pushed. Any attempt to do so will then result in a runtime panic (with the exception of `select` and `try_push()` - see below). Attempts to pop will return immediately if the associated channel has been closed and the buffer is empty. This situation can be handled using an or branch (see [Handling Optionals](#handling-optionals)). ```v wip ch := chan int{} ch2 := chan f64{} // ... ch.close() // ... m := <-ch or { println('channel has been closed') } // propagate error y := <-ch2 ? ``` #### Channel Select The `select` command allows monitoring several channels at the same time without noticeable CPU load. It consists of a list of possible transfers and associated branches of statements - similar to the [match](#match) command: ```v wip import time fn main () { c := chan f64{} ch := chan f64{} ch2 := chan f64{} ch3 := chan f64{} mut b := 0.0 // ... select { a := <-ch { // do something with `a` } b = <-ch2 { // do something with predeclared variable `b` } ch3 <- c { // do something if `c` was sent } > 500 * time.millisecond { // do something if no channel has become ready within 0.5s } } } ``` The timeout branch is optional. If it is absent `select` waits for an unlimited amount of time. It is also possible to proceed immediately if no channel is ready in the moment `select` is called by adding an `else { ... }` branch. `else` and `> timeout` are mutually exclusive. The `select` command can be used as an *expression* of type `bool` that becomes `false` if all channels are closed: ```v wip if select { ch <- a { // ... } } { // channel was open } else { // channel is closed } ``` #### Special Channel Features For special purposes there are some builtin properties and methods: ```v struct Abc { x int } a := 2.13 ch := chan f64{} res := ch.try_push(a) // try to perform `ch <- a` println(res) l := ch.len // number of elements in queue c := ch.cap // maximum queue length is_closed := ch.closed // bool flag - has `ch` been closed println(l) println(c) mut b := Abc{} ch2 := chan Abc{} res2 := ch2.try_pop(mut b) // try to perform `b = <-ch2` ``` The `try_push/pop()` methods will return immediately with one of the results `.success`, `.not_ready` or `.closed` - dependent on whether the object has been transferred or the reason why not. Usage of these methods and properties in production is not recommended - algorithms based on them are often subject to race conditions. Especially `.len` and `.closed` should not be used to make decisions. Use `or` branches, error propagation or `select` instead (see [Syntax and Usage](#syntax-and-usage) and [Channel Select](#channel-select) above). ### Shared Objects Data can be exchanged between a coroutine and the calling thread via a shared variable. Such variables should be created as `shared` and passed to the coroutine as such, too. The underlying `struct` contains a hidden *mutex* that allows locking concurrent access using `rlock` for read-only and `lock` for read/write access. ```v struct St { mut: x int // data to shared } fn (shared b St) g() { lock b { // read/modify/write b.x } } fn main() { shared a := St{ x: 10 } go a.g() // ... rlock a { // read a.x } } ``` Shared variables must be structs, arrays or maps. ## Decoding JSON ```v import json struct Foo { x int } struct User { name string age int // Use the `skip` attribute to skip certain fields foo Foo [skip] // If the field name is different in JSON, it can be specified last_name string [json: lastName] } data := '{ "name": "Frodo", "lastName": "Baggins", "age": 25 }' user := json.decode(User, data) or { eprintln('Failed to decode json') return } println(user.name) println(user.last_name) println(user.age) // You can also decode JSON arrays: sfoos := '[{"x":123},{"x":456}]' foos := json.decode([]Foo, sfoos) ? println(foos[0].x) println(foos[1].x) ``` Because of the ubiquitous nature of JSON, support for it is built directly into V. The `json.decode` function takes two arguments: the first is the type into which the JSON value should be decoded and the second is a string containing the JSON data. V generates code for JSON encoding and decoding. No runtime reflection is used. This results in much better performance. ## Testing ### Asserts ```v fn foo(mut v []int) { v[0] = 1 } mut v := [20] foo(mut v) assert v[0] < 4 ``` An `assert` statement checks that its expression evaluates to `true`. If an assert fails, the program will abort. Asserts should only be used to detect programming errors. When an assert fails it is reported to *stderr*, and the values on each side of a comparison operator (such as `<`, `==`) will be printed when possible. This is useful to easily find an unexpected value. Assert statements can be used in any function. ### Test files ```v // hello.v module main fn hello() string { return 'Hello world' } fn main() { println(hello()) } ``` ```v failcompile module main // hello_test.v fn test_hello() { assert hello() == 'Hello world' } ``` To run the test above, use `v hello_test.v`. This will check that the function `hello` is producing the correct output. V executes all test functions in the file. * All test functions have to be inside a test file whose name ends in `_test.v`. * Test function names must begin with `test_` to mark them for execution. * Normal functions can also be defined in test files, and should be called manually. Other symbols can also be defined in test files e.g. types. * There are two kinds of tests: external and internal. * Internal tests must *declare* their module, just like all other .v files from the same module. Internal tests can even call private functions in the same module. * External tests must *import* the modules which they test. They do not have access to the private functions/types of the modules. They can test only the external/public API that a module provides. In the example above, `test_hello` is an internal test, that can call the private function `hello()` because `hello_test.v` has `module main`, just like `hello.v`, i.e. both are part of the same module. Note also that since `module main` is a regular module like the others, internal tests can be used to test private functions in your main program .v files too. You can also define special test functions in a test file: * `testsuite_begin` which will be run *before* all other test functions. * `testsuite_end` which will be run *after* all other test functions. #### Running tests To run test functions in an individual test file, use `v foo_test.v`. To test an entire module, use `v test mymodule`. You can also use `v test .` to test everything inside your current folder (and subfolders). You can pass the `-stats` option to see more details about the individual tests run. ## Memory management V avoids doing unnecessary allocations in the first place by using value types, string buffers, promoting a simple abstraction-free code style. Most objects (~90-100%) are freed by V's autofree engine: the compiler inserts necessary free calls automatically during compilation. Remaining small percentage of objects is freed via reference counting. The developer doesn't need to change anything in their code. "It just works", like in Python, Go, or Java, except there's no heavy GC tracing everything or expensive RC for each object. ### Control You can take advantage of V's autofree engine and define a `free()` method on custom data types: ```v struct MyType {} [unsafe] fn (data &MyType) free() { // ... } ``` Just as the compiler frees C data types with C's `free()`, it will statically insert `free()` calls for your data type at the end of each variable's lifetime. For developers willing to have more low level control, autofree can be disabled with `-manualfree`, or by adding a `[manualfree]` on each function that wants manage its memory manually. (See [attributes](#attributes)). _Note: right now autofree is hidden behind the -autofree flag. It will be enabled by default in V 0.3. If autofree is not used, V programs will leak memory._ ### Examples ```v import strings fn draw_text(s string, x int, y int) { // ... } fn draw_scene() { // ... name1 := 'abc' name2 := 'def ghi' draw_text('hello $name1', 10, 10) draw_text('hello $name2', 100, 10) draw_text(strings.repeat(`X`, 10000), 10, 50) // ... } ``` The strings don't escape `draw_text`, so they are cleaned up when the function exits. In fact, with the `-prealloc` flag, the first two calls won't result in any allocations at all. These two strings are small, so V will use a preallocated buffer for them. ```v struct User { name string } fn test() []int { number := 7 // stack variable user := User{} // struct allocated on stack numbers := [1, 2, 3] // array allocated on heap, will be freed as the function exits println(number) println(user) println(numbers) numbers2 := [4, 5, 6] // array that's being returned, won't be freed here return numbers2 } ``` ## ORM (This is still in an alpha state) V has a built-in ORM (object-relational mapping) which supports SQLite, MySQL and Postgres, but soon it will support MS SQL and Oracle. V's ORM provides a number of benefits: - One syntax for all SQL dialects. (Migrating between databases becomes much easier.) - Queries are constructed using V's syntax. (There's no need to learn another syntax.) - Safety. (All queries are automatically sanitised to prevent SQL injection.) - Compile time checks. (This prevents typos which can only be caught during runtime.) - Readability and simplicity. (You don't need to manually parse the results of a query and then manually construct objects from the parsed results.) ```v import sqlite struct Customer { // struct name has to be the same as the table name (for now) id int [primary; sql: serial] // a field named `id` of integer type must be the first field name string [nonull] nr_orders int country string [nonull] } db := sqlite.connect('customers.db') ? // you can create tables // CREATE TABLE IF NOT EXISTS `Customer` (`id` INTEGER PRIMARY KEY, `name` TEXT NOT NULL, `nr_orders` INTEGER, `country` TEXT NOT NULL) sql db { create table Customer } // select count(*) from Customer nr_customers := sql db { select count from Customer } println('number of all customers: $nr_customers') // V syntax can be used to build queries uk_customers := sql db { select from Customer where country == 'uk' && nr_orders > 0 } println(uk_customers.len) for customer in uk_customers { println('$customer.id - $customer.name') } // by adding `limit 1` we tell V that there will be only one object customer := sql db { select from Customer where id == 1 limit 1 } println('$customer.id - $customer.name') // insert a new customer new_customer := Customer{ name: 'Bob' nr_orders: 10 } sql db { insert new_customer into Customer } ``` For more examples and the docs, see
vlib/orm. ## Writing Documentation The way it works is very similar to Go. It's very simple: there's no need to write documentation separately for your code, vdoc will generate it from docstrings in the source code. Documentation for each function/type/const must be placed right before the declaration: ```v // clearall clears all bits in the array fn clearall() { } ``` The comment must start with the name of the definition. Sometimes one line isn't enough to explain what a function does, in that case comments should span to the documented function using single line comments: ```v // copy_all recursively copies all elements of the array by their value, // if `dupes` is false all duplicate values are eliminated in the process. fn copy_all(dupes bool) { // ... } ``` By convention it is preferred that comments are written in *present tense*. An overview of the module must be placed in the first comment right after the module's name. To generate documentation use vdoc, for example `v doc net.http`. ## Tools ### v fmt You don't need to worry about formatting your code or setting style guidelines. `v fmt` takes care of that: ```shell v fmt file.v ``` It's recommended to set up your editor, so that `v fmt -w` runs on every save. A vfmt run is usually pretty cheap (takes <30ms). Always run `v fmt -w file.v` before pushing your code. ### Profiling V has good support for profiling your programs: `v -profile profile.txt run file.v` That will produce a profile.txt file, which you can then analyze. The generated profile.txt file will have lines with 4 columns: a) how many times a function was called b) how much time in total a function took (in ms) c) how much time on average, a call to a function took (in ns) d) the name of the v function You can sort on column 3 (average time per function) using: `sort -n -k3 profile.txt|tail` You can also use stopwatches to measure just portions of your code explicitly: ```v import time fn main() { sw := time.new_stopwatch({}) println('Hello world') println('Greeting the world took: ${sw.elapsed().nanoseconds()}ns') } ``` # Advanced Topics ## Dumping expressions at runtime You can dump/trace the value of any V expression using `dump(expr)`. For example, save this code sample as `factorial.v`, then run it with `v run factorial.v`: ```v fn factorial(n u32) u32 { if dump(n <= 1) { return dump(1) } return dump(n * factorial(n - 1)) } fn main() { println(factorial(5)) } ``` You will get: ``` [factorial.v:2] n <= 1: false [factorial.v:2] n <= 1: false [factorial.v:2] n <= 1: false [factorial.v:2] n <= 1: false [factorial.v:2] n <= 1: true [factorial.v:3] 1: 1 [factorial.v:5] n * factorial(n - 1): 2 [factorial.v:5] n * factorial(n - 1): 6 [factorial.v:5] n * factorial(n - 1): 24 [factorial.v:5] n * factorial(n - 1): 120 120 ``` Note that `dump(expr)` will trace both the source location, the expression itself, and the expression value. ## Memory-unsafe code Sometimes for efficiency you may want to write low-level code that can potentially corrupt memory or be vulnerable to security exploits. V supports writing such code, but not by default. V requires that any potentially memory-unsafe operations are marked intentionally. Marking them also indicates to anyone reading the code that there could be memory-safety violations if there was a mistake. Examples of potentially memory-unsafe operations are: * Pointer arithmetic * Pointer indexing * Conversion to pointer from an incompatible type * Calling certain C functions, e.g. `free`, `strlen` and `strncmp`. To mark potentially memory-unsafe operations, enclose them in an `unsafe` block: ```v wip // allocate 2 uninitialized bytes & return a reference to them mut p := unsafe { malloc(2) } p[0] = `h` // Error: pointer indexing is only allowed in `unsafe` blocks unsafe { p[0] = `h` // OK p[1] = `i` } p++ // Error: pointer arithmetic is only allowed in `unsafe` blocks unsafe { p++ // OK } assert *p == `i` ``` Best practice is to avoid putting memory-safe expressions inside an `unsafe` block, so that the reason for using `unsafe` is as clear as possible. Generally any code you think is memory-safe should not be inside an `unsafe` block, so the compiler can verify it. If you suspect your program does violate memory-safety, you have a head start on finding the cause: look at the `unsafe` blocks (and how they interact with surrounding code). * Note: This is work in progress. ### Structs with reference fields Structs with references require explicitly setting the initial value to a reference value unless the struct already defines its own initial value. Zero-value references, or nil pointers, will **NOT** be supported in the future, for now data structures such as Linked Lists or Binary Trees that rely on reference fields that can use the value `0`, understanding that it is unsafe, and that it can cause a panic. ```v struct Node { a &Node b &Node = 0 // Auto-initialized to nil, use with caution! } // Reference fields must be initialized unless an initial value is declared. // Zero (0) is OK but use with caution, it's a nil pointer. foo := Node{ a: 0 } bar := Node{ a: &foo } baz := Node{ a: 0 b: 0 } qux := Node{ a: &foo b: &bar } println(baz) println(qux) ``` ## sizeof and __offsetof * `sizeof(Type)` gives the size of a type in bytes. * `__offsetof(Struct, field_name)` gives the offset in bytes of a struct field. ```v struct Foo { a int b int } assert sizeof(Foo) == 8 assert __offsetof(Foo, a) == 0 assert __offsetof(Foo, b) == 4 ``` ## Calling C from V ### Example ```v #flag -lsqlite3 #include "sqlite3.h" // See also the example from https://www.sqlite.org/quickstart.html struct C.sqlite3 { } struct C.sqlite3_stmt { } type FnSqlite3Callback = fn (voidptr, int, &&char, &&char) int fn C.sqlite3_open(&char, &&C.sqlite3) int fn C.sqlite3_close(&C.sqlite3) int fn C.sqlite3_column_int(stmt &C.sqlite3_stmt, n int) int // ... you can also just define the type of parameter and leave out the C. prefix fn C.sqlite3_prepare_v2(&C.sqlite3, &char, int, &&C.sqlite3_stmt, &&char) int fn C.sqlite3_step(&C.sqlite3_stmt) fn C.sqlite3_finalize(&C.sqlite3_stmt) fn C.sqlite3_exec(db &C.sqlite3, sql &char, cb FnSqlite3Callback, cb_arg voidptr, emsg &&char) int fn C.sqlite3_free(voidptr) fn my_callback(arg voidptr, howmany int, cvalues &&char, cnames &&char) int { unsafe { for i in 0 .. howmany { print('| ${cstring_to_vstring(cnames[i])}: ${cstring_to_vstring(cvalues[i]):20} ') } } println('|') return 0 } fn main() { db := &C.sqlite3(0) // this means `sqlite3* db = 0` // passing a string literal to a C function call results in a C string, not a V string C.sqlite3_open('users.db', &db) // C.sqlite3_open(db_path.str, &db) query := 'select count(*) from users' stmt := &C.sqlite3_stmt(0) // NB: you can also use the `.str` field of a V string, // to get its C style zero terminated representation C.sqlite3_prepare_v2(db, &char(query.str), -1, &stmt, 0) C.sqlite3_step(stmt) nr_users := C.sqlite3_column_int(stmt, 0) C.sqlite3_finalize(stmt) println('There are $nr_users users in the database.') // error_msg := &char(0) query_all_users := 'select * from users' rc := C.sqlite3_exec(db, &char(query_all_users.str), my_callback, voidptr(7), &error_msg) if rc != C.SQLITE_OK { eprintln(unsafe { cstring_to_vstring(error_msg) }) C.sqlite3_free(error_msg) } C.sqlite3_close(db) } ``` ### Passing C compilation flags Add `#flag` directives to the top of your V files to provide C compilation flags like: - `-I` for adding C include files search paths - `-l` for adding C library names that you want to get linked - `-L` for adding C library files search paths - `-D` for setting compile time variables You can (optionally) use different flags for different targets. Currently the `linux`, `darwin` , `freebsd`, and `windows` flags are supported. NB: Each flag must go on its own line (for now) ```v oksyntax #flag linux -lsdl2 #flag linux -Ivig #flag linux -DCIMGUI_DEFINE_ENUMS_AND_STRUCTS=1 #flag linux -DIMGUI_DISABLE_OBSOLETE_FUNCTIONS=1 #flag linux -DIMGUI_IMPL_API= ``` In the console build command, you can use: * `-cflags` to pass custom flags to the backend C compiler. * `-cc` to change the default C backend compiler. * For example: `-cc gcc-9 -cflags -fsanitize=thread`. You can define a `VFLAGS` environment variable in your terminal to store your `-cc` and `-cflags` settings, rather than including them in the build command each time. ### #pkgconfig Add `#pkgconfig` directive is used to tell the compiler which modules should be used for compiling and linking using the pkg-config files provided by the respective dependencies. As long as backticks can't be used in `#flag` and spawning processes is not desirable for security and portability reasons, V uses its own pkgconfig library that is compatible with the standard freedesktop one. If no flags are passed it will add `--cflags` and `--libs`, both lines below do the same: ```v oksyntax #pkgconfig r_core #pkgconfig --cflags --libs r_core ``` The `.pc` files are looked up into a hardcoded list of default pkg-config paths, the user can add extra paths by using the `PKG_CONFIG_PATH` environment variable. Multiple modules can be passed. ### Including C code You can also include C code directly in your V module. For example, let's say that your C code is located in a folder named 'c' inside your module folder. Then: * Put a v.mod file inside the toplevel folder of your module (if you created your module with `v new` you already have v.mod file). For example: ```v ignore Module { name: 'mymodule', description: 'My nice module wraps a simple C library.', version: '0.0.1' dependencies: [] } ``` * Add these lines to the top of your module: ```v oksyntax #flag -I @VMODROOT/c #flag @VMODROOT/c/implementation.o #include "header.h" ``` NB: @VMODROOT will be replaced by V with the *nearest parent folder, where there is a v.mod file*. Any .v file beside or below the folder where the v.mod file is, can use `#flag @VMODROOT/abc` to refer to this folder. The @VMODROOT folder is also *prepended* to the module lookup path, so you can *import* other modules under your @VMODROOT, by just naming them. The instructions above will make V look for an compiled .o file in your module `folder/c/implementation.o`. If V finds it, the .o file will get linked to the main executable, that used the module. If it does not find it, V assumes that there is a `@VMODROOT/c/implementation.c` file, and tries to compile it to a .o file, then will use that. This allows you to have C code, that is contained in a V module, so that its distribution is easier. You can see a complete minimal example for using C code in a V wrapper module here: [project_with_c_code](https://github.com/vlang/v/tree/master/vlib/v/tests/project_with_c_code). Another example, demonstrating passing structs from C to V and back again: [interoperate between C to V to C](https://github.com/vlang/v/tree/master/vlib/v/tests/project_with_c_code_2). ### C types Ordinary zero terminated C strings can be converted to V strings with `unsafe { &char(cstring).vstring() }` or if you know their length already with `unsafe { &char(cstring).vstring_with_len(len) }`. NB: The .vstring() and .vstring_with_len() methods do NOT create a copy of the `cstring`, so you should NOT free it after calling the method `.vstring()`. If you need to make a copy of the C string (some libc APIs like `getenv` pretty much require that, since they return pointers to internal libc memory), you can use `cstring_to_vstring(cstring)`. On Windows, C APIs often return so called `wide` strings (utf16 encoding). These can be converted to V strings with `string_from_wide(&u16(cwidestring))` . V has these types for easier interoperability with C: - `voidptr` for C's `void*`, - `&byte` for C's `byte*` and - `&char` for C's `char*`. - `&&char` for C's `char**` To cast a `voidptr` to a V reference, use `user := &User(user_void_ptr)`. `voidptr` can also be dereferenced into a V struct through casting: `user := User(user_void_ptr)`. [an example of a module that calls C code from V](https://github.com/vlang/v/blob/master/vlib/v/tests/project_with_c_code/mod1/wrapper.v) ### C Declarations C identifiers are accessed with the `C` prefix similarly to how module-specific identifiers are accessed. Functions must be redeclared in V before they can be used. Any C types may be used behind the `C` prefix, but types must be redeclared in V in order to access type members. To redeclare complex types, such as in the following C code: ```c struct SomeCStruct { uint8_t implTraits; uint16_t memPoolData; union { struct { void* data; size_t size; }; DataView view; }; }; ``` members of sub-data-structures may be directly declared in the containing struct as below: ```v struct C.SomeCStruct { implTraits byte memPoolData u16 // These members are part of sub data structures that can't currently be represented in V. // Declaring them directly like this is sufficient for access. // union { // struct { data voidptr size size_t // } view C.DataView // } } ``` The existence of the data members is made known to V, and they may be used without re-creating the original structure exactly. Alternatively, you may [embed](#embedded-structs) the sub-data-structures to maintain a parallel code structure. ## Debugging generated C code To debug issues in the generated C code, you can pass these flags: - `-g` - produces a less optimized executable with more debug information in it. V will enforce line numbers from the .v files in the stacktraces, that the executable will produce on panic. It is usually better to pass -g, unless you are writing low level code, in which case use the next option `-cg`. - `-cg` - produces a less optimized executable with more debug information in it. The executable will use C source line numbers in this case. It is frequently used in combination with `-keepc`, so that you can inspect the generated C program in case of panic, or so that your debugger (`gdb`, `lldb` etc.) can show you the generated C source code. - `-showcc` - prints the C command that is used to build the program. - `-show-c-output` - prints the output, that your C compiler produced while compiling your program. - `-keepc` - do not delete the generated C source code file after a successful compilation. Also keep using the same file path, so it is more stable, and easier to keep opened in an editor/IDE. For best debugging experience if you are writing a low level wrapper for an existing C library, you can pass several of these flags at the same time: `v -keepc -cg -showcc yourprogram.v`, then just run your debugger (gdb/lldb) or IDE on the produced executable `yourprogram`. If you just want to inspect the generated C code, without further compilation, you can also use the `-o` flag (e.g. `-o file.c`). This will make V produce the `file.c` then stop. If you want to see the generated C source code for *just* a single C function, for example `main`, you can use: `-printfn main -o file.c`. To see a detailed list of all flags that V supports, use `v help`, `v help build` and `v help build-c`. ## Conditional compilation ### Compile time code `$` is used as a prefix for compile-time operations. #### $if ```v // Support for multiple conditions in one branch $if ios || android { println('Running on a mobile device!') } $if linux && x64 { println('64-bit Linux.') } // Usage as expression os := $if windows { 'Windows' } $else { 'UNIX' } println('Using $os') // $else-$if branches $if tinyc { println('tinyc') } $else $if clang { println('clang') } $else $if gcc { println('gcc') } $else { println('different compiler') } $if test { println('testing') } // v -cg ... $if debug { println('debugging') } // v -prod ... $if prod { println('production build') } // v -d option ... $if option ? { println('custom option') } ``` If you want an `if` to be evaluated at compile time it must be prefixed with a `$` sign. Right now it can be used to detect an OS, compiler, platform or compilation options. `$if debug` is a special option like `$if windows` or `$if x32`. If you're using a custom ifdef, then you do need `$if option ? {}` and compile with`v -d option`. Full list of builtin options: | OS | Compilers | Platforms | Other | | --- | --- | --- | --- | | `windows`, `linux`, `macos` | `gcc`, `tinyc` | `amd64`, `arm64` | `debug`, `prod`, `test` | | `mac`, `darwin`, `ios`, | `clang`, `mingw` | `x64`, `x32` | `js`, `glibc`, `prealloc` | | `android`,`mach`, `dragonfly` | `msvc` | `little_endian` | `no_bounds_checking`, `freestanding` | | `gnu`, `hpux`, `haiku`, `qnx` | `cplusplus` | `big_endian` | | `solaris` | | | | #### $embed_file ```v ignore import os fn main() { embedded_file := $embed_file('v.png') os.write_file('exported.png', embedded_file.to_string()) ? } ``` V can embed arbitrary files into the executable with the `$embed_file()` compile time call. Paths can be absolute or relative to the source file. When you do not use `-prod`, the file will not be embedded. Instead, it will be loaded *the first time* your program calls `f.data()` at runtime, making it easier to change in external editor programs, without needing to recompile your executable. When you compile with `-prod`, the file *will be embedded inside* your executable, increasing your binary size, but making it more self contained and thus easier to distribute. In this case, `f.data()` will cause *no IO*, and it will always return the same data. #### $tmpl for embedding and parsing V template files V has a simple template language for text and html templates, and they can easily be embedded via `$tmpl('path/to/template.txt')`: ```v ignore fn build() string { name := 'Peter' age := 25 numbers := [1, 2, 3] return $tmpl('1.txt') } fn main() { println(build()) } ``` 1.txt: ``` name: @name age: @age numbers: @numbers @for number in numbers @number @end ``` output: ``` name: Peter age: 25 numbers: [1, 2, 3] 1 2 3 ``` #### $env ```v module main fn main() { compile_time_env := $env('ENV_VAR') println(compile_time_env) } ``` V can bring in values at compile time from environment variables. `$env('ENV_VAR')` can also be used in top-level `#flag` and `#include` statements: `#flag linux -I $env('JAVA_HOME')/include`. ### Environment specific files If a file has an environment-specific suffix, it will only be compiled for that environment. - `.js.v` => will be used only by the JS backend. These files can contain JS. code. - `.c.v` => will be used only by the C backend. These files can contain C. code. - `.native.v` => will be used only by V's native backend. - `_nix.c.v` => will be used only on Unix systems (non Windows). - `_${os}.c.v` => will be used only on the specific `os` system. For example, `_windows.c.v` will be used only when compiling on Windows, or with `-os windows`. - `_default.c.v` => will be used only if there is NOT a more specific platform file. For example, if you have both `file_linux.c.v` and `file_default.c.v`, and you are compiling for linux, then only `file_linux.c.v` will be used, and `file_default.c.v` will be ignored. Here is a more complete example: main.v: ```v ignore module main fn main() { println(message) } ``` main_default.c.v: ```v ignore module main const ( message = 'Hello world' ) ``` main_linux.c.v: ```v ignore module main const ( message = 'Hello linux' ) ``` main_windows.c.v: ```v ignore module main const ( message = 'Hello windows' ) ``` With the example above: - when you compile for windows, you will get 'Hello windows' - when you compile for linux, you will get 'Hello linux' - when you compile for any other platform, you will get the non specific 'Hello world' message. - `_d_customflag.v` => will be used *only* if you pass `-d customflag` to V. That corresponds to `$if customflag ? {}`, but for a whole file, not just a single block. `customflag` should be a snake_case identifier, it can not contain arbitrary characters (only lower case latin letters + numbers + `_`). NB: a combinatorial `_d_customflag_linux.c.v` postfix will not work. If you do need a custom flag file, that has platform dependent code, use the postfix `_d_customflag.v`, and then use plaftorm dependent compile time conditional blocks inside it, i.e. `$if linux {}` etc. - `_notd_customflag.v` => similar to _d_customflag.v, but will be used *only* if you do NOT pass `-d customflag` to V. ## Compile time pseudo variables V also gives your code access to a set of pseudo string variables, that are substituted at compile time: - `@FN` => replaced with the name of the current V function - `@METHOD` => replaced with ReceiverType.MethodName - `@MOD` => replaced with the name of the current V module - `@STRUCT` => replaced with the name of the current V struct - `@FILE` => replaced with the path of the V source file - `@LINE` => replaced with the V line number where it appears (as a string). - `@COLUMN` => replaced with the column where it appears (as a string). - `@VEXE` => replaced with the path to the V compiler - `@VEXEROOT` => will be substituted with the *folder*, where the V executable is (as a string). - `@VHASH` => replaced with the shortened commit hash of the V compiler (as a string). - `@VMOD_FILE` => replaced with the contents of the nearest v.mod file (as a string). - `@VMODROOT` => will be substituted with the *folder*, where the nearest v.mod file is (as a string). That allows you to do the following example, useful while debugging/logging/tracing your code: ```v eprintln('file: ' + @FILE + ' | line: ' + @LINE + ' | fn: ' + @MOD + '.' + @FN) ``` Another example, is if you want to embed the version/name from v.mod *inside* your executable: ```v ignore import v.vmod vm := vmod.decode( @VMOD_FILE ) or { panic(err.msg) } eprintln('$vm.name $vm.version\n $vm.description') ``` ## Performance tuning The generated C code is usually fast enough, when you compile your code with `-prod`. There are some situations though, where you may want to give additional hints to the compiler, so that it can further optimize some blocks of code. NB: These are *rarely* needed, and should not be used, unless you *profile your code*, and then see that there are significant benefits for them. To cite gcc's documentation: "programmers are notoriously bad at predicting how their programs actually perform". `[inline]` - you can tag functions with `[inline]`, so the C compiler will try to inline them, which in some cases, may be beneficial for performance, but may impact the size of your executable. `[direct_array_access]` - in functions tagged with `[direct_array_access]` the compiler will translate array operations directly into C array operations - omiting bounds checking. This may save a lot of time in a function that iterates over an array but at the cost of making the function unsafe - unless the boundaries will be checked by the user. `if _likely_(bool expression) {` this hints the C compiler, that the passed boolean expression is very likely to be true, so it can generate assembly code, with less chance of branch misprediction. In the JS backend, that does nothing. `if _unlikely_(bool expression) {` similar to `_likely_(x)`, but it hints that the boolean expression is highly improbable. In the JS backend, that does nothing. ## Compile-time reflection Having built-in JSON support is nice, but V also allows you to create efficient serializers for any data format. V has compile-time `if` and `for` constructs: ```v wip // TODO: not fully implemented struct User { name string age int } // Note: T should be passed a struct name only fn decode(data string) T { mut result := T{} // compile-time `for` loop // T.fields gives an array of a field metadata type $for field in T.fields { $if field.typ is string { // $(string_expr) produces an identifier result.$(field.name) = get_string(data, field.name) } $else $if field.typ is int { result.$(field.name) = get_int(data, field.name) } } return result } // `decode` generates: fn decode_User(data string) User { mut result := User{} result.name = get_string(data, 'name') result.age = get_int(data, 'age') return result } ``` ## Limited operator overloading ```v struct Vec { x int y int } fn (a Vec) str() string { return '{$a.x, $a.y}' } fn (a Vec) + (b Vec) Vec { return Vec{a.x + b.x, a.y + b.y} } fn (a Vec) - (b Vec) Vec { return Vec{a.x - b.x, a.y - b.y} } fn main() { a := Vec{2, 3} b := Vec{4, 5} mut c := Vec{1, 2} println(a + b) // "{6, 8}" println(a - b) // "{-2, -2}" c += a println(c) // "{3, 5}" } ``` Operator overloading goes against V's philosophy of simplicity and predictability. But since scientific and graphical applications are among V's domains, operator overloading is an important feature to have in order to improve readability: `a.add(b).add(c.mul(d))` is a lot less readable than `a + b + c * d`. To improve safety and maintainability, operator overloading is limited: - It's only possible to overload `+, -, *, /, %, <, >, ==, !=, <=, >=` operators. - `==` and `!=` are self generated by the compiler but can be overriden. - Calling other functions inside operator functions is not allowed. - Operator functions can't modify their arguments. - When using `<` and `==` operators, the return type must be `bool`. - `!=`, `>`, `<=` and `>=` are auto generated when `==` and `<` are defined. - Both arguments must have the same type (just like with all operators in V). - Assignment operators (`*=`, `+=`, `/=`, etc) are auto generated when the operators are defined though they must return the same type. ## Inline assembly ```v ignore a := 100 b := 20 mut c := 0 asm amd64 { mov eax, a add eax, b mov c, eax ; =r (c) as c // output ; r (a) as a // input r (b) as b } println('a: $a') // 100 println('b: $b') // 20 println('c: $c') // 120 ``` For more examples, see [github.com/vlang/v/tree/master/vlib/v/tests/assembly/asm_test.amd64.v](https://github.com/vlang/v/tree/master/vlib/v/tests/assembly/asm_test.amd64.v) ## Translating C to V TODO: translating C to V will be available in V 0.3. V can translate your C code to human readable V code and generate V wrappers on top of C libraries. Let's create a simple program `test.c` first: ```c #include "stdio.h" int main() { for (int i = 0; i < 10; i++) { printf("hello world\n"); } return 0; } ``` Run `v translate test.c`, and V will generate `test.v`: ```v fn main() { for i := 0; i < 10; i++ { println('hello world') } } ``` To generate a wrapper on top of a C library use this command: ```bash v wrapper c_code/libsodium/src/libsodium ``` This will generate a directory `libsodium` with a V module. Example of a C2V generated libsodium wrapper: https://github.com/medvednikov/libsodium
When should you translate C code and when should you simply call C code from V? If you have well-written, well-tested C code, then of course you can always simply call this C code from V. Translating it to V gives you several advantages: - If you plan to develop that code base, you now have everything in one language, which is much safer and easier to develop in than C. - Cross-compilation becomes a lot easier. You don't have to worry about it at all. - No more build flags and include files either. ## Hot code reloading ```v live module main import time import os [live] fn print_message() { println('Hello! Modify this message while the program is running.') } fn main() { for { print_message() time.sleep(500 * time.millisecond) } } ``` Build this example with `v -live message.v`. Functions that you want to be reloaded must have `[live]` attribute before their definition. Right now it's not possible to modify types while the program is running. More examples, including a graphical application: [github.com/vlang/v/tree/master/examples/hot_code_reload](https://github.com/vlang/v/tree/master/examples/hot_reload). ## Cross compilation To cross compile your project simply run ```shell v -os windows . ``` or ```shell v -os linux . ``` (Cross compiling for macOS is temporarily not possible.) If you don't have any C dependencies, that's all you need to do. This works even when compiling GUI apps using the `ui` module or graphical apps using `gg`. You will need to install Clang, LLD linker, and download a zip file with libraries and include files for Windows and Linux. V will provide you with a link. ## Cross-platform shell scripts in V V can be used as an alternative to Bash to write deployment scripts, build scripts, etc. The advantage of using V for this is the simplicity and predictability of the language, and cross-platform support. "V scripts" run on Unix-like systems as well as on Windows. Use the `.vsh` file extension. It will make all functions in the `os` module global (so that you can use `mkdir()` instead of `os.mkdir()`, for example). An example `deploy.vsh`: ```v wip #!/usr/bin/env -S v run // The shebang above associates the file to V on Unix-like systems, // so it can be run just by specifying the path to the file // once it's made executable using `chmod +x`. // Remove if build/ exits, ignore any errors if it doesn't rmdir_all('build') or { } // Create build/, never fails as build/ does not exist mkdir('build') ? // Move *.v files to build/ result := exec('mv *.v build/') ? if result.exit_code != 0 { println(result.output) } // Similar to: // files := ls('.') ? // mut count := 0 // if files.len > 0 { // for file in files { // if file.ends_with('.v') { // mv(file, 'build/') or { // println('err: $err') // return // } // } // count++ // } // } // if count == 0 { // println('No files') // } ``` Now you can either compile this like a normal V program and get an executable you can deploy and run anywhere: `v deploy.vsh && ./deploy` Or just run it more like a traditional Bash script: `v run deploy.vsh` On Unix-like platforms, the file can be run directly after making it executable using `chmod +x`: `./deploy.vsh` ## Attributes V has several attributes that modify the behavior of functions and structs. An attribute is a compiler instruction specified inside `[]` right before a function/struct/enum declaration and applies only to the following declaration. ```v // Calling this function will result in a deprecation warning [deprecated] fn old_function() { } // It can also display a custom deprecation message [deprecated: 'use new_function() instead'] fn legacy_function() {} // This function's calls will be inlined. [inline] fn inlined_function() { } // The following struct must be allocated on the heap. Therefore, it can only be used as a // reference (`&Window`) or inside another reference (`&OuterStruct{ Window{...} }`). [heap] struct Window { } // V will not generate this function and all its calls if the provided flag is false. // To use a flag, use `v -d flag` [if debug] fn foo() { } fn bar() { foo() // will not be called if `-d debug` is not passed } // The memory pointed to by the pointer arguments of this function will not be // freed by the garbage collector (if in use) before the function returns [keep_args_alive] fn C.my_external_function(voidptr, int, voidptr) int // Calls to following function must be in unsafe{} blocks. // Note that the code in the body of `risky_business()` will still be // checked, unless you also wrap it in `unsafe {}` blocks. // This is usefull, when you want to have an `[unsafe]` function that // has checks before/after a certain unsafe operation, that will still // benefit from V's safety features. [unsafe] fn risky_business() { // code that will be checked, perhaps checking pre conditions unsafe { // code that *will not be* checked, like pointer arithmetic, // accessing union fields, calling other `[unsafe]` fns, etc... // Usually, it is a good idea to try minimizing code wrapped // in unsafe{} as much as possible. // See also [Memory-unsafe code](#memory-unsafe-code) } // code that will be checked, perhaps checking post conditions and/or // keeping invariants } // V's autofree engine will not take care of memory management in this function. // You will have the responsibility to free memory manually yourself in it. [manualfree] fn custom_allocations() { } // For C interop only, tells V that the following struct is defined with `typedef struct` in C [typedef] struct C.Foo { } // Used in Win32 API code when you need to pass callback function [windows_stdcall] fn C.DefWindowProc(hwnd int, msg int, lparam int, wparam int) // Windows only: // If a default graphics library is imported (ex. gg, ui), then the graphical window takes // priority and no console window is created, effectively disabling println() statements. // Use to explicity create console window. Valid before main() only. [console] fn main() { } ``` ## Goto V allows unconditionally jumping to a label with `goto`. The label name must be contained within the same function as the `goto` statement. A program may `goto` a label outside or deeper than the current scope. `goto` allows jumping past variable initialization or jumping back to code that accesses memory that has already been freed, so it requires `unsafe`. ```v ignore if x { // ... if y { unsafe { goto my_label } } // ... } my_label: ``` `goto` should be avoided, particularly when `for` can be used instead. [Labelled break/continue](#labelled-break--continue) can be used to break out of a nested loop, and those do not risk violating memory-safety. # Appendices ## Appendix I: Keywords V has 41 reserved keywords (3 are literals): ```v ignore as asm assert atomic break const continue defer else embed enum false fn for go goto if import in interface is lock match module mut none or pub return rlock select shared sizeof static struct true type typeof union unsafe __offsetof ``` See also [Types](#types). ## Appendix II: Operators This lists operators for [primitive types](#primitive-types) only. ```v ignore + sum integers, floats, strings - difference integers, floats * product integers, floats / quotient integers, floats % remainder integers ~ bitwise NOT integers & bitwise AND integers | bitwise OR integers ^ bitwise XOR integers ! logical NOT bools && logical AND bools || logical OR bools != logical XOR bools << left shift integer << unsigned integer >> right shift integer >> unsigned integer Precedence Operator 5 * / % << >> & 4 + - | ^ 3 == != < <= > >= 2 && 1 || Assignment Operators += -= *= /= %= &= |= ^= >>= <<= ```