v.util #

fn args_quote_paths(args []string) string

fn bold(msg string) string

fn cached_file2sourcelines(path string) []string

fn cached_read_source_file(path string) !string

fn cescaped_path(s string) string

fn check_module_is_installed(modulename string, is_verbose bool, need_update bool) !bool

fn color(kind string, msg string) string

fn contains_capital(s string) bool

fn ensure_modules_for_all_tools_are_installed(is_verbose bool)

fn find_all_v_files(roots []string) ![]string

find_all_v_files - given a list of files/folders, finds all .v/.vsh files if some of the files/folders on the list does not exist, or a file is not a .v or .vsh file, returns an error instead.

fn formatted_error(kind string, omsg string, filepath string, pos token.Pos) string

formatted_error - kind may be 'error' or 'warn'

fn free_caches()

free_caches knows about all util caches and makes sure that they are freed if you add another cached unsafe function using static, do not forget to add a mechanism to clear its cache, and call it here.

fn get_build_time() time.Time

get_build_time returns the current build time, while taking into account SOURCE_DATE_EPOCH to support transparent reproducible builds. See also https://reproducible-builds.org/docs/source-date-epoch/ When SOURCE_DATE_EPOCH is not set, it will return the current UTC time.

fn get_timers() &Timers

fn get_vtmp_folder() string

get_vtmp_folder returns the path to a folder, that is writable to V programs, and specific to the user. It can be overridden by setting the env variable VTMP.

fn good_type_name(s string) bool

HTTPRequest bad HttpRequest good

fn highlight_suggestion(message string) string

highlight_suggestion returns a colorfull/highlighted version of message, but only if the standard error output allows for color messages, otherwise the plain message will be returned.

fn is_escape_sequence(c u8) bool

is_escape_sequence returns true if c is considered a valid escape sequence denoter.

fn is_func_char(c u8) bool

fn is_generic_type_name(name string) bool

is_generic_type_name returns true if the current token is a generic type name.

fn is_name_char(c u8) bool

fn join_env_vflags_and_os_args() []string

join_env_vflags_and_os_args returns all the arguments (the ones from the env variable VFLAGS too), passed on the command line.

fn launch_tool(is_verbose bool, tool_name string, args []string)

launch_tool - starts a V tool in a separate process, passing it the args. All V tools are located in the cmd/tools folder, in files or folders prefixed by the letter v, followed by the tool name, i.e. cmd/tools/vdoc/ or cmd/tools/vpm.v. The folder variant is suitable for larger and more complex tools, like v doc, because it provides you the ability to split their source in separate .v files, organized by topic, as well as have resources like static css/text/js files, that the tools can use. launch_tool uses a timestamp based detection mechanism, so that after v self, each tool will be recompiled too, before it is used, which guarantees that it would be up to date with V itself. That mechanism can be disabled by package managers by creating/touching a small cmd/tools/.disable_autorecompilation file, OR by changing the timestamps of all executables in cmd/tools to be < 1024 seconds (in unix time).

fn module_is_builtin(mod string) bool

fn new_error_manager() &EManager

fn new_suggestion(wanted string, possibilities []string, params SuggestionParams) Suggestion

new_suggestion creates a new Suggestion, given a wanted value and a list of possibilities.

fn new_surrounder(expected_length int) Surrounder

new_surrounder creates a new Surrounder instance. The expected_length is a hint for the initial capacity for the befores/afters stacks.

fn new_timers(params TimerParams) &Timers

fn no_cur_mod(typename string, cur_mod string) string

no_cur_mod - removes cur_mod. prefix from typename, but only when it is at the start, i.e.: no_cur_mod('vproto.Abdcdef', 'proto') == 'vproto.Abdcdef' even though proto. is a substring

fn no_dots(s string) string

fn path_of_executable(path string) string

fn path_styled_for_error_messages(path string) string

path_styled_for_error_messages converts the given file path, into one suitable for displaying in error messages, produced by the V compiler.

