From a60b381d5e0e948b85e9c260f5a6ea64e72c6ae7 Mon Sep 17 00:00:00 2001 From: jeffmikels Date: Wed, 5 Jan 2022 11:06:08 -0500 Subject: [PATCH] docs: adding skeleton README.md files for all vlib modules (#13034) --- vlib/README.md | 1 + vlib/arrays/README.md | 4 ++ vlib/benchmark/README.md | 8 +++- vlib/bitfield/README.md | 7 ++- vlib/builtin/README.md | 7 +++ vlib/cli/README.md | 8 ++++ vlib/clipboard/README.md | 5 ++ vlib/compress/README.md | 4 ++ vlib/compress/zlib/README.md | 16 +++++++ vlib/crypto/README.md | 5 ++ vlib/darwin/README.md | 4 ++ vlib/dl/README.md | 6 +++ vlib/dl/dl.v | 7 ++- vlib/dl/dl_nix.c.v | 7 ++- vlib/dl/dl_windows.c.v | 7 ++- vlib/encoding/README.md | 4 ++ vlib/flag/README.md | 13 +++-- vlib/fontstash/README.md | 5 ++ vlib/gg/README.md | 35 ++++++++++++++ vlib/gx/README.md | 6 +++ vlib/hash/README.md | 7 +++ vlib/io/README.md | 3 ++ vlib/js/README.md | 4 ++ vlib/jsdom/README.md | 8 ++++ vlib/json/README.md | 36 ++++++++++++++ vlib/log/README.md | 5 ++ vlib/math/README.md | 4 ++ vlib/net/README.md | 5 ++ vlib/os/README.md | 5 ++ vlib/pg/README.md | 7 ++- vlib/picoev/README.md | 4 ++ vlib/picohttpparser/README.md | 4 ++ vlib/rand/README.md | 30 ++++++------ vlib/readline/README.md | 2 +- vlib/regex/README.md | 90 ++++++++++++++++++----------------- vlib/runtime/README.md | 7 +++ vlib/semver/README.md | 74 ++++++++++++++-------------- vlib/sokol/README.md | 6 +++ vlib/sqlite/README.md | 9 ++++ vlib/stbi/README.md | 4 ++ vlib/strconv/README.md | 3 ++ vlib/strings/README.md | 3 ++ vlib/sync/README.md | 3 ++ vlib/szip/README.md | 9 ++++ vlib/term/README.md | 14 +++--- vlib/time/README.md | 17 +++++++ vlib/toml/README.md | 2 +- vlib/v/README.md | 9 ++++ vlib/x/README.md | 8 ++++ 49 files changed, 416 insertions(+), 125 deletions(-) create mode 100644 vlib/README.md create mode 100644 vlib/arrays/README.md create mode 100644 vlib/builtin/README.md create mode 100644 vlib/clipboard/README.md create mode 100644 vlib/compress/README.md create mode 100644 vlib/compress/zlib/README.md create mode 100644 vlib/crypto/README.md create mode 100644 vlib/darwin/README.md create mode 100644 vlib/dl/README.md create mode 100644 vlib/encoding/README.md create mode 100644 vlib/fontstash/README.md create mode 100644 vlib/gg/README.md create mode 100644 vlib/gx/README.md create mode 100644 vlib/hash/README.md create mode 100644 vlib/io/README.md create mode 100644 vlib/js/README.md create mode 100644 vlib/jsdom/README.md create mode 100644 vlib/json/README.md create mode 100644 vlib/log/README.md create mode 100644 vlib/math/README.md create mode 100644 vlib/net/README.md create mode 100644 vlib/os/README.md create mode 100644 vlib/picoev/README.md create mode 100644 vlib/picohttpparser/README.md create mode 100644 vlib/runtime/README.md create mode 100644 vlib/sokol/README.md create mode 100644 vlib/stbi/README.md create mode 100644 vlib/strconv/README.md create mode 100644 vlib/strings/README.md create mode 100644 vlib/sync/README.md create mode 100644 vlib/szip/README.md create mode 100644 vlib/time/README.md create mode 100644 vlib/x/README.md diff --git a/vlib/README.md b/vlib/README.md new file mode 100644 index 000000000..137d7167d --- /dev/null +++ b/vlib/README.md @@ -0,0 +1 @@ +# Documentation for all included modules... diff --git a/vlib/arrays/README.md b/vlib/arrays/README.md new file mode 100644 index 000000000..e5bee5466 --- /dev/null +++ b/vlib/arrays/README.md @@ -0,0 +1,4 @@ +## Description: + +`arrays` provides some generic functions for processing arrays. + diff --git a/vlib/benchmark/README.md b/vlib/benchmark/README.md index 6f4f7dbdc..74c78c82b 100644 --- a/vlib/benchmark/README.md +++ b/vlib/benchmark/README.md @@ -1,4 +1,10 @@ -Example usage of this module: +## Description: + +`benchmark` provides an easy way to measure how fast a piece of code is, +and produce a readable report about it. + +## Example usage of this module: + ```v import benchmark diff --git a/vlib/bitfield/README.md b/vlib/bitfield/README.md index 8b82c4cc8..8585b7cdb 100644 --- a/vlib/bitfield/README.md +++ b/vlib/bitfield/README.md @@ -1,8 +1,7 @@ -# Quickstart +## Description: -`bitfield` is a module for -manipulating arrays of bits, i.e. series of zeroes and ones spread across an -array of storage units (unsigned 32-bit integers). +`bitfield` is a module for manipulating arrays of bits, i.e. series of zeroes +and ones spread across an array of storage units (unsigned 32-bit integers). ## BitField structure diff --git a/vlib/builtin/README.md b/vlib/builtin/README.md new file mode 100644 index 000000000..f692ef44c --- /dev/null +++ b/vlib/builtin/README.md @@ -0,0 +1,7 @@ +## Description: + +`builtin` is a module that is implicitly imported by every V program. +It implements the builtin V types `array`, `string`, `map`. +It also implements builtin functions like `println`, `eprintln`, `malloc`, +`panic`, `print_backtrace`. + diff --git a/vlib/cli/README.md b/vlib/cli/README.md index 93d8d62cd..7712754a0 100644 --- a/vlib/cli/README.md +++ b/vlib/cli/README.md @@ -1,3 +1,11 @@ +## Description: + +`cli` is a command line option parser, that supports +declarative subcommands, each having separate set of options. + +See also the `flag` module, for a simpler command line option parser, +that supports only options. + Usage example: ```v diff --git a/vlib/clipboard/README.md b/vlib/clipboard/README.md new file mode 100644 index 000000000..c79483fa4 --- /dev/null +++ b/vlib/clipboard/README.md @@ -0,0 +1,5 @@ +## Description: + +`clipboard` provides access to the platform's clipboard mechanism. +You can use it to read from the system clipboard, and write to it +from your applications. diff --git a/vlib/compress/README.md b/vlib/compress/README.md new file mode 100644 index 000000000..158c2c432 --- /dev/null +++ b/vlib/compress/README.md @@ -0,0 +1,4 @@ +## Description: + +`compress` is a namespace for (multiple) compression algorithms supported by V. +At the moment, only `compress.zlib` is implemented. diff --git a/vlib/compress/zlib/README.md b/vlib/compress/zlib/README.md new file mode 100644 index 000000000..1b9f0495b --- /dev/null +++ b/vlib/compress/zlib/README.md @@ -0,0 +1,16 @@ +## Description: + +`compress.zlib` implements zlib compression and decompression of binary data. + +## Examples: + +```v +import compress.zlib + +fn main() { + uncompressed := 'Hello world!' + compressed := zlib.compress(uncompressed.bytes()) ? + decompressed := zlib.decompress(compressed) ? + assert decompressed == uncompressed.bytes() +} +``` diff --git a/vlib/crypto/README.md b/vlib/crypto/README.md new file mode 100644 index 000000000..2d40d7815 --- /dev/null +++ b/vlib/crypto/README.md @@ -0,0 +1,5 @@ +## Description: + +`crypto` is a namespace for multiple crypto algorithms. + +The implementations here are loosely based on [Go's crypto package](https://pkg.go.dev/crypto). diff --git a/vlib/darwin/README.md b/vlib/darwin/README.md new file mode 100644 index 000000000..2fd56aab5 --- /dev/null +++ b/vlib/darwin/README.md @@ -0,0 +1,4 @@ +## Description: + +`darwin` is a deprecated module that will be removed soon. +Do not rely on it. diff --git a/vlib/dl/README.md b/vlib/dl/README.md new file mode 100644 index 000000000..e6e5d2d46 --- /dev/null +++ b/vlib/dl/README.md @@ -0,0 +1,6 @@ +## Description: + +`dl` can be used to Dynamically Load a library during runtime. +It is a thin wrapper over `LoadLibrary` on Windows, and `dlopen` on Unix. + +Using it, you can implement a plugin system for your application. diff --git a/vlib/dl/dl.v b/vlib/dl/dl.v index 04ad16ba4..2cb59fbf2 100644 --- a/vlib/dl/dl.v +++ b/vlib/dl/dl.v @@ -1,9 +1,8 @@ module dl -pub const ( - version = 1 - dl_ext = get_shared_library_extension() -) +pub const version = 1 + +pub const dl_ext = get_shared_library_extension() // get_shared_library_extension returns the platform dependent shared library extension // i.e. .dll on windows, .so on most unixes, .dylib on macos. diff --git a/vlib/dl/dl_nix.c.v b/vlib/dl/dl_nix.c.v index 40f63b542..66c8f6918 100644 --- a/vlib/dl/dl_nix.c.v +++ b/vlib/dl/dl_nix.c.v @@ -6,10 +6,9 @@ $if linux { #flag -ldl } -pub const ( - rtld_now = C.RTLD_NOW - rtld_lazy = C.RTLD_LAZY -) +pub const rtld_now = C.RTLD_NOW + +pub const rtld_lazy = C.RTLD_LAZY fn C.dlopen(filename &char, flags int) voidptr diff --git a/vlib/dl/dl_windows.c.v b/vlib/dl/dl_windows.c.v index b6ae2fcda..85de31eac 100644 --- a/vlib/dl/dl_windows.c.v +++ b/vlib/dl/dl_windows.c.v @@ -1,9 +1,8 @@ module dl -pub const ( - rtld_now = 0 - rtld_lazy = 0 -) +pub const rtld_now = 0 + +pub const rtld_lazy = 0 fn C.LoadLibrary(libfilename &u16) voidptr diff --git a/vlib/encoding/README.md b/vlib/encoding/README.md new file mode 100644 index 000000000..7a711f583 --- /dev/null +++ b/vlib/encoding/README.md @@ -0,0 +1,4 @@ +## Description: + +`encoding` is a namespace for different formats/protocols encoding/decoding, +like `csv`, `utf8`, `base64` etc. diff --git a/vlib/flag/README.md b/vlib/flag/README.md index 87c94e604..b840a9db5 100644 --- a/vlib/flag/README.md +++ b/vlib/flag/README.md @@ -1,10 +1,17 @@ -The `flag` module helps command-line flag parsing. -Main features are: +## Description: + +The `flag` module is a command line option parser. +Its main features are: +- simplicity of usage. - parses flags like `-f` or '--flag' or '--stuff=things' or '--things stuff'. - handles bool, int, float and string args. -- can print usage information listing all the declrared flags. +- can print usage information listing all the declared flags. - handles unknown arguments as error. +See also the `cli` module, for a more complex command line option parser, +that supports declaring multiple subcommands each having a separate set of +options. + Usage example: ```v diff --git a/vlib/fontstash/README.md b/vlib/fontstash/README.md new file mode 100644 index 000000000..099f4dd0c --- /dev/null +++ b/vlib/fontstash/README.md @@ -0,0 +1,5 @@ +## Description: + +`fontstash` is a thin wrapper over , +which in turn is a light-weight online font texture atlas builder written in C. +It uses stb_truetype to render fonts on demand to a texture atlas diff --git a/vlib/gg/README.md b/vlib/gg/README.md new file mode 100644 index 000000000..a9aeb8894 --- /dev/null +++ b/vlib/gg/README.md @@ -0,0 +1,35 @@ +## Description: + +`gg` is V's simple graphics module. +It is currently implemented using `sokol`, and makes easy creating +apps that just need a way to draw simple 2D shapes, and to react to +user's keyboard/mouse input. + +## Example: + +```v +module main + +import gg +import gx + +fn main() { + mut context := gg.new_context( + bg_color: gx.rgb(174, 198, 255) + width: 600 + height: 400 + window_title: 'Polygons' + frame_fn: frame + ) + context.run() +} + +fn frame(mut ctx gg.Context) { + ctx.begin() + ctx.draw_convex_poly([f32(100.0), 100.0, 200.0, 100.0, 300.0, 200.0, 200.0, 300.0, 100.0, 300.0], + gx.blue) + ctx.draw_poly_empty([f32(50.0), 50.0, 70.0, 60.0, 90.0, 80.0, 70.0, 110.0], gx.black) + ctx.draw_triangle_filled(450, 142, 530, 280, 370, 280, gx.red) + ctx.end() +} +``` diff --git a/vlib/gx/README.md b/vlib/gx/README.md new file mode 100644 index 000000000..d286fb942 --- /dev/null +++ b/vlib/gx/README.md @@ -0,0 +1,6 @@ +## Description: + +`gx` is a complementary module to `gg`, that just provides +some predefined graphical color names/operations. + +NB: `gx` is going to be merged with `gg` soon. diff --git a/vlib/hash/README.md b/vlib/hash/README.md new file mode 100644 index 000000000..075bd85f6 --- /dev/null +++ b/vlib/hash/README.md @@ -0,0 +1,7 @@ +## Description: + +`hash` provides a way to hash binary data, i.e. produce a shorter value, +that is highly content dependent, so even slightly different content will +produce widely different hashes. + +Hash functions are useful for implementing maps, caches etc. diff --git a/vlib/io/README.md b/vlib/io/README.md new file mode 100644 index 000000000..5ff1887f8 --- /dev/null +++ b/vlib/io/README.md @@ -0,0 +1,3 @@ +## Description: + +`io` provides common interfaces for buffered reading/writing of data. diff --git a/vlib/js/README.md b/vlib/js/README.md new file mode 100644 index 000000000..a3b91ce9d --- /dev/null +++ b/vlib/js/README.md @@ -0,0 +1,4 @@ +## Description: + +`js` is frontend/browser specific module, that provides access to global JS functions. +NB: it *only* works with the JS backend. diff --git a/vlib/jsdom/README.md b/vlib/jsdom/README.md new file mode 100644 index 000000000..bbc3456a7 --- /dev/null +++ b/vlib/jsdom/README.md @@ -0,0 +1,8 @@ +## Description: + +`jsdom` is frontend/browser specific module, that provides access to the DOM. +NB: it *only* works with the JS backend. + +## Examples: +Run `v -b js_browser examples/js_dom_draw/draw.js.v`, +then open `examples/js_dom_draw/index.html` in your browser. diff --git a/vlib/json/README.md b/vlib/json/README.md new file mode 100644 index 000000000..3a7e468f9 --- /dev/null +++ b/vlib/json/README.md @@ -0,0 +1,36 @@ +## Description: + +`json` provides encoding/decoding of V data structures to/from JSON. + +## Examples: + +```v +import json + +enum JobTitle { + manager + executive + worker +} + +struct Employee { + name string + age int + salary f32 + title JobTitle +} + +fn main() { + x := Employee{'Peter', 28, 95000.5, .worker} + println(x) + // + s := json.encode(x) + println('Employee x: $s') + assert s == '{"name":"Peter","age":28,"salary":95000.5,"title":2}' + // + y := json.decode(Employee, s) ? + // + println(y) + assert y == x +} +``` diff --git a/vlib/log/README.md b/vlib/log/README.md new file mode 100644 index 000000000..2c278b14d --- /dev/null +++ b/vlib/log/README.md @@ -0,0 +1,5 @@ +## Description: + +`log` provides your application logging services. +You can log to file or to the console and use different +logging levels, so that you are not overwhelmed by the logs. diff --git a/vlib/math/README.md b/vlib/math/README.md new file mode 100644 index 000000000..2b78b3bb9 --- /dev/null +++ b/vlib/math/README.md @@ -0,0 +1,4 @@ +## Description: + +`math` provides commonly used mathematical functions for +trigonometry, logarithms, etc. diff --git a/vlib/net/README.md b/vlib/net/README.md new file mode 100644 index 000000000..3ee7b6e3c --- /dev/null +++ b/vlib/net/README.md @@ -0,0 +1,5 @@ +## Description: + +`net` provides networking functions. It is mostly a wrapper to BSD sockets, +so you can listen on a port, connect to remote TCP/UDP services, and +communicate with them. diff --git a/vlib/os/README.md b/vlib/os/README.md new file mode 100644 index 000000000..82ed0b4f4 --- /dev/null +++ b/vlib/os/README.md @@ -0,0 +1,5 @@ +## Description: + +`os` provides common OS/platform independent functions for accessing +command line arguments, reading/writing files, listing folders, +handling processes etc. diff --git a/vlib/pg/README.md b/vlib/pg/README.md index bcdae9845..1d1fce277 100644 --- a/vlib/pg/README.md +++ b/vlib/pg/README.md @@ -1,5 +1,10 @@ +## Description: + +`pg` is a wrapper for the PostgreSQL client library. It provides access +to a PostgreSQL DB server. + 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. +your system. 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 or you need extra help, [go here](https://www.postgresql.org/download/). diff --git a/vlib/picoev/README.md b/vlib/picoev/README.md new file mode 100644 index 000000000..1934162c2 --- /dev/null +++ b/vlib/picoev/README.md @@ -0,0 +1,4 @@ +## Description: + +`picoev` is a thin wrapper over [picoev](https://github.com/kazuho/picoev), +which in turn is "A tiny, lightning fast event loop for network applications". diff --git a/vlib/picohttpparser/README.md b/vlib/picohttpparser/README.md new file mode 100644 index 000000000..5b2c75675 --- /dev/null +++ b/vlib/picohttpparser/README.md @@ -0,0 +1,4 @@ +## Description: + +`picohttpparser` is a thin wrapper over [picohttpparser](https://github.com/h2o/picohttpparser), +which in turn is "a tiny, primitive, fast HTTP request/response parser." diff --git a/vlib/rand/README.md b/vlib/rand/README.md index b5b917f09..211dfbaa2 100644 --- a/vlib/rand/README.md +++ b/vlib/rand/README.md @@ -1,4 +1,4 @@ -# Quickstart +# Description The V `rand` module provides two main ways in which users can generate pseudorandom numbers: @@ -29,27 +29,27 @@ For arrays, see `rand.util`. # General Background -A PRNG is a Pseudo Random Number Generator. -Computers cannot generate truly random numbers without an external source of noise or entropy. -We can use algorithms to generate sequences of seemingly random numbers, -but their outputs will always be deterministic. +A PRNG is a Pseudo Random Number Generator. +Computers cannot generate truly random numbers without an external source of noise or entropy. +We can use algorithms to generate sequences of seemingly random numbers, +but their outputs will always be deterministic. This is often useful for simulations that need the same starting seed. -If you need truly random numbers that are going to be used for cryptography, +If you need truly random numbers that are going to be used for cryptography, use the `crypto.rand` module. # Guaranteed functions -The following 21 functions are guaranteed to be supported by `rand` +The following 21 functions are guaranteed to be supported by `rand` as well as the individual PRNGs. -- `seed(seed_data)` where `seed_data` is an array of `u32` values. - Different generators require different number of bits as the initial seed. - The smallest is 32-bits, required by `sys.SysRNG`. +- `seed(seed_data)` where `seed_data` is an array of `u32` values. + Different generators require different number of bits as the initial seed. + The smallest is 32-bits, required by `sys.SysRNG`. Most others require 64-bits or 2 `u32` values. - `u32()`, `u64()`, `int()`, `i64()`, `f32()`, `f64()` - `u32n(max)`, `u64n(max)`, `intn(max)`, `i64n(max)`, `f32n(max)`, `f64n(max)` -- `u32_in_range(min, max)`, `u64_in_range(min, max)`, `int_in_range(min, max)`, +- `u32_in_range(min, max)`, `u64_in_range(min, max)`, `int_in_range(min, max)`, `i64_in_range(min, max)`, `f32_in_range(min, max)`, `f64_in_range(min, max)` - `int31()`, `int63()` @@ -59,7 +59,7 @@ PRNG, you can can change the global RNG to do so. # Seeding Functions -All the generators are time-seeded. +All the generators are time-seeded. The helper functions publicly available in `rand.seed` module are: 1. `time_seed_array()` - returns a `[]u32` that can be directly plugged into the `seed()` functions. @@ -69,8 +69,8 @@ The helper functions publicly available in `rand.seed` module are: # Caveats Note that the `sys.SysRNG` struct (in the C backend) uses `C.srand()` which sets the seed globally. -Consequently, all instances of the RNG will be affected. -This problem does not arise for the other RNGs. +Consequently, all instances of the RNG will be affected. +This problem does not arise for the other RNGs. A workaround (if you _must_ use the libc RNG) is to: 1. Seed the first instance. @@ -83,5 +83,5 @@ A workaround (if you _must_ use the libc RNG) is to: Please note that [math interval](https://en.wikipedia.org/wiki/Interval_(mathematics)#Including_or_excluding_endpoints) 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`. diff --git a/vlib/readline/README.md b/vlib/readline/README.md index 24a2b527d..c4bc9193a 100644 --- a/vlib/readline/README.md +++ b/vlib/readline/README.md @@ -1,4 +1,4 @@ -# Readline +# Description The `readline` module lets you await and read user input from a terminal in an easy and structured manner. diff --git a/vlib/regex/README.md b/vlib/regex/README.md index 067f17d80..0b481ad95 100644 --- a/vlib/regex/README.md +++ b/vlib/regex/README.md @@ -1,4 +1,8 @@ -# V RegEx (Regular expression) 1.0 alpha +# Description +`regex` is a small but powerful regular expression library, +written in pure V. + +NB: `regex` is *not* PCRE compatible. [TOC] @@ -9,13 +13,13 @@ are valid for all the `regex` module features: 1. The matching stops at the end of the string, *not* at newline characters. -2. The basic atomic elements of this regex engine are the tokens. +2. The basic atomic elements of this regex engine are the tokens. In a query string a simple character is a token. ## Differences with PCRE: -NB: We must point out that the **V-Regex module is not PCRE compliant** and thus +NB: We must point out that the **V-Regex module is not PCRE compliant** and thus some behaviour will be different. This difference is due to the V philosophy, to have one way and keep it simple. @@ -24,13 +28,13 @@ The main differences can be summarized in the following points: - The basic element **is the token not the sequence of symbols**, and the most simple token, is a single character. -- `|` **the OR operator acts on tokens,** for example `abc|ebc` is not +- `|` **the OR operator acts on tokens,** for example `abc|ebc` is not `abc` OR `ebc`. Instead it is evaluated like `ab`, followed by `c OR e`, followed by `bc`, because the **token is the base element**, not the sequence of symbols. Note: **Two char classes with an `OR` in the middle is a syntax error.** -- The **match operation stops at the end of the string**. It does *NOT* stop +- The **match operation stops at the end of the string**. It does *NOT* stop at new line characters. @@ -54,7 +58,7 @@ This token is a simple single character like `a` or `b` etc. ### Char class (cc) -The character classes match all the chars specified inside. Use square +The character classes match all the chars specified inside. Use square brackets `[ ]` to enclose them. The sequence of the chars in the character class, is evaluated with an OR op. @@ -65,7 +69,7 @@ but it doesn't match `C` or `z`. Inside a cc, it is possible to specify a "range" of characters, for example `[ad-h]` is equivalent to writing `[adefgh]`. -A cc can have different ranges at the same time, for example `[a-zA-z0-9]` +A cc can have different ranges at the same time, for example `[a-zA-z0-9]` matches all the latin lowercase, uppercase and numeric characters. It is possible to negate the meaning of a cc, using the caret char at the @@ -80,13 +84,13 @@ 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 a backslash in the cc, for example `[\-_\d\a]` will match: `-` minus, - `_` underscore, + `_` underscore, `\d` numeric chars, `\a` lower case chars. ### Meta-chars -A meta-char is specified by a backslash, before a character. +A meta-char is specified by a backslash, before a character. For example `\w` is the meta-char `w`. A meta-char can match different types of characters. @@ -130,7 +134,7 @@ The dot is a particular meta-char, that matches "any char". It is simpler to explain it with an example: -Suppose you have `abccc ddeef` as a source string, that you want to parse +Suppose you have `abccc ddeef` as a source string, that you want to parse with a regex. The following table show the query strings and the result of parsing source string. @@ -151,14 +155,14 @@ The token `|`, means a logic OR operation between two consecutive tokens, i.e. `a|b` matches a character that is `a` or `b`. 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`. -NB: ** unlike in PCRE, the OR operation works at token level!** +NB: ** unlike in PCRE, the OR operation works at token level!** It doesn't work at concatenation level! NB2: **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. The OR operation works only for `c|b`, not at char concatenation level. @@ -177,7 +181,7 @@ outer round brackets `(...)+`. This group has a quantifier `+`, that say to match its content *at least one time*. Then we have a simple char token `c`, and a second group `#1`: `(pa)+`. -This group also tries to match the sequence `pa`, *at least one time*, +This group also tries to match the sequence `pa`, *at least one time*, as specified by the `+` quantifier. Then, we have another simple token `z` and another simple token ` ?`, @@ -190,7 +194,7 @@ can match `cpaz cpapaz cpapapaz` . In this implementation the groups are "capture groups". This means that the last temporal result for each group, can be retrieved from the `RE` struct. -The "capture groups" are stored as indexes in the field `groups`, +The "capture groups" are stored as indexes in the field `groups`, that is an `[]int` inside the `RE` struct. **example:** @@ -263,14 +267,14 @@ fn convert_html_rgb(in_col string) u32 { } ``` -Others utility functions are `get_group_by_id` and `get_group_bounds_by_id` +Others utility functions are `get_group_by_id` and `get_group_bounds_by_id` that get directly the string of a group using its `id`: ```v ignore txt := "my used string...." for g_index := 0; g_index < re.group_count ; g_index++ { println("#${g_index} [${re.get_group_by_id(txt, g_index)}] \ - bounds: ${re.get_group_bounds_by_id(g_index)}") + bounds: ${re.get_group_bounds_by_id(g_index)}") } ``` @@ -294,8 +298,8 @@ The `.group_csave` array will be filled then, following this logic: `re.group_csave[1+n*3]` - start index in the source string of the saved group `re.group_csave[1+n*3]` - end index in the source string of the saved group -The regex will save groups, until it finishes, or finds that the array has no -more space. If the space ends, no error is raised, and further records will +The regex will save groups, until it finishes, or finds that the array has no +more space. If the space ends, no error is raised, and further records will not be saved. ```v ignore @@ -355,11 +359,11 @@ This regex module supports partially the question mark `?` PCRE syntax for group `(?:abcd)` **non capturing group**: the content of the group will not be saved. -`(?Pabcdef)` **named group:** the group content is saved and labeled +`(?Pabcdef)` **named group:** the group content is saved and labeled as `mygroup`. -The label of the groups is saved in the `group_map` of the `RE` struct, -that is a map from `string` to `int`, where the value is the index in +The label of the groups is saved in the `group_map` of the `RE` struct, +that is a map from `string` to `int`, where the value is the index in `group_csave` list of indexes. Here is an example for how to use them: @@ -447,7 +451,7 @@ These functions are helpers to query the captured groups ```v ignore // get_group_bounds_by_name get a group boundaries by its name -pub fn (re RE) get_group_bounds_by_name(group_name string) (int, int) +pub fn (re RE) get_group_bounds_by_name(group_name string) (int, int) // get_group_by_name get a group string by its name pub fn (re RE) get_group_by_name(group_name string) string @@ -481,15 +485,15 @@ re.flag = regex.f_bin - `f_bin`: parse a string as bytes, utf-8 management disabled. -- `f_efm`: exit on the first char matches in the query, used by the +- `f_efm`: exit on the first char matches in the query, used by the find function. - + - `f_ms`: matches only if the index of the start match is 0, same as `^` at the start of the query string. - + - `f_me`: matches only if the end index of the match is the last char of the input string, same as `$` end of query string. - + - `f_nl`: stop the matching if found a new line char `\n` or `\r` ## Functions @@ -561,7 +565,7 @@ There are the following find and replace functions: pub fn (re mut RE) find(in_txt string) (int,int) // find_all find all the "non overlapping" occurrences of the matching pattern -// return a list of start end indexes like: [3,4,6,8] +// return a list of start end indexes like: [3,4,6,8] // the matches are [3,4] and [6,8] pub fn (re mut RE) find_all(in_txt string) []int @@ -574,7 +578,7 @@ pub fn (mut re RE) find_all_str(in_txt string) []string #### Replace functions ```v ignore -// replace return a string where the matches are replaced with the repl_str string, +// replace return a string where the matches are replaced with the repl_str string, // this function support groups in the replace string pub fn (re mut RE) replace(in_txt string, repl string) string ``` @@ -617,7 +621,7 @@ pub fn (mut re RE) replace_n(in_txt string, repl_str string, count int) string #### Custom replace function For complex find and replace operations, you can use `replace_by_fn` . -The `replace_by_fn`, uses a custom replace callback function, thus +The `replace_by_fn`, uses a custom replace callback function, thus allowing customizations. The custom callback function is called for every non overlapped find. @@ -629,7 +633,7 @@ The custom callback function must be of the type: // start index of the start of the match in in_txt // end index of the end of the match in in_txt // --- the match is in in_txt[start..end] --- -fn (re RE, in_txt string, start int, end int) string +fn (re RE, in_txt string, start int, end int) string ``` The following example will clarify its usage: @@ -642,7 +646,7 @@ fn my_repl(re regex.RE, in_txt string, start int, end int) string { g0 := re.get_group_by_id(in_txt, 0) g1 := re.get_group_by_id(in_txt, 1) g2 := re.get_group_by_id(in_txt, 2) - return "*$g0*$g1*$g2*" + return "*$g0*$g1*$g2*" } fn main(){ @@ -650,7 +654,7 @@ fn main(){ query := r"(.)(\A\w+)(.)" mut re := regex.regex_opt(query) or { panic(err) } - + result := re.replace_by_fn(txt, my_repl) println(result) } @@ -803,13 +807,13 @@ fn main(){ query := r"(?Phttps?)|(?Pftps?)://(?P[\w_]+.)+" mut re := regex.regex_opt(query) or { panic(err) } - + start, end := re.match_string(txt) if start >= 0 { println("Match ($start, $end) => [${txt[start..end]}]") for g_index := 0; g_index < re.group_count ; g_index++ { println("#${g_index} [${re.get_group_by_id(txt, g_index)}] \ - bounds: ${re.get_group_bounds_by_id(g_index)}") + bounds: ${re.get_group_bounds_by_id(g_index)}") } for name in re.group_map.keys() { println("group:'$name' \t=> [${re.get_group_by_name(txt, name)}] \ @@ -831,17 +835,17 @@ fn main(){ // init regex mut re := regex.RE{} // max program length, can not be longer then the query - re.prog = []regex.Token {len: query.len + 1} + re.prog = []regex.Token {len: query.len + 1} // can not be more char class the the length of the query - re.cc = []regex.CharClass{len: query.len} + re.cc = []regex.CharClass{len: query.len} re.prog = []regex.Token {len: query.len+1} // enable continuos group saving - re.group_csave_flag = true + re.group_csave_flag = true // set max 128 group nested - re.group_max_nested = 128 - // we can't have more groups than the half of the query legth - re.group_max = query.len>>1 - + re.group_max_nested = 128 + // we can't have more groups than the half of the query legth + re.group_max = query.len>>1 + // compile the query re.compile_opt(query) or { panic(err) } @@ -870,7 +874,7 @@ fn main(){ println("Match ($start, $end) => [${txt[start..end]}]") for g_index := 0; g_index < re.group_count ; g_index++ { println("#${g_index} [${re.get_group_by_id(txt, g_index)}] \ - bounds: ${re.get_group_bounds_by_id(g_index)}") + bounds: ${re.get_group_bounds_by_id(g_index)}") } for name in re.group_map.keys() { println("group:'$name' \t=> [${re.get_group_by_name(txt, name)}] \ diff --git a/vlib/runtime/README.md b/vlib/runtime/README.md new file mode 100644 index 000000000..6d3fc226a --- /dev/null +++ b/vlib/runtime/README.md @@ -0,0 +1,7 @@ +## Description: + +`runtime` provides access to functions describing the current platform: +- whether it is 32bit or 64bit +- how many CPUs/cores are available +- whether the platform is little endian or big endian +- etc. diff --git a/vlib/semver/README.md b/vlib/semver/README.md index 2f3f9bb8c..e5a7a2beb 100644 --- a/vlib/semver/README.md +++ b/vlib/semver/README.md @@ -1,37 +1,37 @@ -# semver - -A library for working with versions in [semver][semver] format. - -## Usage - -```v -import semver - -fn main() { - ver1 := semver.from('1.2.4') or { - println('Invalid version') - return - } - ver2 := semver.from('2.3.4') or { - println('Invalid version') - return - } - println(ver1.gt(ver2)) - println(ver2.gt(ver1)) - println(ver1.satisfies('>=1.1.0 <2.0.0')) - println(ver2.satisfies('>=1.1.0 <2.0.0')) - println(ver2.satisfies('>=1.1.0 <2.0.0 || >2.2.0')) -} -``` - -``` -false -true -true -false -true -``` - -For more details see `semver.v` file. - -[semver]: https://semver.org/ +## Description: + +`semver` is a library for processing versions, that use the [semver][semver] format. + +## Examples: + +```v +import semver + +fn main() { + ver1 := semver.from('1.2.4') or { + println('Invalid version') + return + } + ver2 := semver.from('2.3.4') or { + println('Invalid version') + return + } + println(ver1.gt(ver2)) + println(ver2.gt(ver1)) + println(ver1.satisfies('>=1.1.0 <2.0.0')) + println(ver2.satisfies('>=1.1.0 <2.0.0')) + println(ver2.satisfies('>=1.1.0 <2.0.0 || >2.2.0')) +} +``` + +``` +false +true +true +false +true +``` + +For more details see `semver.v` file. + +[semver]: https://semver.org/ diff --git a/vlib/sokol/README.md b/vlib/sokol/README.md new file mode 100644 index 000000000..ac81fb343 --- /dev/null +++ b/vlib/sokol/README.md @@ -0,0 +1,6 @@ +## Description: + +`sokol` is a thin wrapper around [sokol](https://github.com/floooh/sokol), +which in turn is a library of "Simple STB-style cross-platform libraries +for C and C++, written in C.", that provide access to graphics/audio/input +processing. diff --git a/vlib/sqlite/README.md b/vlib/sqlite/README.md index d7462c650..49c153284 100644 --- a/vlib/sqlite/README.md +++ b/vlib/sqlite/README.md @@ -1,5 +1,14 @@ +## Description: + +`sqlite` is a thin wrapper for [the SQLite library](https://sqlite.org/), which in turn is +"a C-language library that implements a small, fast, self-contained, +high-reliability, full-featured, SQL database engine." + # Install SQLite Dependency +Before you can use this module, you must first have the SQLite development +library installed on your system. + **Fedora 31**: `sudo dnf -y install sqlite-devel` diff --git a/vlib/stbi/README.md b/vlib/stbi/README.md new file mode 100644 index 000000000..50954dde6 --- /dev/null +++ b/vlib/stbi/README.md @@ -0,0 +1,4 @@ +## Description: + +`stbi` is a thin wrapper around [stb](https://github.com/nothings/stb)'s stb_image.h, which in turn +is "a public domain image loader" for popular graphics image file formats. diff --git a/vlib/strconv/README.md b/vlib/strconv/README.md new file mode 100644 index 000000000..574afc132 --- /dev/null +++ b/vlib/strconv/README.md @@ -0,0 +1,3 @@ +## Description: + +`strconv` provides functions for converting strings to numbers and numbers to strings. diff --git a/vlib/strings/README.md b/vlib/strings/README.md new file mode 100644 index 000000000..9fce34918 --- /dev/null +++ b/vlib/strings/README.md @@ -0,0 +1,3 @@ +## Description: + +`strings` provides utilities for efficiently processing large strings. diff --git a/vlib/sync/README.md b/vlib/sync/README.md new file mode 100644 index 000000000..eee85f147 --- /dev/null +++ b/vlib/sync/README.md @@ -0,0 +1,3 @@ +## Description: + +`sync` provides cross platform handling of concurrency primitives. diff --git a/vlib/szip/README.md b/vlib/szip/README.md new file mode 100644 index 000000000..4d4f9528c --- /dev/null +++ b/vlib/szip/README.md @@ -0,0 +1,9 @@ +## Description: + +`szip` is a thin wrapper around [miniz.h](https://github.com/richgel999/miniz), +which in turn is "Single C source file zlib-replacement library, +originally from code.google.com/p/miniz". +It provides utility functions for reading/writing .zip files. + +*TODO* +Merge/move under vlib/compress/zip . diff --git a/vlib/term/README.md b/vlib/term/README.md index 589013f33..3beeab681 100644 --- a/vlib/term/README.md +++ b/vlib/term/README.md @@ -1,11 +1,11 @@ -# Quickstart +## Description -The V `term` module is a module designed to provide the building blocks -for building very simple TUI apps. -For more complex apps, you should really look at the `term.input` module, -as it includes terminal events, is easier to use and is much more performant for large draws. +The `term` module is designed to provide the building blocks for building +very simple TUI apps. For more complex apps, you should really look at the +`term.input` module, as it includes terminal events, is easier to use and +is much more performant for large draws. -# Use +## Usage You can use the `term` module to either color the output on a terminal or to decide on where to put the output in your terminal. @@ -39,7 +39,7 @@ fn main() { This simple program covers many of the principal aspects of the `term ` module. -# API +## API Here are some functions you should be aware of in the `term `module: diff --git a/vlib/time/README.md b/vlib/time/README.md new file mode 100644 index 000000000..ffc1f448f --- /dev/null +++ b/vlib/time/README.md @@ -0,0 +1,17 @@ +## Description: + +`time` provides utilities for working with time and dates: +- parsing of time values expressed in one of the commonly used standard time/date formats +- formatting of time values +- arithmetic over times/durations +- converting between local time and UTC (timezone support) +- stop watches for accurately measuring time durations +- sleeping for a period of time + +## Examples: + +```v +import time + +println(time.now()) +``` diff --git a/vlib/toml/README.md b/vlib/toml/README.md index 4aa222423..cdcc47503 100644 --- a/vlib/toml/README.md +++ b/vlib/toml/README.md @@ -1,4 +1,4 @@ -# TOML module +## Description `toml` is a fully fledged [TOML v1.0.0](https://toml.io/en/v1.0.0) compatible parser written in pure V. The module is tested against the [official compliance tests](https://github.com/toml-lang/compliance). diff --git a/vlib/v/README.md b/vlib/v/README.md index c5360f922..9c06c05e8 100644 --- a/vlib/v/README.md +++ b/vlib/v/README.md @@ -1,3 +1,12 @@ +## 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. diff --git a/vlib/x/README.md b/vlib/x/README.md new file mode 100644 index 000000000..8392a17ff --- /dev/null +++ b/vlib/x/README.md @@ -0,0 +1,8 @@ +## Description: + +`x` is not a module by itself, but a namespace for other modules. +The modules here are considered experimental/subject to change. + +In time, `x` modules will either become ordinary vlib modules, +or they will be split to their own repositories, and distributed +apart from V. -- 2.30.2