doc: add more subheadings & tweaks (#5752)

pull/5958/head
Nick Treleaven 2020-07-23 17:55:54 +01:00 committed by GitHub
parent 582338ab79
commit 75aa92b907
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 29 additions and 33 deletions

View File

@ -22,21 +22,24 @@ you can do in V.
* [Hello world](#hello-world) * [Hello world](#hello-world)
* [Comments](#comments) * [Comments](#comments)
* [Functions](#functions) * [Functions](#functions)
* [Returning multiple values](#returning-multiple-values)
* [Symbol visibility](#symbol-visibility)
* [Variables](#variables) * [Variables](#variables)
* [Types](#types) * [Types](#types)
* [Primitive types](#primitive-types)
* [Strings](#strings) * [Strings](#strings)
* [Numbers](#numbers) * [Numbers](#numbers)
* [Arrays](#arrays) * [Arrays](#arrays)
* [Maps](#maps) * [Maps](#maps)
* [Module Imports](#module-imports) * [Module imports](#module-imports)
* [Statements & Expressions](#statements--expressions) * [Statements & expressions](#statements--expressions)
* [If](#if) * [If](#if)
* [In Operator](#in-operator) * [In operator](#in-operator)
* [For loop](#for-loop) * [For loop](#for-loop)
* [Match](#match) * [Match](#match)
* [Defer](#defer) * [Defer](#defer)
* [Structs](#structs) * [Structs](#structs)
* [Embedded structs](#embedded-structs)
* [Default field values](#default-field-values)
* [Short struct literal syntax](#short-struct-initialization-syntax) * [Short struct literal syntax](#short-struct-initialization-syntax)
* [Access modifiers](#access-modifiers) * [Access modifiers](#access-modifiers)
* [Methods](#methods) * [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 This is true for all declarations in V and eliminates the need for header files
or thinking about the order of files and declarations. or thinking about the order of files and declarations.
<p>&nbsp;</p> ### Returning multiple values
```v ```v
fn foo() (int, int) { fn foo() (int, int) {
@ -180,10 +183,7 @@ println(b) // 3
c, _ := foo() // ignore values using `_` c, _ := foo() // ignore values using `_`
``` ```
Functions can return multiple values. ## Symbol visibility
<p>&nbsp;</p>
```v ```v
pub fn public_function() { 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 allow other modules to use them, prepend `pub`. The same applies
to constants and types. to constants and types.
## Variables ## Variables
```v ```v
@ -220,9 +218,10 @@ the expression `T(v)` converts the value `v` to the
type `T`. type `T`.
Unlike most other languages, V only allows defining variables in functions. 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).
<p>&nbsp;</p> ### Mutable variables
```v ```v
mut age := 20 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. Try compiling the program above after removing `mut` from the first line.
### Initialization vs assignment
Note the (important) difference between `:=` and `=` Note the (important) difference between `:=` and `=`
`:=` is used for declaring and initializing, `=` is used for assigning. `:=` is used for declaring and initializing, `=` is used for assigning.
<p>&nbsp;</p>
```v ```v
fn main() { fn main() {
age = 21 age = 21
@ -250,8 +249,6 @@ fn main() {
This code will not compile, because the variable `age` is not declared. This code will not compile, because the variable `age` is not declared.
All variables need to be declared in V. All variables need to be declared in V.
<p>&nbsp;</p>
```v ```v
fn main() { fn main() {
age := 21 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 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). In production mode (enabled by passing the `-prod` flag to v `v -prod foo.v`) it will not compile at all (like in Go).
<p>&nbsp;</p>
```v ```v
fn main() { fn main() {
a := 10 a := 10
if true { 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) For information about creating a module, see [Modules](#modules)
### Importing a Module ### Importing a module
Modules can be imported using keyword `import`. Modules can be imported using keyword `import`.
@ -574,7 +570,7 @@ import crypto.sha256 { sum }
import time { Time } import time { Time }
``` ```
### Module Import Aliasing ### Module import aliasing
Any imported module name can be aliased using the `as` keyword: Any imported module name can be aliased using the `as` keyword:
@ -608,7 +604,7 @@ fn main() {
} }
``` ```
## Statements & Expressions ## Statements & expressions
### If ### If
@ -887,7 +883,7 @@ p = Point{10, 20}
assert p.x == 10 assert p.x == 10
``` ```
<p>&nbsp;</p> ### Heap structs
Structs are allocated on the stack. To allocate a struct on the heap Structs are allocated on the stack. To allocate a struct on the heap
and get a reference to it, use the `&` prefix: and get a reference to it, use the `&` prefix:
@ -898,10 +894,10 @@ p := &Point{10, 10}
println(p.x) 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. References are similar to Go pointers and C++ references.
<p>&nbsp;</p> ### Embedded structs
V doesn't allow subclassing, but it supports 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) button.widget.set_pos(x,y)
``` ```
<p>&nbsp;</p> ### Default field values
```v ```v
struct Foo { struct Foo {
@ -1047,10 +1043,8 @@ user2 := User{age: 20}
println(user2.can_register()) // "true" 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. 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. 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`. 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 ### Pure functions by default
V functions are pure by default, meaning that their return values are a function of their arguments only, 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, This is achieved by a lack of global variables and all function arguments being immutable by default,
even when [references](#references) are passed. even when [references](#references) are passed.
@ -2471,6 +2465,8 @@ See also [Types](#types).
## Appendix II: Operators ## Appendix II: Operators
This lists operators for [primitive types](#primitive-types) only.
```v ```v
+ sum integers, floats, strings + sum integers, floats, strings
- difference integers, floats - difference integers, floats