mirror/v
1
0
Fork 0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00
Code Issues Projects Releases Wiki Activity

docs: unify format of notes (#17294)

Browse Source
This commit is contained in:
Makhnev Petr 2023-02-13 12:29:02 +04:00 committed by GitHub
parent e7fcf66095
commit c8c70de87d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 422 additions and 252 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
CONTRIBUTING.md
View File

@ -1,7 +1,7 @@
## Code Structure ## Code Structure
I tried to make the code of the compiler and vlib as simple and readable as I tried to make the code of the compiler and vlib as simple and readable as
possible. One of V's goals is to be open to developers with different levels possible. One of V's goals is to be open to developers with different levels
of experience in compiler development. Compilers don't need to be black boxes of experience in compiler development. Compilers don't need to be black boxes
full of magic that only few people understand. full of magic that only few people understand.
@ -24,55 +24,55 @@ The architecture of the compiler is very simple and has three distinct steps:
Parse/generate AST (`v.parser`) => Check types (`v.checker`) Parse/generate AST (`v.parser`) => Check types (`v.checker`)
=> Generate C/JavaScript/machine code (`v.gen`) => Generate C/JavaScript/machine code (`v.gen`)
The main files are: The main files are:
1. `cmd/v/v.v` The entry point. 1. `cmd/v/v.v` The entry point.
- V figures out the build mode. - V figures out the build mode.
- Constructs the compiler object (`struct V`). - Constructs the compiler object (`struct V`).
- Creates a list of .v files that need to be parsed. - Creates a list of .v files that need to be parsed.
- Creates a parser object for each file and runs `parse()` on them. - Creates a parser object for each file and runs `parse()` on them.
- The correct backend is called (C, JS, native), and a binary is compiled. - The correct backend is called (C, JS, native), and a binary is compiled.
2. `vlib/v/scanner` The scanner's job is to parse a list of characters and convert 2. `vlib/v/scanner` The scanner's job is to parse a list of characters and convert
them to tokens. them to tokens.
3. `vlib/v/token` This is simply a list of all tokens, their string values, and a 3. `vlib/v/token` This is simply a list of all tokens, their string values, and a
couple of helper functions. couple of helper functions.
4. `vlib/v/parser` The parser. It converts a list of tokens into an AST. 4. `vlib/v/parser` The parser. It converts a list of tokens into an AST.
In V, objects can be used before declaration, so unknown types are marked as In V, objects can be used before declaration, so unknown types are marked as
unresolved. They are resolved later in the type checker. unresolved. They are resolved later in the type checker.
5. `vlib/v/table` V creates one table object that is shared by all parsers. It 5. `vlib/v/table` V creates one table object that is shared by all parsers. It
contains all types, consts, and functions, as well as several helpers to search contains all types, consts, and functions, as well as several helpers to search
for objects by name, register new objects, modify types' fields, etc. for objects by name, register new objects, modify types' fields, etc.
6. `vlib/v/checker` Type checker and resolver. It processes the AST and makes sure 6. `vlib/v/checker` Type checker and resolver. It processes the AST and makes sure
the types are correct. Unresolved types are resolved, type information is added the types are correct. Unresolved types are resolved, type information is added
to the AST. to the AST.
7. `vlib/v/gen/c` C backend. It simply walks the AST and generates C code that can be 7. `vlib/v/gen/c` C backend. It simply walks the AST and generates C code that can be
compiled with Clang, GCC, Visual Studio, and TCC. compiled with Clang, GCC, Visual Studio, and TCC.
8. `vlib/v/gen/js` JavaScript backend. It simply walks the AST and generates JS code that can be 8. `vlib/v/gen/js` JavaScript backend. It simply walks the AST and generates JS code that can be
executed on the browser or in NodeJS/Deno. executed on the browser or in NodeJS/Deno.
9. `vlib/v/gen/c/json.v` defines the json code generation. This file will be removed once V 9. `vlib/v/gen/c/json.v` defines the json code generation. This file will be removed once V
supports comptime code generation, and it will be possible to do this using the supports comptime code generation, and it will be possible to do this using the
language's tools. language's tools.
10. `vlib/v/gen/native` is the directory with all the machine code generation logic. It 10. `vlib/v/gen/native` is the directory with all the machine code generation logic. It
defines a set of functions that translate assembly instructions to machine code defines a set of functions that translate assembly instructions to machine code
and build the binary from scratch byte by byte. It manually builds all headers, and build the binary from scratch byte by byte. It manually builds all headers,
segments, sections, symtable, relocations, etc. Right now it only has basic segments, sections, symtable, relocations, etc. Right now it only has basic
support of the native platform (ELF, MACHO format). support of the native platform (ELF, MACHO format).
The rest of the directories are vlib modules: `builtin/` (strings, arrays, The rest of the directories are vlib modules: `builtin/` (strings, arrays,
maps), `time/`, `os/`, etc. Their documentation is pretty clear. maps), `time/`, `os/`, etc. Their documentation is pretty clear.
## Example Workflow for Contributing ## Example Workflow for Contributing
(provided by [@spytheman](https://github.com/spytheman)) (provided by [@spytheman](https://github.com/spytheman))
(If you don't already have a GitHub account, please create one. Your GitHub (If you don't already have a GitHub account, please create one. Your GitHub
@ -80,13 +80,14 @@ username will be referred to later as 'YOUR_GITHUB_USERNAME'. Change it
accordingly in the steps below.) accordingly in the steps below.)
1. Fork https://github.com/vlang/v using GitHub's interface to your own account. 1. Fork https://github.com/vlang/v using GitHub's interface to your own account.
Let's say that the forked repository is at Let's say that the forked repository is at
`https://github.com/YOUR_GITHUB_USERNAME/v` . `https://github.com/YOUR_GITHUB_USERNAME/v` .
2. Clone the main v repository https://github.com/vlang/v to a local folder on 2. Clone the main v repository https://github.com/vlang/v to a local folder on
your computer, say named nv/ (`git clone https://github.com/vlang/v nv`) your computer, say named nv/ (`git clone https://github.com/vlang/v nv`)
3. `cd nv` 3. `cd nv`
4. `git remote add pullrequest https://github.com/YOUR_GITHUB_USERNAME/v` 4. `git remote add pullrequest https://github.com/YOUR_GITHUB_USERNAME/v`
NB: the remote named `pullrequest` should point to YOUR own forked repo, not the
Note: The remote named `pullrequest` should point to YOUR own forked repo, not the
main v repository! After this, your local cloned repository is prepared for main v repository! After this, your local cloned repository is prepared for
making pullrequests, and you can just do normal git operations such as: making pullrequests, and you can just do normal git operations such as:
`git pull` `git status` and so on. `git pull` `git status` and so on.
@ -94,7 +95,7 @@ making pullrequests, and you can just do normal git operations such as:
5. When finished with a feature/bugfix/change, you can: 5. When finished with a feature/bugfix/change, you can:
`git checkout -b fix_alabala` `git checkout -b fix_alabala`
- Don't forget to keep formatting standards, run `v fmt -w YOUR_MODIFIED_FILES` before committing - Don't forget to keep formatting standards, run `v fmt -w YOUR_MODIFIED_FILES` before committing
6. `git push pullrequest` # (NOTE: the `pullrequest` remote was setup on step 4) 6. `git push pullrequest` Note: The `pullrequest` remote was setup on step 4
7. On GitHub's web interface, go to: https://github.com/vlang/v/pulls 7. On GitHub's web interface, go to: https://github.com/vlang/v/pulls
Here the UI shows a dialog with a button to make a new pull request based on Here the UI shows a dialog with a button to make a new pull request based on
@ -102,16 +103,16 @@ making pullrequests, and you can just do normal git operations such as:
(Example dialog: https://url4e.com/gyazo/images/364edc04.png) (Example dialog: https://url4e.com/gyazo/images/364edc04.png)
8. After making your pullrequest (aka, PR), you can continue to work on the 8. After making your pullrequest (aka, PR), you can continue to work on the
branch `fix_alabala` ... just do again `git push pullrequest` when you have more branch `fix_alabala` ... just do again `git push pullrequest` when you have more
commits. commits.
9. If there are merge conflicts, or a branch lags too much behind V's master, 9. If there are merge conflicts, or a branch lags too much behind V's master,
you can do the following: you can do the following:
1. `git pull --rebase origin master` # solve conflicts and do 1. `git pull --rebase origin master` # solve conflicts and do
`git rebase --continue` `git rebase --continue`
2. `git push pullrequest -f` # this will overwrite your current remote branch 2. `git push pullrequest -f` # this will overwrite your current remote branch
with the updated version of your changes. with the updated version of your changes.
The point of doing the above steps, is to never directly push to the main V The point of doing the above steps, is to never directly push to the main V
repository, *only to your own fork*. Since your local `master` branch tracks the repository, *only to your own fork*. Since your local `master` branch tracks the
@ -120,7 +121,8 @@ main V repository's master, then `git checkout master`, as well as
(these are actually used by `v up`) and git can always do it cleanly. (these are actually used by `v up`) and git can always do it cleanly.
Git is very flexible, so there are other ways to accomplish the same thing. Git is very flexible, so there are other ways to accomplish the same thing.
See the [GitHub flow](https://guides.github.com/introduction/git-handbook/#github), for more information. See the [GitHub flow](https://guides.github.com/introduction/git-handbook/#github), for more
information.
## Using Github's hub CLI tool ## Using Github's hub CLI tool
@ -129,9 +131,11 @@ You can download the `hub` tool from https://hub.github.com/ . Using
to make PRs. Most remote operations can be done through the `hub` CLI to make PRs. Most remote operations can be done through the `hub` CLI
command. command.
NB: You still need to have a GitHub account. > **Note**
> You still need to have a GitHub account.
### Preparation: ### Preparation:
(steps 1..3 need to be done just *once*): (steps 1..3 need to be done just *once*):
1. `hub clone vlang/v my_v` 1. `hub clone vlang/v my_v`
@ -139,13 +143,14 @@ NB: You still need to have a GitHub account.
3. `hub fork --remote-name pullrequest` 3. `hub fork --remote-name pullrequest`
4. `git checkout -b my_cool_feature` # Step 4 is better done *once per each new 4. `git checkout -b my_cool_feature` # Step 4 is better done *once per each new
feature/bugfix* that you make. feature/bugfix* that you make.
### Improve V by making commits: ### Improve V by making commits:
5. `git commit -am "math: add a new function copysign"` 5. `git commit -am "math: add a new function copysign"`
### Testing your commits locally: ### Testing your commits locally:
You can test locally whether your changes have not broken something by You can test locally whether your changes have not broken something by
running: `v test-all`. See `TESTS.md` for more details. running: `v test-all`. See `TESTS.md` for more details.
@ -154,6 +159,7 @@ running: `v test-all`. See `TESTS.md` for more details.
6. `git push pullrequest` 6. `git push pullrequest`
### Making a PR with `hub`: ### Making a PR with `hub`:
(so that your changes can be merged to the main V repository) (so that your changes can be merged to the main V repository)
7. `hub pull-request` 7. `hub pull-request`
@ -163,6 +169,7 @@ Optionally, you can track the status of your PR CI tests with:
8. `hub ci-status --verbose` 8. `hub ci-status --verbose`
### Fixing failing tests: ### Fixing failing tests:
If everything is OK, after 5-10 minutes, the CI tests should pass for If everything is OK, after 5-10 minutes, the CI tests should pass for
all platforms. If not, visit the URLs for the failing CI jobs, see all platforms. If not, visit the URLs for the failing CI jobs, see
which tests have failed and then fix them by making more changes. Just use which tests have failed and then fix them by making more changes. Just use
@ -185,22 +192,22 @@ not the program, so do for example: `v -d time_parsing cmd/v` or
Some flags can make the compiler very verbose, so it is recommended Some flags can make the compiler very verbose, so it is recommended
to create a copy of the compiler rather than replacing it with `v self`. to create a copy of the compiler rather than replacing it with `v self`.
| Flag | Usage | | Flag | Usage |
|------|-------| |-----------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `debugscanner` | Prints debug information during the scanning phase | | `debugscanner` | Prints debug information during the scanning phase |
| `debug_codegen` | Prints automatically generated V code during the scanning phase | | `debug_codegen` | Prints automatically generated V code during the scanning phase |
| `debug_interface_table` | Prints generated interfaces during C generation | | `debug_interface_table` | Prints generated interfaces during C generation |
| `debug_interface_type_implements` | Prints debug information when checking that a type implements in interface | | `debug_interface_type_implements` | Prints debug information when checking that a type implements in interface |
| `print_vweb_template_expansions` | Prints vweb compiled HTML files | | `print_vweb_template_expansions` | Prints vweb compiled HTML files |
| `time_checking` | Prints the time spent checking files and other related information | | `time_checking` | Prints the time spent checking files and other related information |
| `time_parsing` | Prints the time spent parsing files and other related information | | `time_parsing` | Prints the time spent parsing files and other related information |
| `trace_autofree` | Prints details about how/when -autofree puts free() calls | | `trace_autofree` | Prints details about how/when -autofree puts free() calls |
| `trace_autostr` | Prints details about `.str()` method auto-generated by the compiler during C generation | | `trace_autostr` | Prints details about `.str()` method auto-generated by the compiler during C generation |
| `trace_ccoptions` | Prints options passed down to the C compiler | | `trace_ccoptions` | Prints options passed down to the C compiler |
| `trace_checker` | Prints details about the statements being checked | | `trace_checker` | Prints details about the statements being checked |
| `trace_gen` | Prints strings written to the generated C file. Beware, this flag is very verbose | | `trace_gen` | Prints strings written to the generated C file. Beware, this flag is very verbose |
| `trace_parser` | Prints details about parsed statements and expressions | | `trace_parser` | Prints details about parsed statements and expressions |
| `trace_thirdparty_obj_files` | Prints details about built thirdparty obj files | | `trace_thirdparty_obj_files` | Prints details about built thirdparty obj files |
| `trace_usecache` | Prints details when -usecache is used | | `trace_usecache` | Prints details when -usecache is used |
| `trace_embed_file` | Prints details when $embed_file is used | | `trace_embed_file` | Prints details when $embed_file is used |
| `embed_only_metadata` | Embed only the metadata for the file(s) with `$embed_file('somefile')`; faster; for development, *not* distribution | | `embed_only_metadata` | Embed only the metadata for the file(s) with `$embed_file('somefile')`; faster; for development, *not* distribution |

89
README.md
View File

@ -19,9 +19,11 @@
</div> </div>
## Key Features of V ## Key Features of V
- Simplicity: the language can be learned in a weekend - Simplicity: the language can be learned in a weekend
- Fast compilation: ≈110k loc/s with a Clang backend, - Fast compilation: ≈110k loc/s with a Clang backend,
≈500k loc/s with native and tcc backends *(Intel i5-7500, SSD, no optimization)* ([demo video](https://www.youtube.com/watch?v=pvP6wmcl_Sc)) ≈500k loc/s with native and tcc backends *(Intel i5-7500, SSD, no
optimization)* ([demo video](https://www.youtube.com/watch?v=pvP6wmcl_Sc))
- Easy to develop: V compiles itself in less than a second - Easy to develop: V compiles itself in less than a second
- Performance: as fast as C (V's main backend compiles to human-readable C) - Performance: as fast as C (V's main backend compiles to human-readable C)
- Safety: no null, no globals, no undefined behavior, immutability by default - Safety: no null, no globals, no undefined behavior, immutability by default
@ -38,6 +40,7 @@
- Great for writing low-level software ([Vinix OS](https://github.com/vlang/vinix)) - Great for writing low-level software ([Vinix OS](https://github.com/vlang/vinix))
## Stability guarantee and future changes ## Stability guarantee and future changes
Despite being at an early development stage, the V language is relatively stable and has Despite being at an early development stage, the V language is relatively stable and has
backwards compatibility guarantee, meaning that the code you write today is guaranteed backwards compatibility guarantee, meaning that the code you write today is guaranteed
to work a month, a year, or five years from now. to work a month, a year, or five years from now.
@ -58,10 +61,12 @@ language, very similar to the way it is right now.
--> **_(this is the preferred method)_** --> **_(this is the preferred method)_**
### Linux, macOS, Windows, *BSD, Solaris, WSL, etc. ### Linux, macOS, Windows, *BSD, Solaris, WSL, etc.
Usually installing V is quite simple if you have an environment that already has a Usually installing V is quite simple if you have an environment that already has a
functional `git` installation. functional `git` installation.
To get started, simply try to execute the following in your terminal/shell: To get started, simply try to execute the following in your terminal/shell:
```bash ```bash
git clone https://github.com/vlang/v git clone https://github.com/vlang/v
cd v cd v
@ -77,7 +82,8 @@ That should be it and you should find your V executable at `[path to V repo]/v`.
Now you can try `./v run examples/hello_world.v` (or `v run examples/hello_world.v` in cmd shell). Now you can try `./v run examples/hello_world.v` (or `v run examples/hello_world.v` in cmd shell).
* *Trouble? Please see the note above and link to * *Trouble? Please see the note above and link to
[Installation Issues](https://github.com/vlang/v/discussions/categories/installation-issues) for help.* [Installation Issues](https://github.com/vlang/v/discussions/categories/installation-issues)
for help.*
V is constantly being updated. To update V, simply run: V is constantly being updated. To update V, simply run:
@ -85,18 +91,21 @@ V is constantly being updated. To update V, simply run:
v up v up
``` ```
* *(* ***NOTE:*** *If you run into any trouble, or you have a different operating > **Note**
system or Linux distribution that doesn't install or work immediately, please see > If you run into any trouble, or you have a different operating
[Installation Issues](https://github.com/vlang/v/discussions/categories/installation-issues) > system or Linux distribution that doesn't install or work immediately, please see
and search for your OS and problem. If you can't find your problem, please add it to an > [Installation Issues](https://github.com/vlang/v/discussions/categories/installation-issues)
existing discussion if one exists for your OS, or create a new one if a main discussion > and search for your OS and problem.
doesn't yet exist for your OS.)* >
> If you can't find your problem, please add it to an existing discussion if one exists for
> your OS, or create a new one if a main discussion doesn't yet exist for your OS.
### C compiler ### C compiler
The [Tiny C Compiler (tcc)](https://repo.or.cz/w/tinycc.git) is downloaded for you by `make` if The [Tiny C Compiler (tcc)](https://repo.or.cz/w/tinycc.git) is downloaded for you by `make` if
there is a compatible version for your system, and installed under the V `thirdparty` directory. there is a compatible version for your system, and installed under the V `thirdparty` directory.
This compiler is very fast, but does almost no optimizations. It is best for development builds. This compiler is very fast, but does almost no optimizations. It is best for development builds.
For production builds (using the `-prod` option to V), it's recommended to use clang, gcc, or For production builds (using the `-prod` option to V), it's recommended to use clang, gcc, or
Microsoft Visual C++. If you are doing development, you most likely already have one of those Microsoft Visual C++. If you are doing development, you most likely already have one of those
@ -109,9 +118,11 @@ Otherwise, follow these instructions:
- [Installing a C compiler on Windows](https://github.com/vlang/v/wiki/Installing-a-C-compiler-on-Windows) - [Installing a C compiler on Windows](https://github.com/vlang/v/wiki/Installing-a-C-compiler-on-Windows)
### Symlinking ### Symlinking
NB: it is *highly recommended*, that you put V on your PATH. That saves
you the effort to type in the full path to your v executable every time. > **Note**
V provides a convenience `v symlink` command to do that more easily. > It is *highly recommended*, that you put V on your PATH. That saves
> you the effort to type in the full path to your v executable every time.
> V provides a convenience `v symlink` command to do that more easily.
On Unix systems, it creates a `/usr/local/bin/v` symlink to your On Unix systems, it creates a `/usr/local/bin/v` symlink to your
executable. To do that, run: executable. To do that, run:
@ -128,17 +139,19 @@ type:
```bat ```bat
v symlink v symlink
``` ```
(or `./v symlink` in PowerShell) (or `./v symlink` in PowerShell)
That will make V available everywhere, by adding it to your PATH. Please restart your That will make V available everywhere, by adding it to your PATH. Please restart your
shell/editor after that, so that it can pick up the new PATH variable. shell/editor after that, so that it can pick up the new PATH variable.
NB: there is no need to run `v symlink` more than once - v will still be available, even after > **Note**
`v up`, restarts, and so on. You only need to run it again if you decide to move the V repo > There is no need to run `v symlink` more than once - v will still be available, even after
folder somewhere else. > `v up`, restarts, and so on. You only need to run it again if you decide to move the V repo
> folder somewhere else.
### Void Linux ### Void Linux
<details><summary>Expand Void Linux instructions</summary> <details><summary>Expand Void Linux instructions</summary>
```bash ```bash
@ -148,10 +161,11 @@ $ git clone https://github.com/vlang/v
$ cd v $ cd v
$ make $ make
``` ```
</details> </details>
### Docker ### Docker
<details><summary>Expand Docker instructions</summary> <details><summary>Expand Docker instructions</summary>
```bash ```bash
@ -160,19 +174,24 @@ cd v
docker build -t vlang . docker build -t vlang .
docker run --rm -it vlang:latest docker run --rm -it vlang:latest
``` ```
### Docker with Alpine/musl ### Docker with Alpine/musl
```bash ```bash
git clone https://github.com/vlang/v git clone https://github.com/vlang/v
cd v cd v
docker build -t vlang --file=Dockerfile.alpine . docker build -t vlang --file=Dockerfile.alpine .
docker run --rm -it vlang:latest docker run --rm -it vlang:latest
``` ```
</details> </details>
### Termux/Android ### Termux/Android
On Termux, V needs some packages preinstalled - a working C compiler, also `libexecinfo`, On Termux, V needs some packages preinstalled - a working C compiler, also `libexecinfo`,
`libgc` and `libgc-static`. After installing them, you can use the same script, like on `libgc` and `libgc-static`. After installing them, you can use the same script, like on
Linux/macos: Linux/macos:
```bash ```bash
pkg install clang libexecinfo libgc libgc-static make git pkg install clang libexecinfo libgc libgc-static make git
git clone https://github.com/vlang/v git clone https://github.com/vlang/v
@ -181,7 +200,9 @@ make
``` ```
## Testing and running the examples ## Testing and running the examples
Make sure V can compile itself: Make sure V can compile itself:
```bash ```bash
$ v self $ v self
$ v $ v
@ -192,6 +213,7 @@ Use Ctrl-C or `exit` to exit
hello world hello world
>>> >>>
``` ```
```bash ```bash
cd examples cd examples
v hello_world.v && ./hello_world # or simply v hello_world.v && ./hello_world # or simply
@ -201,9 +223,10 @@ v run word_counter/word_counter.v word_counter/cinderella.txt
v run news_fetcher.v v run news_fetcher.v
v run tetris/tetris.v v run tetris/tetris.v
``` ```
<img src='https://raw.githubusercontent.com/vlang/v/master/examples/tetris/screenshot.png' width=300 alt='tetris screenshot'> <img src='https://raw.githubusercontent.com/vlang/v/master/examples/tetris/screenshot.png' width=300 alt='tetris screenshot'>
NB: In order to build Tetris or 2048 (or anything else using `sokol` or `gg` graphics modules), In order to build Tetris or 2048 (or anything else using `sokol` or `gg` graphics modules),
you will need additional development libraries for your system. you will need additional development libraries for your system.
For some Linux distros (Debian/Ubuntu based), you need to run this: For some Linux distros (Debian/Ubuntu based), you need to run this:
`sudo apt install libxi-dev libxcursor-dev`. `sudo apt install libxi-dev libxcursor-dev`.
@ -213,8 +236,9 @@ For NixOS, add these packages to your `environment.systemPackages`:
`xorg.libX11.dev xorg.libXcursor.dev xorg.libXi.dev libGL.dev` `xorg.libX11.dev xorg.libXcursor.dev xorg.libXi.dev libGL.dev`
## V net.http, net.websocket, `v install` ## V net.http, net.websocket, `v install`
The net.http module, the net.websocket module, and the `v install` command may all use SSL. The net.http module, the net.websocket module, and the `v install` command may all use SSL.
V comes with a version of mbedtls, which should work on all systems. If you find a need to V comes with a version of mbedtls, which should work on all systems. If you find a need to
use OpenSSL instead, you will need to make sure that it is installed on your system, then use OpenSSL instead, you will need to make sure that it is installed on your system, then
use the `-d use_openssl` switch when you compile. use the `-d use_openssl` switch when you compile.
@ -234,13 +258,15 @@ Fedora:
sudo dnf install openssl-devel sudo dnf install openssl-devel
``` ```
On Windows, OpenSSL is simply hard to get working correctly. The instructions On Windows, OpenSSL is simply hard to get working correctly. The instructions
[here](https://tecadmin.net/install-openssl-on-windows/) may (or may not) help. [here](https://tecadmin.net/install-openssl-on-windows/) may (or may not) help.
## V sync ## V sync
V's `sync` module and channel implementation uses libatomic. V's `sync` module and channel implementation uses libatomic.
It is most likely already installed on your system, but if not, It is most likely already installed on your system, but if not,
you can install it, by doing the following: you can install it, by doing the following:
```bash ```bash
MacOS: already installed MacOS: already installed
@ -252,6 +278,7 @@ sudo dnf install libatomic-static
``` ```
## V UI ## V UI
<a href="https://github.com/vlang/ui"> <a href="https://github.com/vlang/ui">
<img src='https://raw.githubusercontent.com/vlang/ui/master/examples/screenshot.png' width=712 alt='V UI example screenshot'> <img src='https://raw.githubusercontent.com/vlang/ui/master/examples/screenshot.png' width=712 alt='V UI example screenshot'>
</a> </a>
@ -280,15 +307,20 @@ Hello from V.js
--> -->
## Android graphical apps ## Android graphical apps
With V's `vab` tool, building V UI and graphical apps for Android can become as easy as: With V's `vab` tool, building V UI and graphical apps for Android can become as easy as:
``` ```
./vab /path/to/v/examples/2048 ./vab /path/to/v/examples/2048
``` ```
[https://github.com/vlang/vab](https://github.com/vlang/vab). [https://github.com/vlang/vab](https://github.com/vlang/vab).
<img src="https://user-images.githubusercontent.com/768942/107622846-c13f3900-6c58-11eb-8a66-55db12979b73.png" alt="vab examples screenshot"> <img src="https://user-images.githubusercontent.com/768942/107622846-c13f3900-6c58-11eb-8a66-55db12979b73.png" alt="vab examples screenshot">
## Developing web applications ## Developing web applications
Check out the [Building a simple web blog](https://github.com/vlang/v/blob/master/tutorials/building_a_simple_web_blog_with_vweb/README.md)
Check out the
[Building a simple web blog](https://github.com/vlang/v/blob/master/tutorials/building_a_simple_web_blog_with_vweb/README.md)
tutorial and Gitly, a light and fast alternative to GitHub/GitLab: tutorial and Gitly, a light and fast alternative to GitHub/GitLab:
https://github.com/vlang/gitly https://github.com/vlang/gitly
@ -296,6 +328,7 @@ https://github.com/vlang/gitly
<img src="https://user-images.githubusercontent.com/687996/85933714-b195fe80-b8da-11ea-9ddd-09cadc2103e4.png" alt="gitly screenshot"> <img src="https://user-images.githubusercontent.com/687996/85933714-b195fe80-b8da-11ea-9ddd-09cadc2103e4.png" alt="gitly screenshot">
## Vinix, an OS/kernel written in V ## Vinix, an OS/kernel written in V
V is great for writing low-level software like drivers and kernels. V is great for writing low-level software like drivers and kernels.
Vinix is an OS/kernel that already runs bash, GCC, V, and nano. Vinix is an OS/kernel that already runs bash, GCC, V, and nano.
@ -305,10 +338,20 @@ https://github.com/vlang/vinix
<img src="https://github.com/vlang/vinix/blob/main/screenshot1.png?raw=true" alt="vinix screenshot 2"> <img src="https://github.com/vlang/vinix/blob/main/screenshot1.png?raw=true" alt="vinix screenshot 2">
## Acknowledgement ## Acknowledgement
V thanks Fabrice Bellard for his original work on the [TCC - Tiny C Compiler](https://bellard.org/tcc/). Note the TCC website is old; the current TCC repository can be found [here](https://repo.or.cz/w/tinycc.git). V utilizes pre-built TCC binaries located at [https://github.com/vlang/tccbin/](https://github.com/vlang/tccbin/).
V thanks Fabrice Bellard for his original work on the
[TCC - Tiny C Compiler](https://bellard.org/tcc/).
Note the TCC website is old; the current TCC repository can be found
[here](https://repo.or.cz/w/tinycc.git).
V utilizes pre-built TCC binaries located at
[https://github.com/vlang/tccbin/](https://github.com/vlang/tccbin/).
## Troubleshooting ## Troubleshooting
Please see the [Troubleshooting](https://github.com/vlang/v/wiki/Troubleshooting) section on our [wiki page](https://github.com/vlang/v/wiki)
Please see the
[Troubleshooting](https://github.com/vlang/v/wiki/Troubleshooting)
section on our
[wiki page](https://github.com/vlang/v/wiki)
[WorkflowBadge]: https://github.com/vlang/v/workflows/CI/badge.svg [WorkflowBadge]: https://github.com/vlang/v/workflows/CI/badge.svg
[DiscordBadge]: https://img.shields.io/discord/592103645835821068?label=Discord&logo=discord&logoColor=white [DiscordBadge]: https://img.shields.io/discord/592103645835821068?label=Discord&logo=discord&logoColor=white

1
ROADMAP.md
View File

@ -1,4 +1,5 @@
## [Version 0.4] ## [Version 0.4]
- [ ] [Coroutines](https://github.com/vlang/v/discussions/11582) - [ ] [Coroutines](https://github.com/vlang/v/discussions/11582)
- [ ] [Thread safe maps](https://github.com/vlang/v/discussions/11729) - [ ] [Thread safe maps](https://github.com/vlang/v/discussions/11729)
- [ ] Parallel parser - [ ] Parallel parser

35
TESTS.md
View File

@ -5,7 +5,7 @@ and before submitting PRs.
Tip: use `v -cc tcc` when compiling tests, because TCC is much faster, Tip: use `v -cc tcc` when compiling tests, because TCC is much faster,
compared to most other C compilers like clang/gcc/msvc. Most test commands compared to most other C compilers like clang/gcc/msvc. Most test commands
will use the V compiler and the V tools many times, potentially will use the V compiler and the V tools many times, potentially
hundreds/thousands of times. hundreds/thousands of times.
## `v test-all` ## `v test-all`
@ -14,6 +14,7 @@ Test and build *everything*. Usefull to verify *locally*, that the CI will
most likely pass. Slowest, but most comprehensive. most likely pass. Slowest, but most comprehensive.
It works, by running these in succession: It works, by running these in succession:
* `v test-cleancode` * `v test-cleancode`
* `v test-self` * `v test-self`
* `v test-fmt` * `v test-fmt`
@ -23,10 +24,12 @@ It works, by running these in succession:
* `v install nedpals.args` * `v install nedpals.args`
# Details: # Details:
In the `v` repo there are many tests. The main types are: In the `v` repo there are many tests. The main types are:
## `_test.v` tests - these are the normal V test files. ## `_test.v` tests - these are the normal V test files.
All `test_` functions in these files, will be ran automatically by
All `test_` functions in these files, will be ran automatically by
V's test framework. V's test framework.
NB 1: You can run test files one by one, with: NB 1: You can run test files one by one, with:
@ -44,7 +47,6 @@ recursively.
`v -stats test folder` - same, but will also produce timing reports `v -stats test folder` - same, but will also produce timing reports
about how fast each test_ function in each _test.v file ran. about how fast each test_ function in each _test.v file ran.
## `v test vlib/v/tests`: ## `v test vlib/v/tests`:
This folder contains _test.v files, testing the different features of the V This folder contains _test.v files, testing the different features of the V
@ -58,8 +60,9 @@ matches an expected .out file. You can also check for code that does panic
using this test runner - just paste the start of the `panic()` output in the using this test runner - just paste the start of the `panic()` output in the
corresponding .out file. corresponding .out file.
NB: these tests, expect to find a pair of `.vv` and `.out` files, in the folder: > **Note**
vlib/v/slow_tests/inout > These tests, expect to find a pair of `.vv` and `.out` files, in the folder:
> vlib/v/slow_tests/inout
The test runner will run each `.vv` file, and will check that its output, matches The test runner will run each `.vv` file, and will check that its output, matches
the contents of the `.out` file with the same base name. This is particularly useful the contents of the `.out` file with the same base name. This is particularly useful
@ -78,13 +81,16 @@ lines, *should* be present *at least once* in the output, when the .vv
file is compiled with `-o -` . file is compiled with `-o -` .
## `v vlib/v/slow_tests/run_project_folders_test.v` ## `v vlib/v/slow_tests/run_project_folders_test.v`
This *test runner*, checks whether whole project folders, can be compiled, and run. This *test runner*, checks whether whole project folders, can be compiled, and run.
NB: Each project in these folders, should finish with an exit code of 0, > **Note**
and it should output `OK` as its last stdout line. > Each project in these folders, should finish with an exit code of 0,
> and it should output `OK` as its last stdout line.
## `v vlib/v/tests/known_errors/known_errors_test.v` ## `v vlib/v/tests/known_errors/known_errors_test.v`
This *test runner*, checks whether a known program, that was expected to compile,
This *test runner*, checks whether a known program, that was expected to compile,
but did NOT, due to a buggy checker, parser or cgen, continues to fail. but did NOT, due to a buggy checker, parser or cgen, continues to fail.
The negative programs are collected in the `vlib/v/tests/known_errors/testdata/` folder. The negative programs are collected in the `vlib/v/tests/known_errors/testdata/` folder.
Each of them should FAIL to compile, due to a known/confirmed compiler bug/limitation. Each of them should FAIL to compile, due to a known/confirmed compiler bug/limitation.
@ -96,7 +102,6 @@ change/improvement. For example, code that triggers generating invalid C code ca
and later when a bug is fixed, can be moved to a proper _test.v or .vv/.out pair, outside of and later when a bug is fixed, can be moved to a proper _test.v or .vv/.out pair, outside of
the `vlib/v/tests/known_errors/testdata/` folder. the `vlib/v/tests/known_errors/testdata/` folder.
## Test building of actual V programs (examples, tools, V itself) ## Test building of actual V programs (examples, tools, V itself)
* `v build-tools` * `v build-tools`
@ -147,21 +152,23 @@ Run `vlib` module tests, *including* the compiler tests.
## `v vlib/v/compiler_errors_test.v` ## `v vlib/v/compiler_errors_test.v`
This runs tests for: This runs tests for:
* `vlib/v/scanner/tests/*.vv` * `vlib/v/scanner/tests/*.vv`
* `vlib/v/checker/tests/*.vv` * `vlib/v/checker/tests/*.vv`
* `vlib/v/parser/tests/*.vv` * `vlib/v/parser/tests/*.vv`
NB: there are special folders, that compiler_errors_test.v will try to > **Note**
run/compile with specific options: > There are special folders, that compiler_errors_test.v will try to
> run/compile with specific options:
vlib/v/checker/tests/globals_run/ - `-enable-globals run`; vlib/v/checker/tests/globals_run/ - `-enable-globals run`;
results stored in `.run.out` files, matching the .vv ones. results stored in `.run.out` files, matching the .vv ones.
NB 2: in case you need to modify many .out files, run *twice* in a row: NB 2: in case you need to modify many .out files, run *twice* in a row:
`VAUTOFIX=1 ./v vlib/v/compiler_errors_test.v` `VAUTOFIX=1 ./v vlib/v/compiler_errors_test.v`
This will fail the first time, but it will record the new output for each This will fail the first time, but it will record the new output for each
.vv file, and store it into the corresponding .out file. The second run .vv file, and store it into the corresponding .out file. The second run
should be now successfull, and so you can inspect the difference, and should be now successfull, and so you can inspect the difference, and
commit the new .out files with minimum manual effort. commit the new .out files with minimum manual effort.
NB 3: To run only some of the tests, use: NB 3: To run only some of the tests, use:

186
doc/docs.md
View File

@ -209,7 +209,7 @@ by using any of the following commands in a terminal:
</table> </table>
<!-- <!--
NB: there are several special keywords, which you can put after the code fences for v: Note: There are several special keywords, which you can put after the code fences for v:
compile, cgen, live, ignore, failcompile, okfmt, oksyntax, badsyntax, wip, nofmt compile, cgen, live, ignore, failcompile, okfmt, oksyntax, badsyntax, wip, nofmt
For more details, do: `v check-md` For more details, do: `v check-md`
--> -->
@ -252,10 +252,11 @@ This means that a "hello world" program in V is as simple as
println('hello world') println('hello world')
``` ```
Note: if you do not use explicitly `fn main() {}`, you need to make sure, that all your > **Note**
declarations, come before any variable assignment statements, or top level function calls, > If you do not use explicitly `fn main() {}`, you need to make sure, that all your
since V will consider everything after the first assignment/function call as part of your > declarations, come before any variable assignment statements, or top level function calls,
implicit main function. > since V will consider everything after the first assignment/function call as part of your
> implicit main function.
## Running a project folder with several files ## Running a project folder with several files
@ -285,13 +286,15 @@ import os
println(os.args) println(os.args)
``` ```
NB: after a successful run, V will delete the generated executable. > **Note**
If you want to keep it, use `v -keepc run .` instead, or just compile > After a successful run, V will delete the generated executable.
manually with `v .` . > 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. > **Note**
Everything after the source file/folder, will be passed to the program > Any V compiler flags should be passed *before* the `run` command.
as is - it will not be processed by V. > Everything after the source file/folder, will be passed to the program
> as is - it will not be processed by V.
## Comments ## Comments
@ -359,8 +362,9 @@ Functions are private (not exported) by default.
To allow other [modules](#module-imports) to use them, prepend `pub`. The same applies To allow other [modules](#module-imports) to use them, prepend `pub`. The same applies
to [structs](#structs), [constants](#constants) and [types](#type-declarations). to [structs](#structs), [constants](#constants) and [types](#type-declarations).
Note: `pub` can only be used from a named module. > **Note**
For information about creating a module, see [Modules](#modules). > `pub` can only be used from a named module.
> For information about creating a module, see [Modules](#modules).
## Variables ## Variables
@ -477,7 +481,8 @@ voidptr // this one is mostly used for [C interoperability](#v-and-c)
any // similar to C's void* and Go's interface{} any // similar to C's void* and Go's interface{}
``` ```
Please note that unlike C and Go, `int` is always a 32 bit integer. > **Note**
> Unlike C and Go, `int` is always a 32 bit integer.
There is an exception to the rule that all operators 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 in V must have values of the same type on both sides. A small primitive type
@ -623,9 +628,10 @@ To use a format specifier, follow this pattern:
`${varname:[flags][width][.precision][type]}` `${varname:[flags][width][.precision][type]}`
- flags: may be zero or more of the following: `-` to left-align output within the field, `0` to use - flags: may be zero or more of the following: `-` to left-align output within the field, `0` to use
`0` as the padding character instead of the default `space` character. (Note: V does not currently `0` as the padding character instead of the default `space` character.
support the use of `'` or `#` as format flags, and V supports but doesn't need `+` to right-align > **Note**
since that's the default.) > V does not currently support the use of `'` or `#` as format flags, and V supports but
> doesn't need `+` to right-align since that's the default.
- width: may be an integer value describing the minimum width of total field to output. - width: may be an integer value describing the minimum width of total field to output.
- precision: an integer value preceded by a `.` will guarantee that many digits after the decimal - precision: an integer value preceded by a `.` will guarantee that many digits after the decimal
point, if the input variable is a float. Ignored if variable is an integer. point, if the input variable is a float. Ignored if variable is an integer.
@ -637,13 +643,15 @@ To use a format specifier, follow this pattern:
integer and will render it as octal digits, `b` requires an integer and will render it as binary integer and will render it as octal digits, `b` requires an integer and will render it as binary
digits, `s` requires a string (almost never used). digits, `s` requires a string (almost never used).
Note: when a numeric type can render alphabetic characters, such as hex strings or special values > **Note**
like `infinity`, the lowercase version of the type forces lowercase alphabetics and the uppercase > When a numeric type can render alphabetic characters, such as hex strings or special values
version forces uppercase alphabetics. > like `infinity`, the lowercase version of the type forces lowercase alphabetics and the
> uppercase version forces uppercase alphabetics.
Also note: in most cases, it's best to leave the format type empty. Floats will be rendered by > **Note**
default as `g`, integers will be rendered by default as `d`, and `s` is almost always redundant. > In most cases, it's best to leave the format type empty. Floats will be rendered by
There are only three cases where specifying a type is recommended: > default as `g`, integers will be rendered by default as `d`, and `s` is almost always redundant.
> There are only three cases where specifying a type is recommended:
- format strings are parsed at compile time, so specifying a type can help detect errors then - format strings are parsed at compile time, so specifying a type can help detect errors then
- format strings default to using lowercase letters for hex digits and the `e` in exponents. Use a - format strings default to using lowercase letters for hex digits and the `e` in exponents. Use a
@ -887,7 +895,8 @@ println(nums.len) // "0"
`data` is a field (of type `voidptr`) with the address of the first `data` is a field (of type `voidptr`) with the address of the first
element. This is for low-level [`unsafe`](#memory-unsafe-code) code. element. This is for low-level [`unsafe`](#memory-unsafe-code) code.
Note that the fields are read-only and can't be modified by the user. > **Note**
> Fields are read-only and can't be modified by the user.
#### Array Initialization #### Array Initialization
@ -933,7 +942,8 @@ for i in 0 .. 1000 {
} }
``` ```
Note: The above code uses a [range `for`](#range-for) statement. > **Note**
> The above code uses a [range `for`](#range-for) statement.
You can initialize the array by accessing the `it` variable which gives You can initialize the array by accessing the `it` variable which gives
the index as shown here: the index as shown here:
@ -1231,7 +1241,7 @@ You can call .clone() on the slice, if you do want to have an independent copy r
```v ```v
mut a := [0, 1, 2, 3, 4, 5] mut a := [0, 1, 2, 3, 4, 5]
mut b := a[2..4].clone() mut b := a[2..4].clone()
b[0] = 7 // NB: `b[0]` is NOT referring to `a[2]`, as it would have been, without the .clone() b[0] = 7 // Note: `b[0]` is NOT referring to `a[2]`, as it would have been, without the .clone()
println(a) // [0, 1, 2, 3, 4, 5] println(a) // [0, 1, 2, 3, 4, 5]
println(b) // [7, 3] println(b) // [7, 3]
``` ```
@ -1441,8 +1451,9 @@ fn main() {
} }
``` ```
Note: This will import the module as well. Also, this is not allowed for > **Note**
constants - they must always be prefixed. > This will import the module as well. Also, this is not allowed for
> constants - they must always be prefixed.
You can import several specific symbols at once: You can import several specific symbols at once:
@ -1459,7 +1470,8 @@ println('Your OS is ${current_os}.')
Any imported module name can be aliased using the `as` keyword: Any imported module name can be aliased using the `as` keyword:
NOTE: this example will not compile unless you have created `mymod/sha256.v` > **Note**
> This example will not compile unless you have created `mymod/sha256.v`
```v failcompile ```v failcompile
import crypto.sha256 import crypto.sha256
@ -1737,7 +1749,8 @@ println(num)
Constants can also be used in the range branch expressions. Constants can also be used in the range branch expressions.
Note: `match` as an expression is not usable in `for` loop and `if` statements. > **Note**
> `match` as an expression is not usable in `for` loop and `if` statements.
### In operator ### In operator
@ -2273,12 +2286,12 @@ new_button(ButtonConfig{text:'Click me', width:100})
This only works for functions that take a struct for the last argument. This only works for functions that take a struct for the last argument.
NB: the `[params]` tag is used to tell V, that the trailing struct parameter > Note the `[params]` tag is used to tell V, that the trailing struct parameter
can be omitted *entirely*, so that you can write `button := new_button()`. > can be omitted *entirely*, so that you can write `button := new_button()`.
Without it, you have to specify *at least* one of the field names, even if it > Without it, you have to specify *at least* one of the field names, even if it
has its default value, otherwise the compiler will produce this error message, > has its default value, otherwise the compiler will produce this error message,
when you call the function with no parameters: > when you call the function with no parameters:
`error: expected 1 arguments, but got 0`. > `error: expected 1 arguments, but got 0`.
### Access modifiers ### Access modifiers
@ -2526,7 +2539,8 @@ Output: `Size: 4B, clr1.b: 136, clr2.b: 0`
Union member access must be performed in an `unsafe` block. Union member access must be performed in an `unsafe` block.
Note that the embedded struct arguments are not necessarily stored in the order listed. > **Note**
> Embedded struct arguments are not necessarily stored in the order listed.
## Functions 2 ## Functions 2
@ -2541,7 +2555,8 @@ are a function of their arguments only, and their evaluation has no side effects
Function arguments are immutable by default, even when [references](#references) are passed. Function arguments are immutable by default, even when [references](#references) are passed.
Note that V is not a purely functional language however. > **Note**
> V is not a purely functional language however.
There is a compiler flag to enable global variables (`-enable-globals`), but this is There is a compiler flag to enable global variables (`-enable-globals`), but this is
intended for low-level applications like kernels and drivers. intended for low-level applications like kernels and drivers.
@ -2901,8 +2916,9 @@ fn panic(s string) // prints a message and backtraces on stderr, and terminates
fn print_backtrace() // prints backtraces on stderr fn print_backtrace() // prints backtraces on stderr
``` ```
Note: Although the `print` functions take a string, V accepts other printable types too. > **Note**
See below for details. > Although the `print` functions take a string, V accepts other printable types too.
> See below for details.
There is also a special built-in function called [`dump`](#dumping-expressions-at-runtime). There is also a special built-in function called [`dump`](#dumping-expressions-at-runtime).
@ -3398,7 +3414,8 @@ They are just a convenient way to write `i.some_function()` instead of
`some_function(i)`, similar to how struct methods can be looked at, as `some_function(i)`, similar to how struct methods can be looked at, as
a convenience for writing `s.xyz()` instead of `xyz(s)`. a convenience for writing `s.xyz()` instead of `xyz(s)`.
N.B. This feature is NOT a "default implementation" like in C#. > **Note**
> This feature is NOT a "default implementation" like in C#.
For example, if a struct `cat` is wrapped in an interface `a`, that has For example, if a struct `cat` is wrapped in an interface `a`, that has
implemented a method with the same name `speak`, as a method implemented by implemented a method with the same name `speak`, as a method implemented by
@ -3744,7 +3761,9 @@ user := repo.find_user_by_id(7) or { return }
Here, you can either call `panic()` or `exit()`, which will stop the execution of the 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) entire program, or use a control flow statement (`return`, `break`, `continue`, etc)
to break from the current block. to break from the current block.
Note that `break` and `continue` can only be used inside a `for` loop.
> **Note**
> `break` and `continue` can only be used inside a `for` loop.
V does not have a way to forcibly "unwrap" an option (as other languages do, V does not have a way to forcibly "unwrap" an option (as other languages do,
for instance Rust's `unwrap()` or Swift's `!`). To do this, use `or { panic(err) }` instead. for instance Rust's `unwrap()` or Swift's `!`). To do this, use `or { panic(err) }` instead.
@ -4303,7 +4322,8 @@ assert fails it is reported to *stderr*, and the values on each side of a compar
unexpected value. Assert statements can be used in any function, not just test ones, unexpected value. Assert statements can be used in any function, not just test ones,
which is handy when developing new functionality, to keep your invariants in check. which is handy when developing new functionality, to keep your invariants in check.
Note: all `assert` statements are *removed*, when you compile your program with the `-prod` flag. > **Note**
> All `assert` statements are *removed*, when you compile your program with the `-prod` flag.
### Asserts with an extra message ### Asserts with an extra message
@ -4351,8 +4371,9 @@ assert_continues_example.v:3: FAIL: fn main.abc: assert ii == 2
right value: 2 right value: 2
``` ```
Note: V also supports a command line flag `-assert continues`, which will change the > **Note**
behaviour of all asserts globally, as if you had tagged every function with `[assert_continues]`. > V also supports a command line flag `-assert continues`, which will change the
> behaviour of all asserts globally, as if you had tagged every function with `[assert_continues]`.
### Test files ### Test files
@ -4381,10 +4402,11 @@ fn test_hello() {
To run the test file above, use `v hello_test.v`. This will check that the function `hello` is To run the test file 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. producing the correct output. V executes all test functions in the file.
Note: all `_test.v` files (both external and internal ones), are compiled as *separate programs*. > **Note**
In other words, you may have as many `_test.v` files, and tests in them as you like, they will > All `_test.v` files (both external and internal ones), are compiled as *separate programs*.
not affect the compilation of your other code in `.v` files normally at all, but only when you > In other words, you may have as many `_test.v` files, and tests in them as you like, they will
do explicitly `v file_test.v` or `v test .`. > not affect the compilation of your other code in `.v` files normally at all, but only when you
> do explicitly `v file_test.v` or `v test .`.
* All test functions have to be inside a test file whose name ends in `_test.v`. * 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. * Test function names must begin with `test_` to mark them for execution.
@ -4435,8 +4457,9 @@ put .v files with invalid V source code, or other tests, including known
failing ones, that should be run in a specific way/options by a parent _test.v failing ones, that should be run in a specific way/options by a parent _test.v
file. file.
NB: the path to the V compiler, is available through @VEXE, so a _test.v > **Note**
file, can easily run *other* test files like this: > The path to the V compiler, is available through @VEXE, so a _test.v
> file, can easily run *other* test files like this:
```v oksyntax ```v oksyntax
import os import os
@ -4484,9 +4507,10 @@ For developers willing to have more low level control, autofree can be disabled
`-manualfree`, or by adding a `[manualfree]` on each function that wants manage its `-manualfree`, or by adding a `[manualfree]` on each function that wants manage its
memory manually. (See [attributes](#attributes)). memory manually. (See [attributes](#attributes)).
Note 2: Autofree is still WIP. Until it stabilises and becomes the default, please > **Note**
avoid using it. Right now allocations are handled by a minimal and well performing GC > Autofree is still WIP. Until it stabilises and becomes the default, please
until V's autofree engine is production ready. > avoid using it. Right now allocations are handled by a minimal and well performing GC
> until V's autofree engine is production ready.
**Examples** **Examples**
@ -5616,10 +5640,11 @@ With the example above:
That corresponds to `$if customflag ? {}`, but for a whole file, not just a 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 single block. `customflag` should be a snake_case identifier, it can not
contain arbitrary characters (only lower case latin letters + numbers + `_`). contain arbitrary characters (only lower case latin letters + numbers + `_`).
NB: a combinatorial `_d_customflag_linux.c.v` postfix will not work. > **Note**
If you do need a custom flag file, that has platform dependent code, use the > A combinatorial `_d_customflag_linux.c.v` postfix will not work.
postfix `_d_customflag.v`, and then use plaftorm dependent compile time > If you do need a custom flag file, that has platform dependent code, use the
conditional blocks inside it, i.e. `$if linux {}` etc. > 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 - `_notd_customflag.v` => similar to _d_customflag.v, but will be used
*only* if you do NOT pass `-d customflag` to V. *only* if you do NOT pass `-d customflag` to V.
@ -5669,7 +5694,8 @@ 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 finding the cause: look at the `unsafe` blocks (and how they interact with
surrounding code). surrounding code).
* Note: This is work in progress. > **Note**
> This is work in progress.
## Structs with reference fields ## Structs with reference fields
@ -5797,10 +5823,11 @@ 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 additional hints to the compiler, so that it can further optimize some
blocks of code. blocks of code.
NB: These are *rarely* needed, and should not be used, unless you > **Note**
*profile your code*, and then see that there are significant benefits for them. > These are *rarely* needed, and should not be used, unless you
To cite gcc's documentation: "programmers are notoriously bad at predicting > *profile your code*, and then see that there are significant benefits for them.
how their programs actually perform". > 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 `[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, try to inline them, which in some cases, may be beneficial for performance,
@ -5970,8 +5997,9 @@ or
v -os linux . v -os linux .
``` ```
NB: Cross-compiling a windows binary on a linux machine requires the GNU C compiler for > **Note**
MinGW-w64 (targeting Win64) to first be installed. > Cross-compiling a windows binary on a linux machine requires the GNU C compiler for
> MinGW-w64 (targeting Win64) to first be installed.
For Ubuntu/Debian based distributions: For Ubuntu/Debian based distributions:
@ -6113,7 +6141,7 @@ fn main() {
// C.sqlite3_open(db_path.str, &db) // C.sqlite3_open(db_path.str, &db)
query := 'select count(*) from users' query := 'select count(*) from users'
stmt := &C.sqlite3_stmt(0) stmt := &C.sqlite3_stmt(0)
// NB: you can also use the `.str` field of a V string, // Note: You can also use the `.str` field of a V string,
// to get its C style zero terminated representation // to get its C style zero terminated representation
C.sqlite3_prepare_v2(db, &char(query.str), -1, &stmt, 0) C.sqlite3_prepare_v2(db, &char(query.str), -1, &stmt, 0)
C.sqlite3_step(stmt) C.sqlite3_step(stmt)
@ -6152,7 +6180,8 @@ Add `#flag` directives to the top of your V files to provide C compilation flags
You can (optionally) use different flags for different targets. You can (optionally) use different flags for different targets.
Currently the `linux`, `darwin` , `freebsd`, and `windows` flags are supported. Currently the `linux`, `darwin` , `freebsd`, and `windows` flags are supported.
NB: Each flag must go on its own line (for now) > **Note**
> Each flag must go on its own line (for now)
```v oksyntax ```v oksyntax
#flag linux -lsdl2 #flag linux -lsdl2
@ -6228,11 +6257,13 @@ Module {
#include "header.h" #include "header.h"
``` ```
NB: @VMODROOT will be replaced by V with the *nearest parent folder, where there is a v.mod file*. > **Note**
Any .v file beside or below the folder where the v.mod file is, > @VMODROOT will be replaced by V with the *nearest parent folder,
can use `#flag @VMODROOT/abc` to refer to this folder. > where there is a v.mod file*.
The @VMODROOT folder is also *prepended* to the module lookup path, > Any .v file beside or below the folder where the v.mod file is,
so you can *import* other modules under your @VMODROOT, by just naming them. > 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 The instructions above will make V look for an compiled .o file in
your module `folder/c/implementation.o`. your module `folder/c/implementation.o`.
@ -6252,10 +6283,11 @@ 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() }` or if you know their length already with
`unsafe { &char(cstring).vstring_with_len(len) }`. `unsafe { &char(cstring).vstring_with_len(len) }`.
NB: The .vstring() and .vstring_with_len() methods do NOT create a copy of the `cstring`, > **Note**
so you should NOT free it after calling the method `.vstring()`. > The `.vstring()` and `.vstring_with_len()` methods do NOT create a copy of the `cstring`,
If you need to make a copy of the C string (some libc APIs like `getenv` pretty much require that, > so you should NOT free it after calling the method `.vstring()`.
since they return pointers to internal libc memory), you can use `cstring_to_vstring(cstring)`. > 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). 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))` . These can be converted to V strings with `string_from_wide(&u16(cwidestring))` .
@ -6475,7 +6507,7 @@ An example `deploy.vsh`:
```v oksyntax ```v oksyntax
#!/usr/bin/env -S v #!/usr/bin/env -S v
// Note: the shebang line above, associates the .vsh file to V on Unix-like systems, // Note: The shebang line above, associates the .vsh file to V on Unix-like systems,
// so it can be run just by specifying the path to the .vsh file, once it's made // so it can be run just by specifying the path to the .vsh file, once it's made
// executable, using `chmod +x deploy.vsh`, i.e. after that chmod command, you can // executable, using `chmod +x deploy.vsh`, i.e. after that chmod command, you can
// run the .vsh script, by just typing its name/path like this: `./deploy.vsh` // run the .vsh script, by just typing its name/path like this: `./deploy.vsh`

39
doc/upcoming.md
View File

@ -8,11 +8,11 @@ for the current state of V***
* [Concurrency](#concurrency) * [Concurrency](#concurrency)
* [Variable Declarations](#variable-declarations) * [Variable Declarations](#variable-declarations)
* [Strengths](#strengths) * [Strengths](#strengths)
* [Weaknesses](#weaknesses) * [Weaknesses](#weaknesses)
* [Compatibility](#compatibility) * [Compatibility](#compatibility)
* [Automatic Lock](#automatic-lock) * [Automatic Lock](#automatic-lock)
* [Channels](#channels) * [Channels](#channels)
## Concurrency ## Concurrency
@ -47,7 +47,7 @@ atomic d := ...
... ...
} }
``` ```
```v ignore ```v ignore
rlock c { rlock c {
// read c // read c
@ -65,46 +65,56 @@ atomic d := ...
To help making the correct decision the following table summarizes the To help making the correct decision the following table summarizes the
different capabilities: different capabilities:
| | *default* | `mut` | `shared` | `atomic` | | | *default* | `mut` | `shared` | `atomic` |
| :--- | :---: | :---: | :---: | :---: | |:-------------------------|:---------:|:-----:|:--------:|:--------:|
| write access | | + | + | + | | write access | | + | + | + |
| concurrent access | + | | + | + | | concurrent access | + | | + | + |
| performance | ++ | ++ | | + | | performance | ++ | ++ | | + |
| sophisticated operations | + | + | + | | | sophisticated operations | + | + | + | |
| structured data types | + | + | + | | | structured data types | + | + | + | |
### Strengths ### Strengths
**default** **default**
- very fast - very fast
- unlimited access from different coroutines - unlimited access from different coroutines
- easy to handle - easy to handle
**`mut`** **`mut`**
- very fast - very fast
- easy to handle - easy to handle
**`shared`** **`shared`**
- concurrent access from different coroutines - concurrent access from different coroutines
- data type may be complex structure - data type may be complex structure
- sophisticated access possible (several statements within one `lock` - sophisticated access possible (several statements within one `lock`
block) block)
**`atomic`** **`atomic`**
- concurrent access from different coroutines - concurrent access from different coroutines
- reasonably fast - reasonably fast
### Weaknesses ### Weaknesses
**default** **default**
- read only - read only
**`mut`** **`mut`**
- access only from one coroutine at a time - access only from one coroutine at a time
**`shared`** **`shared`**
- lock/unlock are slow - lock/unlock are slow
- moderately difficult to handle (needs `lock` block) - moderately difficult to handle (needs `lock` block)
**`atomic`** **`atomic`**
- limited to single (max. 64 bit) integers (and pointers) - limited to single (max. 64 bit) integers (and pointers)
- only a small set of predefined operations possible - only a small set of predefined operations possible
- very difficult to handle correctly - very difficult to handle correctly
@ -118,6 +128,7 @@ allocation would be an unnecessary overhead. Instead the compiler
creates a global. creates a global.
### Compatibility ### Compatibility
Outside of `lock`/`rlock` blocks function arguments must in general Outside of `lock`/`rlock` blocks function arguments must in general
match - with the familiar exception that objects declared `mut` can be match - with the familiar exception that objects declared `mut` can be
used to call functions expecting immutable arguments: used to call functions expecting immutable arguments:
@ -145,6 +156,7 @@ i(atomic d)
Inside a `lock c {...}` block `c` behaves like a `mut`, Inside a `lock c {...}` block `c` behaves like a `mut`,
inside an `rlock c {...}` block like an immutable: inside an `rlock c {...}` block like an immutable:
```v ignore ```v ignore
shared c := St{...} shared c := St{...}
lock c { lock c {
@ -160,6 +172,7 @@ rlock c {
``` ```
### Automatic Lock ### Automatic Lock
In general the compiler will generate an error message when a `shared` In general the compiler will generate an error message when a `shared`
object is accessed outside of any corresponding `lock`/`rlock` object is accessed outside of any corresponding `lock`/`rlock`
block. However in simple and obvious cases the necessary lock/unlock block. However in simple and obvious cases the necessary lock/unlock

31
doc/vscode.md
View File

@ -13,11 +13,12 @@ provides V language support for Visual Studio Code.
![Screenshot Code with activated extension](https://github.com/vlang/vscode-vlang/raw/HEAD/images/demo.png) ![Screenshot Code with activated extension](https://github.com/vlang/vscode-vlang/raw/HEAD/images/demo.png)
**Features:** **Features:**
* Syntax Highlighting. * Syntax Highlighting.
* Code Snippets for quick coding. * Code Snippets for quick coding.
* Format code on file save as well as format manually (using v fmt). * Format code on file save as well as format manually (using v fmt).
* Linter (Workspace files only). * Linter (Workspace files only).
[more](https://marketplace.visualstudio.com/items?itemName=vlanguage.vscode-vlang) [more](https://marketplace.visualstudio.com/items?itemName=vlanguage.vscode-vlang)
**Hint:** This extension will not add the V compiler! Information on how to **Hint:** This extension will not add the V compiler! Information on how to
[install V compiler](https://github.com/vlang/v/blob/master/doc/docs.md#install-from-source) [install V compiler](https://github.com/vlang/v/blob/master/doc/docs.md#install-from-source)
@ -35,31 +36,35 @@ The [C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vsc
for Visual Studio Code provides visual conditional debugging. for Visual Studio Code provides visual conditional debugging.
**Features:** **Features:**
* Conditional breakpoints * Conditional breakpoints
* Function breakpoints * Function breakpoints
* Expression evaluation * Expression evaluation
* Change Values * Change Values
[more Features & Documentation](https://code.visualstudio.com/docs/cpp/cpp-debug) [more Features & Documentation](https://code.visualstudio.com/docs/cpp/cpp-debug)
**Hint:** Not all types (e.g. Array) in V currently create the required **Hint:** Not all types (e.g. Array) in V currently create the required
[DWARF](https://en.wikipedia.org/wiki/DWARF) information to show and [DWARF](https://en.wikipedia.org/wiki/DWARF) information to show and
edit the variable. edit the variable.
### Setup Debugging ### Setup Debugging
#### Step1: Configure the launch.json file #### Step1: Configure the launch.json file
1. Install the [C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
1. Install the
[C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
2. Open `RUN AND DEBUG` panel (Debug Icon in left panel). 2. Open `RUN AND DEBUG` panel (Debug Icon in left panel).
3. Click on `Show` all automatic debug configurations. 3. Click on `Show` all automatic debug configurations.
4. Select `Add config`. 4. Select `Add config`.
5. Select environment `C++ (GDB/LLDB)`. 5. Select environment `C++ (GDB/LLDB)`.
6. Change the line `"program": "Enter the program name, e.g. \"${workspaceFolder}/a.out\"",` 6. Change the line `"program": "Enter the program name, e.g. \"${workspaceFolder}/a.out\"",`
to point to your compiled application e.g. `"program": "${workspaceFolder}/hello",` to point to your compiled application e.g. `"program": "${workspaceFolder}/hello",`
or a more flexible one `"program": "${fileDirname}/${fileBasenameNoExtension}",` or a more flexible one `"program": "${fileDirname}/${fileBasenameNoExtension}",`
when you want to debug the current opened file. when you want to debug the current opened file.
This will add a block to your `.workspace` file, This will add a block to your `.workspace` file,
or create the file `.vscode/launch.json`: or create the file `.vscode/launch.json`:
```json ```json
{ {
// Use IntelliSense to learn about possible attributes. // Use IntelliSense to learn about possible attributes.
@ -85,10 +90,11 @@ or create the file `.vscode/launch.json`:
} }
``` ```
**Optional:** use `"program": "${fileDirname}/${fileBasenameNoExtension}"` to debug **Optional:** use `"program": "${fileDirname}/${fileBasenameNoExtension}"` to debug
any current open source file with an existing binary with the same name but without any extension. any current open source file with an existing binary with the same name but without any extension.
#### Step2: Configure the tasks.json file #### Step2: Configure the tasks.json file
Generally, you can manually compile the application with: `v -b c -g hello.v -o hello`, Generally, you can manually compile the application with: `v -b c -g hello.v -o hello`,
or for short: `v -g hello.v`, and then call the debugger. or for short: `v -g hello.v`, and then call the debugger.
@ -96,14 +102,15 @@ The `-g` option will add the needed debugging information.
You can find more debugging options in the [docs](docs.md#debugging). You can find more debugging options in the [docs](docs.md#debugging).
VS Code provides a hook called `preLaunchTask`, which can be used to compile VS Code provides a hook called `preLaunchTask`, which can be used to compile
the application automatically every time you call the debugger. the application automatically every time you call the debugger.
[preLaunchTask](https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes) launches [preLaunchTask](https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes) launches
a task before the start of a debug session, set this attribute to the label of a task specified a task before the start of a debug session, set this attribute to the label of a task specified
in [task.json](https://code.visualstudio.com/docs/editor/tasks) (in the workspace's .vscode folder). in [task.json](https://code.visualstudio.com/docs/editor/tasks) (in the workspace's .vscode folder).
Or, this can be set to `${defaultBuildTask}`, to use your default build task. Or, this can be set to `${defaultBuildTask}`, to use your default build task.
As explained, the `"preLaunchTask": "build"` needs to work with a `.vscode/tasks.json` As explained, the `"preLaunchTask": "build"` needs to work with a `.vscode/tasks.json`
with a label named `build`. with a label named `build`.
```json ```json
{ {
// See https://go.microsoft.com/fwlink/?LinkId=733558 // See https://go.microsoft.com/fwlink/?LinkId=733558
@ -136,7 +143,7 @@ The application needs to include additional debugging information
1. Open your source code and set the required break points 1. Open your source code and set the required break points
2. Click on the Debug Icon in the left Icon panel and click 2. Click on the Debug Icon in the left Icon panel and click
`> (lldb) Start`, or use `F5` to launch your application in debug mode. `> (lldb) Start`, or use `F5` to launch your application in debug mode.
For all options look at the official For all options look at the official
[C/C++ Extension documentation](https://code.visualstudio.com/docs/cpp/cpp-debug). [C/C++ Extension documentation](https://code.visualstudio.com/docs/cpp/cpp-debug).

4
examples/regex/readme.md
View File

@ -3,6 +3,8 @@
There are 2 ways to do regex: There are 2 ways to do regex:
a) using the native module called `regex` a) using the native module called `regex`
b) using an exteranl module called `pcre`, which wraps the C library pcre. b) using an exteranl module called `pcre`, which wraps the C library pcre.
NB: you need to first do: `v install pcre`, for the `pcre` module to work.
> **Note**
> You need to first do: `v install pcre`, for the `pcre` module to work.
You can find examples of both in this directory. You can find examples of both in this directory.

3
tutorials/building_a_simple_web_blog_with_vweb/README.md
View File

@ -16,7 +16,8 @@ The benefits of using V for web:
is enough. is enough.
- Fast development without any boilerplate. - Fast development without any boilerplate.
_Please note that V and Vweb are at a very early stage and are changing rapidly._ > **Note**
> V and Vweb are at a very early stage and are changing rapidly.
The code is available [here](./code/blog). The code is available [here](./code/blog).

13
vlib/db/mysql/README.md
View File

@ -3,11 +3,14 @@ For Linux, you need to install `MySQL development` package and `pkg-config`.
For Windows, install [the installer](https://dev.mysql.com/downloads/installer/) , For Windows, install [the installer](https://dev.mysql.com/downloads/installer/) ,
then copy the `include` and `lib` folders to `<V install directory>\thirdparty\mysql`. then copy the `include` and `lib` folders to `<V install directory>\thirdparty\mysql`.
Note: if you encounter weird errors (your program just exits right away, without ### Troubleshooting
printing any messages, even though you have `println('hi')` statements in your
`fn main()`), when trying to run a program that does `import db.mysql` on windows, you If you encounter weird errors (your program just exits right away, without
may need to copy the .dll file: `thirdparty/mysql/lib/libmysql.dll` , into the folder printing any messages, even though you have `println('hi')` statements in your
of the executable too (it should be right next to the .exe file). `fn main()`), when trying to run a program that does `import db.mysql` on windows, you
may need to copy the .dll file: `thirdparty/mysql/lib/libmysql.dll`, into the folder
of the executable too (it should be right next to the .exe file).
This is a temporary workaround, until we have a more permanent solution, or at least This is a temporary workaround, until we have a more permanent solution, or at least
more user friendly errors for that situation. more user friendly errors for that situation.

5
vlib/db/pg/README.md
View File

@ -6,8 +6,9 @@ database server.
Before you can use this module, you must first have PostgreSQL installed on your system. Before you can use this module, you must first have PostgreSQL installed on your system.
To do this, find your OS and perform the actions listed. To do this, find your OS and perform the actions listed.
**NOTE**: These instructions are meant only as a convenience. If your OS is not listed > **Note**
or you need extra help, [go here](https://www.postgresql.org/download/). > These instructions are meant only as a convenience. If your OS is not listed
> or you need extra help, [go here](https://www.postgresql.org/download/).
### Fedora 31 ### Fedora 31
``` ```

3
vlib/dl/README.md
View File

@ -5,5 +5,6 @@ It is a thin wrapper over `LoadLibrary` on Windows, and `dlopen` on Unix.
Using it, you can implement a plugin system for your application. Using it, you can implement a plugin system for your application.
> NOTE: We highly recommend using `dl.loader` instead of `dl` directly. > **Note**
> We highly recommend using `dl.loader` instead of `dl` directly.
> It provides a more user-friendly API in the V way. > It provides a more user-friendly API in the V way.

5
vlib/encoding/binary/README.md
View File

@ -19,5 +19,6 @@ sequence of bytes in the previous example: `0x12`, `0x34`, `0x56`, and `0x78`. I
this sequence in little endian format, we get the integer `0x78563412`. If we encode this this sequence in little endian format, we get the integer `0x78563412`. If we encode this
sequence in big endian, we get `0x12345678`. sequence in big endian, we get `0x12345678`.
**NOTE:** The functions in this module assume appropriately sized u8 arrays. If the sizes > **Note**
are not valid, the functions will panic. > The functions in this module assume appropriately sized u8 arrays. If the sizes
> are not valid, the functions will panic.

3
vlib/eventbus/README.md
View File

@ -51,7 +51,8 @@ fn on_press(receiver voidptr, e &ClickEvent, sender voidptr) {
For **usage across modules** For **usage across modules**
[check the example](https://github.com/vlang/v/tree/master/examples/eventbus). [check the example](https://github.com/vlang/v/tree/master/examples/eventbus).
_Note: As a general rule, you will need to **subscribe before publishing**._ > **Note**
> As a general rule, you will need to **subscribe before publishing**.
**main.v** **main.v**

3
vlib/gx/README.md
View File

@ -3,4 +3,5 @@
`gx` is a complementary module to `gg`, that just provides `gx` is a complementary module to `gg`, that just provides
some predefined graphical color names/operations. some predefined graphical color names/operations.
NB: `gx` is going to be merged with `gg` soon. > **Note**
> `gx` is going to be merged with `gg` soon.

4
vlib/js/README.md
View File

@ -1,4 +1,6 @@
## Description: ## Description:
`js` is frontend/browser specific module, that provides access to global JS functions. `js` is frontend/browser specific module, that provides access to global JS functions.
NB: it *only* works with the JS backend.
> **Note**
> It *only* works with the JS backend.

14
vlib/rand/README.md
View File

@ -50,8 +50,9 @@ rng.int() // among others ...
You can change the default generator to a different one. The only requirement is that You can change the default generator to a different one. The only requirement is that
the generator must implement the `PRNG` interface. See `get_current_rng()` and `set_rng()`. the generator must implement the `PRNG` interface. See `get_current_rng()` and `set_rng()`.
**Note:** The global PRNG is not thread safe. It is recommended to use separate generators for > **Note**
separate threads in multi-threaded applications. > The global PRNG is not thread safe. It is recommended to use separate generators for
> separate threads in multi-threaded applications.
There are only a few extra functions that are defined only in this top-level `rand` module. There are only a few extra functions that are defined only in this top-level `rand` module.
Otherwise, there is feature parity between the generator functions and the top-level functions. Otherwise, there is feature parity between the generator functions and the top-level functions.
@ -80,8 +81,8 @@ The helper functions publicly available in `rand.seed` module are:
2. `time_seed_32()` and `time_seed_64()` - 32-bit and 64-bit values respectively 2. `time_seed_32()` and `time_seed_64()` - 32-bit and 64-bit values respectively
that are generated from the current time. that are generated from the current time.
When composing your own seeds, use "typical" u32 numbers, not small numbers. This When composing your own seeds, use "typical" u32 numbers, not small numbers. This
is especially important for PRNGs with large state, such as `mt19937`. You can create is especially important for PRNGs with large state, such as `mt19937`. You can create
random unsigned integers with openssl `rand` or with `v repl` as follows: random unsigned integers with openssl `rand` or with `v repl` as follows:
``` ```
@ -110,7 +111,8 @@ A workaround (if you _must_ use the libc RNG) is to:
# Notes # Notes
Please note that [math interval](<https://en.wikipedia.org/wiki/Interval_(mathematics)#Including_or_excluding_endpoints>) notation is used throughout [Math interval](<https://en.wikipedia.org/wiki/Interval_(mathematics)#Including_or_excluding_endpoints>)
the function documentation to denote what numbers ranges include. notation is used throughout the function documentation to denote what numbers ranges include.
An example of `[0, max)` thus denotes a range with all posible values An example of `[0, max)` thus denotes a range with all posible values
between `0` and `max` **including** 0 but **excluding** `max`. between `0` and `max` **including** 0 but **excluding** `max`.

46
vlib/regex/README.md
View File

@ -2,7 +2,8 @@
`regex` is a small but powerful regular expression library, `regex` is a small but powerful regular expression library,
written in pure V. written in pure V.
NB: `regex` is *not* PCRE compatible. > **Note**
> `regex` is *not* PCRE compatible.
[TOC] [TOC]
@ -19,9 +20,10 @@ In a query string a simple character is a token.
## Differences with PCRE: ## Differences with PCRE:
NB: We must point out that the **V-Regex module is not PCRE compliant** and thus > **Note**
some behaviour will be different. This difference is due to the V philosophy, > We must point out that the **V-Regex module is not PCRE compliant** and thus
to have one way and keep it simple. > some behaviour will be different. This difference is due to the V philosophy,
> to have one way and keep it simple.
The main differences can be summarized in the following points: The main differences can be summarized in the following points:
@ -81,12 +83,13 @@ latin chars `a-z` and all the digits `\d`.
It is possible to mix all the properties of the char class together. It is possible to mix all the properties of the char class together.
NB: In order to match the `-` (minus) char, it must be preceded by > **Note**
a backslash in the cc, for example `[\-_\d\a]` will match: > In order to match the `-` (minus) char, it must be preceded by
`-` minus, > a backslash in the cc, for example `[\-_\d\a]` will match:
`_` underscore, > - `-` minus,
`\d` numeric chars, > - `_` underscore,
`\a` lower case chars. > - `\d` numeric chars,
> - `\a` lower case chars.
### Meta-chars ### Meta-chars
@ -146,8 +149,8 @@ parsing source string.
| `ab.{3} .*e` | `abccc dde` | | `ab.{3} .*e` | `abccc dde` |
The dot matches any character, until the next token match is satisfied. The dot matches any character, until the next token match is satisfied.
**Important Note:** *Consecutive dots, for example `...`, are not allowed.* > Important Note: Consecutive dots, for example `...`, are not allowed.
*This will cause a syntax error. Use a quantifier instead.* > This will cause a syntax error. Use a quantifier instead.
### OR token ### OR token
@ -158,9 +161,12 @@ The OR token can work in a "chained way": `a|(b)|cd ` means test first `a`,
if the char is not `a`, then test the group `(b)`, and if the group doesn't if the char is not `a`, then test the group `(b)`, and if the group doesn't
match too, finally test the token `c`. match too, finally test the token `c`.
NB: ** unlike in PCRE, the OR operation works at token level!** > **Note**
It doesn't work at concatenation level! > Unlike in PCRE, the OR operation works at token level!
NB2: **Two char classes with an `OR` in the middle is a syntax error.** > It doesn't work at concatenation level!
> **Note**
> Two char classes with an `OR` in the middle is a syntax error.
That also means, that a query string like `abc|bde` is not equal to That also means, that a query string like `abc|bde` is not equal to
`(abc)|(bde)`, but instead to `ab(c|b)de. `(abc)|(bde)`, but instead to `ab(c|b)de.
@ -220,8 +226,9 @@ for gi < re.groups.len {
// 1 :[pa] // 1 :[pa]
``` ```
**note:** *to show the `group id number` in the result of the `get_query()`* > **Note**
*the flag `debug` of the RE object must be `1` or `2`* > To show the `group id number` in the result of the `get_query()`
> the flag `debug` of the RE object must be `1` or `2`
In order to simplify the use of the captured groups, it possible to use the In order to simplify the use of the captured groups, it possible to use the
utility function: `get_group_list`. utility function: `get_group_list`.
@ -248,7 +255,7 @@ fn convert_html_rgb(in_col string) u32 {
mut n_digit := if in_col.len == 4 { 1 } else { 2 } mut n_digit := if in_col.len == 4 { 1 } else { 2 }
mut col_mul := if in_col.len == 4 { 4 } else { 0 } mut col_mul := if in_col.len == 4 { 4 } else { 0 }
// this is the regex query, it use the V string interpolation to customize the regex query // this is the regex query, it use the V string interpolation to customize the regex query
// NOTE: if you want use escaped code you must use the r"" (raw) strings, // Note: If you want use escaped code you must use the r"" (raw) strings,
// *** please remember that the V interpoaltion doesn't work on raw strings. *** // *** please remember that the V interpoaltion doesn't work on raw strings. ***
query := '#([a-fA-F0-9]{${n_digit}})([a-fA-F0-9]{${n_digit}})([a-fA-F0-9]{${n_digit}})' query := '#([a-fA-F0-9]{${n_digit}})([a-fA-F0-9]{${n_digit}})([a-fA-F0-9]{${n_digit}})'
mut re := regex.regex_opt(query) or { panic(err) } mut re := regex.regex_opt(query) or { panic(err) }
@ -598,7 +605,8 @@ in this example we used the group `0` in the replace string: `\0`, the result wi
Today it is a good day. => Tod__[ay]__it is a good d__[ay]__ Today it is a good day. => Tod__[ay]__it is a good d__[ay]__
``` ```
**Note:** in the replace strings can be used only groups from `0` to `9`. > **Note**
> In the replace strings can be used only groups from `0` to `9`.
If the usage of `groups` in the replace process, is not needed, it is possible If the usage of `groups` in the replace process, is not needed, it is possible
to use a quick function: to use a quick function:

3
vlib/strconv/format.md
View File

@ -2,7 +2,8 @@
These are v implementations of the C language `printf` and `sprintf` functions. These are v implementations of the C language `printf` and `sprintf` functions.
***Note: These functions are platform dependent in C, but in V they are platform independent.*** > **Note**
> These functions are platform dependent in C, but in V they are platform independent.
### v_sprintf ### v_sprintf

36
vlib/v/TEMPLATES.md
View File

@ -4,78 +4,99 @@ usefull for templated HTML views, but the mechanism is general enough
to be used for other kinds of text output also. to be used for other kinds of text output also.
# Template directives # Template directives
Each template directive begins with an `@` sign. Each template directive begins with an `@` sign.
Some directives contain a `{}` block, others only have `''` (string) parameters. Some directives contain a `{}` block, others only have `''` (string) parameters.
Newlines on the beginning and end are ignored in `{}` blocks, Newlines on the beginning and end are ignored in `{}` blocks,
otherwise this (see [if](#if) for this syntax): otherwise this (see [if](#if) for this syntax):
```html ```html
@if bool_val { @if bool_val {
<span>This is shown if bool_val is true</span> <span>This is shown if bool_val is true</span>
} }
``` ```
... would output: ... would output:
```html ```html
<span>This is shown if bool_val is true</span> <span>This is shown if bool_val is true</span>
``` ```
... which is less readable. ... which is less readable.
## if ## if
The if directive, consists of three parts, the `@if` tag, the condition (same syntax like in V) The if directive, consists of three parts, the `@if` tag, the condition (same syntax like in V)
and the `{}` block, where you can write html, which will be rendered if the condition is true: and the `{}` block, where you can write html, which will be rendered if the condition is true:
``` ```
@if <condition> {} @if <condition> {}
``` ```
### Example ### Example
```html ```html
@if bool_val { @if bool_val {
<span>This is shown if bool_val is true</span> <span>This is shown if bool_val is true</span>
} }
``` ```
One-liner: One-liner:
```html ```html
@if bool_val { <span>This is shown if bool_val is true</span> } @if bool_val { <span>This is shown if bool_val is true</span> }
``` ```
The first example would result in: The first example would result in:
```html ```html
<span>This is shown if bool_val is true</span> <span>This is shown if bool_val is true</span>
``` ```
... while the one-liner results in: ... while the one-liner results in:
```html ```html
<span>This is shown if bool_val is true</span> <span>This is shown if bool_val is true</span>
``` ```
## for ## for
The for directive consists of three parts, the `@for` tag, The for directive consists of three parts, the `@for` tag,
the condition (same syntax like in V) and the `{}` block, the condition (same syntax like in V) and the `{}` block,
where you can write text, rendered for each iteration of the loop: where you can write text, rendered for each iteration of the loop:
``` ```
@for <condition> {} @for <condition> {}
``` ```
### Example for @for ### Example for @for
```html ```html
@for i, val in my_vals { @for i, val in my_vals {
<span>$i - $val</span> <span>$i - $val</span>
} }
``` ```
One-liner: One-liner:
```html ```html
@for i, val in my_vals { <span>$i - $val</span> } @for i, val in my_vals { <span>$i - $val</span> }
``` ```
The first example would result in: The first example would result in:
```html ```html
<span>0 - "First"</span> <span>0 - "First"</span>
<span>1 - "Second"</span> <span>1 - "Second"</span>
<span>2 - "Third"</span> <span>2 - "Third"</span>
... ...
``` ```
... while the one-liner results in: ... while the one-liner results in:
```html ```html
<span>0 - "First"</span> <span>0 - "First"</span>
<span>1 - "Second"</span> <span>1 - "Second"</span>
@ -84,6 +105,7 @@ The first example would result in:
``` ```
You can also write (and all other for condition syntaxes that are allowed in V): You can also write (and all other for condition syntaxes that are allowed in V):
```html ```html
@for i = 0; i < 5; i++ { @for i = 0; i < 5; i++ {
<span>$i</span> <span>$i</span>
@ -91,11 +113,13 @@ You can also write (and all other for condition syntaxes that are allowed in V):
``` ```
## include ## include
The include directive is for including other html files (which will be processed as well) The include directive is for including other html files (which will be processed as well)
and consists of two parts, the `@include` tag and a following `'<path>'` string. and consists of two parts, the `@include` tag and a following `'<path>'` string.
The path parameter is relative to the `/templates` directory in the corresponding project. The path parameter is relative to the `/templates` directory in the corresponding project.
### Example for the folder structure of a project using templates: ### Example for the folder structure of a project using templates:
``` ```
Project root Project root
/templates /templates
@ -105,25 +129,31 @@ Project root
``` ```
`index.html` `index.html`
```html ```html
<div>@include 'header/base'</div> <div>@include 'header/base'</div>
``` ```
> Note that there shouldn't be a file suffix, > Note that there shouldn't be a file suffix,
it is automatically appended and only allows `html` files. > it is automatically appended and only allows `html` files.
## js ## js
The js directive consists of two parts, the `@js` tag and `'<path>'` string, The js directive consists of two parts, the `@js` tag and `'<path>'` string,
where you can insert your src where you can insert your src
``` ```
@js '<url>' @js '<url>'
``` ```
### Example for the @js directive: ### Example for the @js directive:
```html ```html
@js 'myscripts.js' @js 'myscripts.js'
``` ```
# Variables # Variables
All variables, which are declared before the $tmpl can be used through the `@{my_var}` syntax. All variables, which are declared before the $tmpl can be used through the `@{my_var}` syntax.
It's also possible to use properties of structs here like `@{my_struct.prop}`. It's also possible to use properties of structs here like `@{my_struct.prop}`.

9
vlib/v/help/FORMATTING.md
View File

@ -4,14 +4,13 @@
- 2 space initial indentation (titles exempt) - 2 space initial indentation (titles exempt)
- Description indentation of two spaces from the longest word - Description indentation of two spaces from the longest word
- All descriptions should be indented to the same column within a block, with a - All descriptions should be indented to the same column within a block, with a
hard limit at column 80. hard limit at column 80.
- Multi-line descriptions should indent to match the description part of the previous line - Multi-line descriptions should indent to match the description part of the previous line
## Example ## Example
Adding a help file was made to be easy. All you have to do is create the text file in the Adding a help file was made to be easy. All you have to do is create the text file in the
appropriate category, and V should recognize it. appropriate category, and V should recognize it.
```text ```text

5
vlib/v/preludes/README.md
View File

@ -4,8 +4,9 @@ The vlib/v/preludes/ contains small v code snippets, that V uses when
compiling certain v programs. V adds the files below automatically itself. compiling certain v programs. V adds the files below automatically itself.
Each file is used in different situations (see below). Each file is used in different situations (see below).
NB: preludes are *NOT* intended to be used by user programs/modules. > **Note**
The folder vlib/v/preludes/ is *NOT* a v module. > Preludes are *NOT* intended to be used by user programs/modules.
> The folder vlib/v/preludes/ is *NOT* a v module.
## Details: ## Details:

7
vlib/v/tests/project_with_tests_for_main/README.md
View File

@ -20,6 +20,7 @@ Instead, your test_ functions will get called inside the generated
`int main(){...}` test runner, just like it is the case with all _test.v `int main(){...}` test runner, just like it is the case with all _test.v
files (internal or external ones). files (internal or external ones).
NB: each _test.v file is compiled separately from all other _test.v > **Note**
files, so you can have conflicting test_ functions in them without a > Each _test.v file is compiled separately from all other _test.v
problem too. > files, so you can have conflicting test_ functions in them without a
> problem too.

9
vlib/x/ttf/README.md
View File

@ -17,7 +17,10 @@ mut ttf_font := ttf.TTF_File{}
ttf_font.buf = os.read_bytes("arial.ttf") or { panic(err) } ttf_font.buf = os.read_bytes("arial.ttf") or { panic(err) }
ttf_font.init() ttf_font.init()
``` ```
*Note: the font must be passed to the `TTF_file` as RAM buffer.*
> **Note**
> The font must be passed to the `TTF_file` as RAM buffer.
At this point the font "arial" is loaded and parsed and if it is a valid TTF font it is At this point the font "arial" is loaded and parsed and if it is a valid TTF font it is
ready for the rendering. ready for the rendering.
We can get some quick info on the font as string using the `get_info_string` function: We can get some quick info on the font as string using the `get_info_string` function:
@ -115,7 +118,9 @@ fn main() {
``` ```
This is the low level render that draw ther text on a bitmap and save the bitmap on a disk as This is the low level render that draw ther text on a bitmap and save the bitmap on a disk as
`.ppm` file. `.ppm` file.
*Note: The render in this case is a raw rendering without any postfiltering or other processing.*
> **Note**
> The render in this case is a raw rendering without any postfiltering or other processing.
Using the low level rendering you need to manage all the amenities like allocate and release Using the low level rendering you need to manage all the amenities like allocate and release
memory and other tasks like calc the character dimensions. memory and other tasks like calc the character dimensions.