From 75aa92b907d65119aef623078e1a686fbada1675 Mon Sep 17 00:00:00 2001 From: Nick Treleaven Date: Thu, 23 Jul 2020 17:55:54 +0100 Subject: [PATCH] doc: add more subheadings & tweaks (#5752) --- doc/docs.md | 62 +++++++++++++++++++++++++---------------------------- 1 file changed, 29 insertions(+), 33 deletions(-) diff --git a/doc/docs.md b/doc/docs.md index 80bf4bc3df..b6b143972c 100644 --- a/doc/docs.md +++ b/doc/docs.md @@ -22,21 +22,24 @@ you can do in V. * [Hello world](#hello-world) * [Comments](#comments) * [Functions](#functions) + * [Returning multiple values](#returning-multiple-values) +* [Symbol visibility](#symbol-visibility) * [Variables](#variables) * [Types](#types) - * [Primitive types](#primitive-types) * [Strings](#strings) * [Numbers](#numbers) * [Arrays](#arrays) * [Maps](#maps) -* [Module Imports](#module-imports) -* [Statements & Expressions](#statements--expressions) +* [Module imports](#module-imports) +* [Statements & expressions](#statements--expressions) * [If](#if) - * [In Operator](#in-operator) + * [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) @@ -167,7 +170,7 @@ Functions can be used before their declaration: 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) { @@ -180,10 +183,7 @@ println(b) // 3 c, _ := foo() // ignore values using `_` ``` -Functions can return multiple values. - -

 

- +## Symbol visibility ```v pub fn public_function() { @@ -193,12 +193,10 @@ fn private_function() { } ``` -Like constants and types, functions are private (not exported) by default. +Functions are private (not exported) by default. To allow other modules to use them, prepend `pub`. The same applies to constants and types. - - ## Variables ```v @@ -220,9 +218,10 @@ 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. +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). -

 

+### Mutable variables ```v mut age := 20 @@ -236,11 +235,11 @@ immutable by default. To be able to change the value of the variable, you have t 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 fn main() { age = 21 @@ -250,8 +249,6 @@ fn main() { 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 @@ -263,14 +260,13 @@ fn main() { 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 fn main() { a := 10 if true { - a := 20 + a := 20 // error: shadowed variable } + // warning: unused variable `a` } ``` @@ -548,11 +544,11 @@ numbers := { } ``` -## Module Imports +## Module imports For information about creating a module, see [Modules](#modules) -### Importing a Module +### Importing a module Modules can be imported using keyword `import`. @@ -574,7 +570,7 @@ import crypto.sha256 { sum } import time { Time } ``` -### Module Import Aliasing +### Module import aliasing Any imported module name can be aliased using the `as` keyword: @@ -608,7 +604,7 @@ fn main() { } ``` -## Statements & Expressions +## Statements & expressions ### If @@ -887,7 +883,7 @@ 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: @@ -898,10 +894,10 @@ p := &Point{10, 10} println(p.x) ``` -The type of `p` is `&Point`. It's a reference to `Point`. +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: @@ -919,7 +915,7 @@ button.set_pos(x, y) button.widget.set_pos(x,y) ``` -

 

+### Default field values ```v struct Foo { @@ -1047,10 +1043,8 @@ user2 := User{age: 20} println(user2.can_register()) // "true" ``` -V doesn't have classes. But you can define methods on types. - +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. In this example, the `can_register` method has a receiver of type `User` named `u`. @@ -1062,7 +1056,7 @@ but a short, preferably one letter long, name. ### 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. +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. @@ -2471,6 +2465,8 @@ See also [Types](#types). ## Appendix II: Operators +This lists operators for [primitive types](#primitive-types) only. + ```v + sum integers, floats, strings - difference integers, floats