v/vlib/v/README.md

129 lines
3.5 KiB
Markdown
Raw Normal View History

## Description
`v` is a namespace for all of the V compiler modules.
The V compiler modules can be used by V programs that want to
process V source code in different ways, in fact, that is how
various V tools are implemented: `v fmt`, `v doc`, `v ast`, `vls`,
as well as the V compiler itself.
# Compiler pipeline
A simple high level explanation
how the compiler pipeline (`parser` -> `checker` -> `generator`) works.
## Reading files
### Getting builtin files
To load all builtin files,
a preference `Preferences.lookup_path` for the path where to look for exists.
See `Builder.get_builtin_files` as example.
If the file is a `.vsh` file and the backend is C, `vlib/os` will also be loaded as builtin.
### Getting project files
Either there is a specific file: `my_file.v` or a directory containing V files.
In the last case it scans that directory for all files.
See `Builder.v_files_from_dir` as the helper method.
This list of files needs to be filtered so that only `*.v` files exist.
Skips the following file types:
- `*_test.v`
- either `*.c.v` or `*.c.js` depending on the backend
- all files that doesn't end with `.v`
- Files that are not defined in `Preferences.compile_defines`
or `Preferences.compile_defines_all` **if any file is defined**.
## Parsing files
To parse something a new template is created as the first step:
```v
import v.ast
table := ast.new_table()
```
a new preference is created:
```v
import v.pref
pref := &pref.Preferences{}
```
and a new scope is created:
```v
import v.ast
scope := ast.Scope{
parent: 0
}
```
after that, you can parse your files.
## Parse text
If you want to parse only text which isn't saved on the disk you can use this function.
```v oksyntax
import v.parser
code := ''
// table, pref and scope needs to be passed as reference
parsed_file := parser.parse_text(code, table, .parse_comments, &pref, &scope)
```
## Parse a single file
For parsing files on disk, a path needs to be provided.
The paths are collected one step earlier.
```v oksyntax
import v.parser
path := ''
// table, pref and scope needs to be passed as reference
parsed_file := parser.parse_file(path, table, .parse_comments, &pref, &scope)
```
## Parse a set of files
If you have a batch of paths available which should be parsed,
there is also a function which does all the work.
```v oksyntax
import v.parser
paths := ['']
// table, pref and scope needs to be passed as reference
parsed_files := parser.parse_files(paths, table, &pref, &scope)
```
## Parse imports
A file often contains imports. These imports might need to be parsed as well.
The builder contains a method which does this: `Builder.parse_imports`.
If the module which is imported isn't parsed already,
you have to collect it relatively from the main file.
For this the `ast.File` contains a list of imports.
Those imports needs to be found on disk.
`.` is just replaced with seperators in the relative location of the main file.
Then all files from that directory are collected and parsed again like the previous steps explained.
## Checking AST
A new checker is created:
```v oksyntax
import v.checker
mut checker := checker.new_checker(table, &pref)
```
After checking your files in `checker.errors` and `checker.warnings` you can see the results.
### Check `ast.File`
```v oksyntax
checker.check(parsed_file)
```
### Check a list of `ast.File`
```v oksyntax
checker.check_files(parsed_files)
```
## Generate target from AST
Generating C code works just as this:
```v oksyntax
import v.gen.c
res := c.gen(parsed_files, table, &pref)
```