Miscellaneous Information

9 – Miscellaneous Information

9.1 – Coding Conventions

9.1.1 – Naming Conventions

In general, snake_case should be used for all identifiers and file names. Some exceptions are macros and flags, which should use UPPER_CASE_SNAKE_CASE. Files that are used as headers should have the .hevi extension, while files that mostly contain implementations should have the .evi extension.

Some correct examples are as follows:

\ my_implementation_file.evi

#apply "my_header" \ .hevi
#flag MY_FLAG
#macro MY_MACRO 123
@is_even bln (i32);
%my_byte ui8;

9.1.2 – Commenting Conventions

By convention documentation of variables and functions should consist of line-comments and should be placed directly above the declaration of said variable or function. These comments are denoted with \?. Documentation of function parameters should be denoted by \? @param <PARAMETER INDEX> and documentation of a function's return value should be denoted by \? @return. The main documentation should be punctuationally correct while the documentation of parameters and return values should not start with a capital letter, nor end with a period.

A correct example of function documentation is the following:

\? Multiplies two integers and returns the result.
\? Returns a negative number if the multiplication failed.
\? @param 0 the first integer
\? @param 1 the second integer
\? @return the result of the multiplication, or -1 if an error occurred
@multiply i32 (i32 i32);

These documentational comments have no effect on the code itself.

9.1.3 – Miscellaneous Conventions

Code inside a block, if- or loop statement or function should be indented. When such code consists of only one statement, it should not be surrounded by a block, and when the statement is relatively short it should not be on a new line.

Code blocks should always start on a new line, unless the code inside is short enough to be put on one line. In such cases, the code block follows the same rules as other statements as mentioned above.

For intendation, tabs are preferred over whitespaces.

An example of code following the above rules is the following snippet:

@absolute i32 (i32) ~ $0 < 0 ? -$0 : $0;

@long_absolute i32 (i32)
	??($0 > 0) ~ 1 * $0; :: ??($0 == 0) ~ 1 * $0 :: -1 * $0;

@three_absolutes i32* (i32 i32 i32)
{
	=0 absolute($0);
	=1 absolute($1);
	=2 absolute($2);
	~ {$0, $1, $3};
}

@echo i32 (i32) { print("%d\n", $0); ~ $0; }

Files that are part of a library and that are used as headers and have the .hevi extension should be include-guarded. This can be done using #info apply_once. Said headers should also set a flag signalling that that header has been included using the format <LIBRARY-NAME>_<HEADER-BASE-NAME>_H (for example MYLIB_MATHFUNCS_H). The last two conventions can also be combined like in the following snippet:

#ifnset MYLIB_MYHEADER_H 
#flag MYLIB_MYHEADER_H 

\ code here
\ ...
\ ...

#endif 

Lastly, type modifiers should not be separated from the basic data type they modify. So e.g. ! i32 and chr * are "incorrect", where e.g. !bln and flt* are "correct". This is because the modifiers "modify" the data type, and not the variable that stores the data. (For example, a character pointer is a pointer to the chr type, not to whatever the variable is named.)

Code that goes against any of the above conventions is considered dirty code, but will not be treated any differently by the compiler as long as it is correct.

9.2 – Credits

Heavy inspiration for AST parser and scanner design: Robert Nystrom

Contents and structure of documentation: Lua Reference Manual

Standard library contents and implementations: GNU Project (glibc)

9.3 – License

MIT License

Copyright (c) 2022 Sjoerd Vermeulen

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.