When the file path is prefixed by the working folder, usually that means, that the resulting path, will be relative to the current working folder. Relative paths are shorter and stabler, because they only depend on the project, and not on the parent folders. If the current working folder of the compiler is NOT a prefix of the given path, then this function will return an absolute path instead. Absolute paths are longer, and also platform/user dependent, but they have the advantage of being more easily processible by tools on the same machine.

The V user can opt out of that relativisation, by setting the environment variable VERROR_PATHS, to absolute. That is useful for starting the V compiler from an IDE or another program, where the concept of a "current working folder", is not as clear as working manually with the compiler in a shell. By setting VERROR_PATHS=absolute, the IDE/editor can ensure, that the produced error messages will have file locations that are easy to find and jump to locally.

Note: path_styled_for_error_messages will always use / in the error paths, no matter the OS,to ensure stable compiler error output in the tests.

fn prepare_tool_when_needed(source_name string)

fn qualify_import(pref_ &pref.Preferences, mod string, file_path string) string

2022-01-30 qualify_import - used by V's parser, to find the full module name of import statements 2022-01-30 i.e. when parsing import automaton inside a .v file in examples/game_of_life/life_gg.v 2022-01-30 it returns just 'automaton' 2022-01-30 TODO: this seems to always just return mod itself, for modules inside the V main folder. 2022-01-30 It does also return mod itself, for stuff installed in ~/.vmodules like vls but for 2022-01-30 other reasons (see res 2 below).

fn qualify_module(pref_ &pref.Preferences, mod string, file_path string) string

2022-01-30 qualify_module - used by V's parser to find the full module name 2022-01-30 i.e. when parsing module textscanner, inside vlib/strings/textscanner/textscanner.v 2022-01-30 it will return strings.textscanner

fn quote_path(s string) string

fn read_file(file_path string) !string

fn recompile_file(vexe string, file string)

fn replace_op(s string) string

fn resolve_d_value(compile_values map[string]string, str string) !string

resolve_d_value replaces all occurrences of $d('ident','value') in str with either the default 'value' param or a compile value passed via -d ident=value.

fn resolve_env_value(str string, check_for_presence bool) !string

resolve_env_value replaces all occurrences of $env('ENV_VAR_NAME') in str with the value of the env variable $ENV_VAR_NAME.

fn resolve_vmodroot(str string, dir string) !string

resolve_vmodroot replaces all occurrences of @VMODROOT in str, with an absolute path, formed by resolving, where the nearest v.mod is, given the folder dir.

fn set_source_for_path(path string, source string) []string

set_source_for_path should be called for every file, over which you want to use util.formatted_error

fn set_vroot_folder(vroot_path string)

set_vroot_folder sets the VCHILD env variable to 'true', and VEXE to the location of the V executable It is called very early by launch_tool/3, so that those env variables can be available by all tools, like v doc, v fmt etc, so they can use them to find how they were started.

fn short_module_name(name string) string

short_module_name returns a shortened version of the fully qualified name, i.e. xyz.def.abc.symname -> abc.symname

fn should_bundle_module(mod string) bool

fn should_recompile_tool(vexe string, tool_source string, tool_name string, tool_exe string) bool

Note: should_recompile_tool/4 compares unix timestamps that have 1 second resolutionThat means that a tool can get recompiled twice, if called in short succession.

Todo: use a nanosecond mtime timestamp, if available.

fn show_compiler_message(kind string, err errors.CompilerMessage)

fn skip_bom(file_content string) string

fn smart_quote(str string, raw bool) string

fn source_file_context(kind string, filepath string, pos token.Pos) []string

fn strip_main_name(name string) string

fn strip_mod_name(name string) string

fn tabs(n int) string

fn timing_measure(label string)

fn timing_measure_cumulative(label string)

fn timing_set_should_print(should_print bool)

fn timing_start(label string)

fn verror(kind string, s string)

fn vlines_escape_path(path string, ccompiler string) string

type CalculateSuggestionSimilarityFN = fn (s1 string, s2 string) f32

CalculateSuggestionSimilarityFN is the type of the similarity comparison function, that will be used to determine what suggestions are best

fn (mut s Suggestion) add(val string)

add adds the val to the list of known possibilities of the suggestion. It calculates the similarity metric towards the wanted value.

fn (mut s Suggestion) add_many(many []string)

add adds all of the many to the list of known possibilities of the suggestion

fn (mut s Suggestion) sort()

sort sorts the list of known possibilities, based on their similarity metric. Equal strings will be first, followed by less similar ones, very distinct ones will be last.

fn (s Suggestion) say(msg string) string

say produces a final suggestion message, based on the preset wanted and possibilities fields, accumulated in the Suggestion.

struct EManager {
mut:
	support_color bool
}

fn (e &EManager) set_support_color(b bool)

struct SuggestionParams {
pub mut:
	similarity_threshold f32 = 0.5                      // only items for which the similarity is above similarity_threshold, will be shown
	similarity_fn        CalculateSuggestionSimilarityFN = strings.dice_coefficient // see also strings.hamming_similarity
}

SuggestionParams contains the defaults for the optional parameters of new_suggestion.

struct Surrounder {
mut:
	befores []string
	afters  []string
}

Surrounder is an utility to help you manage a stack of additions, that should be done both before and after a given piece of generated code, in a synchronised way. It does so by forcing you to put the creation/destruction samples next to each other, so that it is easier to keep them in sync and spot errors.

Note: Surrounder writes the creation samples (befores) in the same order they were added, and the destruction samples (afters) in reverse order.

Usage:

mut sr := new_surrounder(2) // just a rough initial guess; it can grow
sr.add('string tmp1 = ...;', 'string_free(&tmp1);')
sr.add('string tmp2 = ...;', 'string_free(&tmp2);')
..
sr.builder_write_befores(mut some_string_builder)
some_string_builder.writeln('MIDDLE_that_uses_tmp1_and_tmp2')
sr.builder_write_afters(mut some_string_builder)

... will produce this in some_string_builder:

string tmp1 = ...;
string tmp2 = ...;
MIDDLE_that_uses_tmp1_and_tmp2
string_free(&tmp2);
string_free(&tmp1);

fn (mut s Surrounder) add(before string, after string)

add appends a before/after pair to the surrounder When you call .after() or .builder_write_afters(), all before parts will be in order, while all after parts, will be in reverse order.

fn (s &Surrounder) before() string

before returns all the before parts that were accumulated so far

fn (s &Surrounder) after() string

after returns all the after parts that were accumulated so far, in reverse order of their addition.

fn (s &Surrounder) builder_write_befores(mut sb strings.Builder)

builder_write_befores writeln-es all the before parts into the given string builder sb.

fn (s &Surrounder) builder_write_afters(mut sb strings.Builder)

builder_write_afters writeln-es all the after parts into the given string builder sb. They will be written there in reverse order, compared to how/when they were added.

fn (mut s Surrounder) free()

free frees the private resources associated with the surrounder instance Called automatically by -autofree, or in @[manualfree] tagged functions.

struct TimerParams {
pub:
	should_print bool
	label        string
}

struct Timers {
	label string
pub mut:
	swatches     shared map[string]time.StopWatch
	should_print bool
	// already_shown records for which of the swatches .show() or .show_if_exists() had been called already
	already_shown []string
}

fn (mut t Timers) start(name string)

fn (mut t Timers) measure(name string) i64

fn (mut t Timers) measure_cumulative(name string) i64

fn (mut t Timers) measure_pause(name string)

fn (mut t Timers) measure_resume(name string)

fn (mut t Timers) message(name string) string

fn (mut t Timers) show(label string)

fn (mut t Timers) show_if_exists(label string)

fn (mut t Timers) show_remaining()

fn (mut t Timers) dump_all()