Swag Language Reference

Introduction

The swag-lang/swag/bin/reference/language module offers a foundational introduction to the syntax and usage of the Swag programming language, separate from the Swag standard modules (Std). This documentation is auto-generated from the module's source code.

For more advanced features, such as dynamic arrays, dynamic strings, or hash maps, please consult the Std.Core module documentation, as these topics are beyond the scope of the examples covered here. This guide focuses exclusively on the core elements of the Swag language.

Since reference/language is implemented as a test module, you can run it using the following commands:

These commands will execute all test modules within the specified workspace, including this one. If you are running Swag from the workspace directory, the --workspace flag (or shorthand -w) can be omitted.

To compile and execute a specific module within the workspace, use the --module (or -m) flag:

Hello mad world

Let's start with the most simple version of the "hello world" example. This is a version that does not require external dependencies like the Swag standard modules.

#main is the program entry point, a special compiler function (that's why the name starts with #). It must be defined only once for a native executable. @print is an intrinsic, a special built-in function (that's why the name starts with @).

All intrinsics are part of the compiler runtime which comes with the compiler.

Next, a version that this time uses the Core.Console.print function in the Std.Core module. The Std.Core module would have to be imported in order to be used, but let's keep it simple.

A #run block is executed at compile time, and can make Swag behaves like a kind of a scripting language. So in the following example, the famous message will be printed by the compiler during compilation.

A version that calls a nested function at compile time (only) to initialize the string constant to print.

Now a stupid version that generates the code to do the print thanks to meta programming.

And finally let's be more and more crazy.

This whole piece of code is equivalent to...

Code structure

Source code organization

In Swag, all source files are required to use the .swg extension, with the exception of simple script files, which use the .swgs extension. All files must be encoded in UTF-8 to ensure proper handling of text and symbols.

Swag does not support the compilation of individual source files (except for .swgs script files). Instead, source code is structured within a workspace that comprises one or more modules. This approach promotes organized and modular development, allowing for efficient management of complex projects.

For example, Std is a workspace that includes all the standard modules provided by Swag.

A module can either be a dll (on Windows) or an executable. A single workspace may contain multiple modules, meaning that a workspace usually includes the modules you develop (such as your main executable) as well as all your dependencies, including any external modules.

Typically, the entire workspace is compiled together, ensuring that all modules and their dependencies are up to date and correctly integrated.

Global declaration order

The order of all top-level declarations does not matter. This feature allows you to reference constants, variables, or functions before they are defined, either within the same file or even across multiple files. This flexibility can be particularly useful in large codebases, where the natural flow of logic or readability may benefit from organizing code independently of its declaration order.

In this test, we demonstrate Swag's flexibility by calling the function functionDeclaredLater before it is defined. Swag's allowance for this behavior highlights the language's flexibility in handling the order of top-level declarations.

It is important to note that this flexibility applies not only within the same file but also across multiple files. For instance, you can call a function in one file and define it in another. The global order of declarations in Swag is designed to be non-restrictive, allowing for a more intuitive organization of your code.

Comments

Swag supports both single-line and multi-line comments, allowing for flexible documentation and inline explanations within your code. This capability is essential for maintaining clarity and readability, especially in complex codebases.

Swag also supports nested comments within multi-line comments. This feature can be particularly useful when temporarily disabling a block of code or when adding additional notes inside an existing comment block.

Semicolons

Statement Termination in Swag

Unlike languages such as C/C++, there is no strict requirement to end statements with a semicolon (;). The default method of terminating a statement in Swag is simply reaching the end of a line (end of line). This feature allows for cleaner and more concise syntax, reducing visual clutter and making the code easier to read.

Optional Semicolons

While semicolons are optional, they can still be used if desired. In some cases, using semicolons might enhance the clarity of the code or improve readability, particularly when dealing with more complex statements or when writing multiple statements on a single line.

Multiple Statements on a Single Line

Semicolons become particularly useful when you need to write multiple statements on a single line. Although this can make the code more compact, it is advisable to use this approach sparingly, as excessive use may negatively impact code readability.

Identifiers

Naming

User-defined identifiers, such as variables, constants, and function names, must begin with either an underscore or an ASCII letter. These identifiers can then include underscores, ASCII letters, and digits.

Examples:

However, identifiers cannot start with two underscores, as this prefix is reserved by the compiler.

Compiler Instructions

Additionally, some identifiers may begin with #, indicating a compiler directive or special function. These instructions have specific roles within the Swag programming environment. They evaluate at compile time.

Examples of compiler instructions:

Intrinsics

Identifiers that start with @ represent intrinsic functions. These functions are available at both compile time and runtime.

Examples of intrinsic functions:

Keywords

Special Keywords

Special keywords are predefined, reserved identifiers that have specific meanings within the Swag compiler. These cannot be used as identifiers in your code as they are integral to the language's structure.

Reserved Keywords

These keywords are reserved by the language and cannot be used by developers, even though they may not currently serve an active role in the syntax. They are reserved for potential future use or to avoid conflicts with language features.

Basic Types

These are the fundamental data types provided by the language. They are reserved keywords and form the core types that can be used to define variables, constants, and function return types.

Compiler Instructions

Compiler instructions are prefixed with # and are reserved for specific operations within the Swag compiler. These keywords are used to control various aspects of compilation and code generation. User-defined identifiers cannot start with #, ensuring that compiler keywords do not conflict with user-defined names.

Miscellaneous Intrinsics

Intrinsic functions are prefixed with @ and provide low-level operations that are often directly supported by the compiler or underlying hardware. These keywords offer specialized functionality that can be used during both compile time and runtime, depending on the context.

Intrinsics from libc

These intrinsic functions provide access to standard libc functionalities, allowing developers to perform common mathematical, memory, and string operations. They are also prefixed with @ to avoid conflicts with user-defined identifiers.

Modifiers

Modifiers can be applied to specific keywords or operators to alter their behavior. These modifiers allow developers to fine-tune operations, giving more control over how certain code constructs are executed.

Fundamentals

Basic types

Signed Integers

Swag provides various signed integer types: s8, s16, s32, and s64. These types represent signed integers with different bit widths, allowing for both positive and negative values within their respective ranges. Each type is specifically designed to efficiently handle integer operations at varying levels of precision.

Unsigned Integers

Swag also supports various unsigned integer types: u8, u16, u32, and u64. These types represent unsigned integers, which can only hold non-negative values, making them ideal for scenarios where negative numbers are not applicable.

Floating-Point Types

Swag supports floating-point types f32 and f64. These types represent single-precision and double-precision floating-point numbers, respectively. They are crucial for calculations requiring fractional values and greater precision.

Boolean Type

The boolean type bool is used to represent true or false values. In Swag, a boolean is stored as a 1-byte value, offering a straightforward way to handle binary logic within your programs.

String Type

The string type represents text. In Swag, strings are UTF-8 encoded and are stored as two 64-bit values: one for the pointer to the data and one for the length in bytes. Strings are designed to handle text efficiently, including international characters, while ensuring compatibility with common text processing routines.

Rune Type

The rune type represents a 32-bit Unicode code point. It is used to store individual Unicode characters, allowing for the manipulation of text at the character level, supporting a wide range of languages and symbols.

Type Creation with #decltype

You can use #decltype to create a type based on an expression. This is useful for cases where you want to infer or mirror the type of a variable dynamically, promoting code reusability and reducing redundancy.

Number literals

Number Representations

Integers can be written in multiple formats: decimal, hexadecimal, or binary. These different representations allow you to express numbers in the format that best suits your needs.

Digit Separators

Numeric literals can be more readable by using the _ character as a digit separator. This is particularly useful for large numbers, without affecting their value.

Default Integer Types

In Swag, hexadecimal or binary numbers default to u32 if they fit within 32 bits. If the value exceeds 32 bits, it is automatically inferred as u64.

Booleans

A boolean type can be either true or false. As constants are known at compile time, you can use #assert to verify their values during compilation.

Floating Point Values

Floating point values use the standard C/C++ notation for floating-point literals. This provides familiarity and ease of use for developers.

Default Floating Point Type

By default, floating-point literals are of type f32. This is different from languages like C/C++, where floating-point literals default to double (f64).

Literal Suffix

To specify the type of a literal explicitly, you can add a suffix to the literal. This is useful when a specific type is required, such as f64 or u8.

String

UTF-8 Encoding

Swag uses UTF-8 encoding for strings, which allows representation of a wide range of characters, including those from various languages and symbol sets.

String Comparison

Strings can be compared directly for equality using the == operator.

The rune Type

A rune represents a Unicode code point and is stored as a 32-bit value, ensuring it can accommodate any Unicode character.

String Indexing

When indexing a string, Swag returns a byte (u8), not a rune, which reflects the underlying UTF-8 encoding.

String Concatenation

Swag allows compile-time concatenation of strings and other values using the ++ operator.

Null Strings

A string can be null if it has not been initialized. This behavior can be used to check whether a string has been assigned a value.

Character Literals

Character literals are enclosed in quotes. These literals can represent any Unicode character, not just ASCII characters.

Default Type of Character Literals

A character literal is a 32-bit integer by default. It can be assigned to any integer type or a rune, provided the value fits within the target type.

Specifying Character Literal Types

Swag allows you to specify the type of a character literal using a suffix. This is useful for controlling the storage size of the character.

Escape Sequences

Swag supports escape sequences in strings and character literals, allowing special characters to be represented within these literals.

An escape sequence starts with a backslash ` and is followed by a specific character.

ASCII and Unicode Escape Sequences

Escape sequences can also be used to specify characters via their ASCII or Unicode values.

Raw Strings

A raw string is a string where escape sequences and special characters are not processed. This can be useful for strings that contain many special characters or backslashes.

A raw string is enclosed within # characters, which ensures that its content is taken literally.

These two strings are equivalent, even though one uses escape sequences and the other is raw:

Multiline Raw Strings

Raw strings can span multiple lines, and all leading spaces before the closing "# are removed from each line.

In the above example, the multiline raw string retains its formatting, except that leading spaces before the closing "# are stripped from each line.

Multiline Strings

Multiline strings start and end with """. Unlike raw strings, they still process escape sequences.

In a multiline or raw string, ending a line with ` prevents the following end of line (EOL) from being included in the string.

#stringof and #nameof Intrinsics

The #stringof intrinsic returns the string representation of a constant expression at compile time.

The #nameof intrinsic returns the name of a variable, function, etc., as a string.

Constants

Constants with const

Using const implies that the value must be known by the compiler at compile time. This ensures that the value is embedded directly into the compiled code, eliminating any runtime memory usage for simple types like integers or strings. Essentially, the compiler replaces occurrences of these constants with their respective values wherever they are referenced in the code, leading to more optimized and efficient code execution.

Constants with Complex Types

Swag also supports constants with more complex data types, such as arrays or structures. When declaring constants with these types, the data is stored in the program's data segment, which incurs a memory footprint. Additionally, you can obtain the memory address of these constants at runtime, allowing you to manipulate their values indirectly through pointers.

Static Arrays

The following example demonstrates a static array, which is an array with a fixed size. This array contains three elements of type s32, a signed 32-bit integer.

Multidimensional Arrays

This example illustrates a multidimensional array declared as a constant. The array is a 4x4 matrix of 32-bit floating-point numbers (f32). We will explore arrays in further detail later in this documentation.

Key Difference Between let and const

The primary distinction between let and const lies in the timing of value determination. The value assigned to a const must be determined at compile time, meaning it is fixed and known before the program runs. Conversely, a let allows for dynamic assignment, where the value can be computed and assigned during runtime. Despite this, both let and const ensure that their values are assigned only once, maintaining immutability.

Variables

Variable Declaration

Variables are declared using the let or var keyword, followed by a : and the variable's type.

• let: Used for declaring a constant variable. The value assigned cannot be modified, ensuring immutability.
• var: Used for declaring a mutable variable. The value assigned can be modified after initialization.

Multiple Variable Declarations

Swag allows the declaration of multiple variables of the same type on a single line.

Alternatively, multiple variables of different types can also be declared on the same line.

Default Initialization

If a variable is declared without an initial value, it is automatically initialized with its default value. A variable is always initialized, ensuring it never holds an undefined value.

Uninitialized Variables

If you want a variable to remain uninitialized and avoid the default initialization cost, you can assign it undefined. This approach should be used with caution, as the variable will be in an undefined state.

Type Inference

Swag supports type inference, where the type of a variable can be automatically deduced from its assigned value. This allows the omission of explicit type annotations in many cases.

Below are examples demonstrating type inference.

Type inference also applies when declaring multiple variables simultaneously.

Special Variables

Swag offers special keywords and attributes to manage variable storage and behavior beyond typical usage.

Thread-Local Storage

By tagging a global variable with #[Swag.Tls], you can store it in thread-local storage. Each thread will then have its own independent copy of the variable.

Global Variables

A local variable can be tagged with #[Swag.Global] to make it global, functioning similarly to the static keyword in C/C++.

Compile-Time Variables

Global variables marked with #[Swag.Compiler] are only accessible during compile-time and are excluded from the runtime code.

Operators

Arithmetic Operators

These operators perform basic arithmetic operations such as addition, subtraction, multiplication, and division. Modulus operation is also supported to get the remainder of a division.

Bitwise Operators

Bitwise operators manipulate individual bits of integral types. These operators perform operations such as XOR, AND, OR, and bit shifting.

Assignment Operators

These operators perform the basic arithmetic or bitwise operation and assign the result directly to the left operand. The affect versions of these operators make the code concise and clear.

Unary Operators

Unary operators operate on a single operand. These include logical NOT, bitwise NOT, and negation.

Comparison Operators

Comparison operators compare two values and return a boolean result. They include equality, inequality, and relational operators.

Logical Operators

Logical operators evaluate expressions to return a boolean value. Swag uses and and or instead of && and || found in C/C++.

Ternary Operator

The ternary operator tests an expression and returns one of two values depending on the result of the test. The syntax is A = Expression ? B : C, where B is returned if the expression is true, and C is returned if the expression is false.

Spaceshift Operator

Operator <=> returns -1, 0, or 1 if the left expression is lower, equal, or greater than the right expression, respectively. The returned type is s32.

Null-Coalescing Operator

The operator orelse returns the left expression if it is not null, otherwise it returns the right expression.

Works with strings, pointers, and structures with the opData special function (covered later).

Works also for basic types like integers.

Type Promotion

Unlike C, types are not promoted to 32 bits when dealing with 8 or 16-bit types. However, types will be promoted if the two sides of an operation do not have the same type.

This means that an 8/16-bit operation (like an addition) can more easily overflow if you do not take care. In that case, you can use the #prom modifier on the operation, which will promote the type to at least 32 bits. The operation will be done accordingly.

We'll see later how Swag deals with that kind of overflow, and more generally, with safety.

Operator Precedence

If two operators have the same precedence, the expression is evaluated from left to right.

Cast

Explicit Cast with cast

Explicit casting is necessary when you need to convert a value from one type to another manually. This can be achieved using the cast(type) value syntax, which transforms the value into the specified type.

Automatic Cast with cast()

A cast() without an expression stands for automatic cast, allowing the compiler to automatically determine and perform the cast to match the type on the left-hand side of the assignment.

This also works for a function call argument.

Bitcast

The bit cast mode enables bit-level reinterpretation of a value's type without altering the underlying bit pattern. This operation, known as a bitcast, is only valid when the source and destination types share the same size.

This example demonstrates the reverse operation, where an integer representing a bit pattern is reinterpreted as a floating-point number.

Implicit Casts

Swag allows automatic type conversions, known as implicit casts, when assigning a value of one type to a variable of another type. This occurs without requiring an explicit cast statement. However, implicit casts are only permitted when there is no risk of precision loss or range overflow, ensuring that the value remains intact and no data is lost during the conversion.

Implicit Cast Rules

1. Widening Conversions: Implicit casts are allowed when converting a smaller type to a larger type, such as from s8 to s16, or from f32 to f64. These conversions are safe because the larger type can represent all possible values of the smaller type.
2. Sign Preservation: When implicitly casting between signed and unsigned types, Swag ensures that no data loss occurs by verifying that the value can be represented in both types. Implicit casts from unsigned to signed types (and vice versa) are only allowed when the value is positive and within the range of the target type.
3. No Implicit Narrowing: Swag does not permit implicit casts that could potentially lose data or precision, such as from s32 to s8. These narrowing conversions require an explicit cast to indicate that the developer is aware of the potential data loss.

Examples of Implicit Casts

Let's explore some examples to illustrate these rules.

Examples Where Implicit Casts Are Not Allowed

There are cases where implicit casts are not permitted due to the risk of data loss or precision issues. In such situations, Swag requires an explicit cast to ensure that the developer is aware of and accepts the risks.

Additionally, the cast mode unsafe can be used in explicit casts to indicate that the value may lose some precision without raising an error.

Alias

Type Alias

An alias allows you to create a shorthand for an existing type, making it possible to refer to that type using a new, potentially more descriptive name. This can enhance code clarity, reduce repetition, and make complex types easier to work with.

Basic Type Alias

Using alias, you can define an alias for an existing type. This alias can then be used in place of the original type, simplifying the code or improving its readability. It’s important to note that a type alias does not create a new type but merely provides an alternative name for an existing one.

Aliasing Primitive Types

You can create aliases for primitive types, making your code more readable and meaningful, especially when the alias represents a specific domain concept.

Strict Type Alias

In cases where you need to enforce type safety, Swag provides the Swag.Strict attribute, which can be applied to a alias. This makes the alias a distinct type, preventing implicit casting between the alias and the original type. Explicit casting is still allowed, but the distinct type ensures that operations requiring type specificity are clear and deliberate.

Name Alias

An alias allows you also to create an alternative name or shortcut for functions, variables, or namespaces. This can be particularly useful for simplifying code, managing long or complex names, or improving the readability and maintainability of your code.

Function Name Alias

With alias, you can define a shorter or more convenient name for a function. This is particularly helpful when dealing with functions that have long or descriptive names, allowing you to simplify your code without sacrificing functionality.

Variable and Namespace Alias

alias can also be used to alias variables and namespaces, offering a shorter or more convenient reference that can be used throughout your code. This is particularly useful in large codebases where certain variables or namespaces are frequently referenced.

Data structures

Array

Static Arrays in Swag

Static arrays are fixed-size arrays where the size is known and set at compile time. Unlike dynamic arrays from the Std.Core module, static arrays do not change in size during runtime. They are ideal for situations where memory and size constraints are predictable and fixed.

Declaring a Static Array

A static array is declared using the syntax [N] followed by the type, where N is the number of elements.

Array Size and Memory

The @countof intrinsic can be used to get the number of elements in an array, while #sizeof provides the total size of the array in bytes.

Obtaining the Address of an Array

The @dataof intrinsic retrieves the address of the first element in an array.

Array Literals

An array literal is a list of elements enclosed in square brackets [A, B, ...].

Type Deduction in Arrays

Swag can deduce the size of the array from the initialization expression, eliminating the need to specify the dimension explicitly.

Default Initialization

Static arrays in Swag are automatically initialized to zero values (0 for integers, null for strings, false for booleans, etc.) unless specified otherwise.

Preventing Default Initialization

To enhance performance, you can bypass the default initialization by using undefined, particularly useful when you plan to manually initialize all array elements.

Constant Arrays

Static arrays with compile-time values can be declared as constants, meaning their values cannot be altered after declaration.

Type Inference from Array Literals

If the array's type is not explicitly specified, Swag infers the type based on the first literal value, which then applies to all other elements in the array.

Multi-Dimensional Arrays

Swag supports the declaration of multi-dimensional arrays, allowing you to work with arrays with multiple dimensions.

The syntax for declaring multi-dimensional arrays is [X, Y, Z...], where X, Y, and Z represent each dimension.

C/C++ Style Multi-Dimensional Arrays

Swag also allows for the declaration of multi-dimensional arrays using C/C++ syntax, where an array of arrays is created. This method is equivalent to Swag's native multi-dimensional array syntax.

Array Size Deduction

Swag can deduce the size of arrays, including multi-dimensional arrays, directly from the initialization expression.

Single Value Initialization

Swag allows the initialization of an entire array with a single value. This feature is available only for variables, not constants, and supports basic types such as integers, floats, strings, booleans, and runes.

Slice

Slices in Swag

A slice in Swag provides a dynamic view over a contiguous block of memory. Unlike static arrays, slices can be resized or point to different segments of memory at runtime. A slice is composed of a pointer to the data buffer and a u64 value that stores the number of elements in the slice.

This design makes slices a powerful tool for working with subsets of data without the need to copy it, enabling efficient manipulation of large datasets.

Initializing Slices

Slices can be initialized in a similar manner to arrays. By assigning an array literal to a slice, the slice will reference the elements in the array.

Accessing Slice Data

At runtime, you can use @dataof to retrieve the address of the data buffer and @countof to get the number of elements in the slice.

Creating Slices with @mkslice

The @mkslice function allows you to create a slice using your own pointer and element count.

Slicing Strings

For strings, the slice must be const because strings are immutable.

Slicing with the .. Operator

You can create a slice using the .. operator instead of @mkslice. For instance, you can slice a string.

Inclusive and Exclusive Slicing

By default, the upper limit in a slice is inclusive. To exclude the upper limit, use ..< instead of ...

Slicing to the End

You can omit the upper bound to create a slice that extends to the end of the sequence.

Slicing from the Start

To create a slice from the start (index 0), you can omit the lower bound.

Slicing Arrays

Arrays can also be sliced similarly to strings.

Slicing a Slice

It is possible to create a slice from another slice.

Transforming a Pointer to a Slice

You can transform a pointer into a slice.

Tuple

Tuples in Swag

In Swag, a tuple represents an anonymous structure, sometimes referred to as a struct literal. Tuples are particularly useful for grouping together elements of various types without requiring a formally defined structure. The syntax for creating a tuple involves enclosing the elements within curly braces {}.

Accessing Tuple Values

By default, the values in a tuple are accessed using automatically generated field names. These names follow the pattern itemX, where X represents the zero-based index of the element within the tuple.

Named Fields in Tuples

In Swag, it is possible to assign custom names to tuple fields, enhancing the readability and maintainability of the code. When custom names are assigned, the default itemX access pattern remains available, offering flexibility in how you interact with tuple elements.

Automatic Naming of Tuple Fields

When creating a tuple using variables, Swag automatically assigns the field names based on the variable names, unless explicitly overridden. This feature simplifies tuple creation by directly reflecting variable names within the tuple structure.

Tuple Assignment and Compatibility

Swag provides flexibility in assigning tuples to each other, even if the field names differ. As long as the field types are compatible, tuples can be assigned across different structures, facilitating easy data transfer and manipulation.

Tuple Unpacking

Swag allows tuples to be unpacked, meaning their individual elements can be extracted into separate variables. This feature is particularly useful for disaggregating a tuple's data for specific operations or further processing.

Ignoring Tuple Fields During Unpacking

When unpacking a tuple, you can choose to ignore specific fields using the ? placeholder. This is particularly useful when only certain elements of a tuple are needed, allowing you to disregard others efficiently.

Enum

Enums in Swag

Enums in Swag allow you to define a set of named values. Unlike C/C++, enum values in Swag can end with ;, ,, or an end of line (eol).

Enum Underlying Type

By default, an enum in Swag is of type s32, meaning the underlying storage for each value is a 32-bit signed integer.

Custom Enum Underlying Type

You can specify a custom underlying type for an enum by appending it after the enum name.

Default and Custom Enum Values

Enum values, if not explicitly specified, start at 0 and increase by 1 for each subsequent value.

You can specify custom values for each enum element.

Incremental Enum Values

If you omit a value after assigning a specific one, it will be assigned the previous value plus 1.

Non-Integer Enum Values

For non-integer types, you must specify the values explicitly, as they cannot be deduced automatically.

Counting Enum Values

@countof can be used to return the number of values defined in an enum.

Using using with Enums

You can use the using keyword to make enum values accessible without needing to specify the enum name.

Enums as Flags

Enums can be used as flags if declared with the #[Swag.EnumFlags] attribute. For this, the enum's underlying type should be u8, u16, u32, or u64. By default, enums declared as flags start at 1 (not 0), and each value is typically a power of 2.

Enums with Arrays

You can define an enum where each value is associated with a const static array.

Enums with Slices

Similarly, you can define an enum where each value is associated with a const slice.

Nested Enums

Enums can be nested within other enums using the using keyword. Both enums must share the same underlying type.

Accessing Nested Enums

To access a value inside a nested enum, use the enum name (a scope is created).

Automatic Cast with Nested Enums

An automatic cast occurs when converting a nested enum to its parent enum. For example, a value of type BasicErrors can be passed to a parameter of type MyErrors because MyErrors includes BasicErrors.

Specific Attributes for Enums

You can use #[Swag.EnumIndex] to enable an enum value to be used directly as an index without needing to cast it. The underlying enum type must be an integer type.

Preventing Duplicate Enum Values

You can use #[Swag.NoDuplicate] to prevent duplicated values inside an enum. If the compiler detects a value defined more than once, it will raise an error.

Enum Type Inference

Enums in Swag allow type inference, so you can often omit the enum type when assigning a value.

Type Inference in Assignments

The enum type is not necessary in the assignment expression when declaring a variable, as it can be deduced.

Type Inference in switch Statements

The enum type is not necessary in a case expression of a switch block, as it is inferred from the switch expression.

Simplified Enum Syntax

In expressions where the enum type can be deduced, you can omit the enum name and use the .Value syntax.

Simplified Syntax for Enum Flags

This also works for enums used as flags.

Simplified Enum Syntax in Function Calls

In most cases, the simplified .Value syntax also works when passing enum values to functions.

Visiting Enum Values

Using type reflection, Swag allows you to iterate over all the values of an enum. This feature is particularly useful when you need to perform operations across all enum values or when you want to dynamically generate behavior based on the values of an enum.

The two primary mechanisms for iterating over enum values are the for construct and the foreach statement.

Looping Over Enum Values

The for construct allows you to iterate over all values in an enum.

The for idx in RGB: statement is a powerful construct that allows you to iterate over all values in the RGB enum. During each iteration, idx holds the current enum value, which can be used within the for body. In the example above, the for simply counts the number of values in the enum, asserting that the total is 3.

This method is useful when you need to apply the same operation to each enum value, such as populating a list, checking conditions, or performing calculations.

Visiting Enum Values

The foreach statement offers a more structured way to iterate over an enum and perform specific actions based on the current enum value.

The foreach val in RGB statement offers a more structured way to iterate over an enum. Each iteration provides the current enum value in the val variable, which can then be used in a switch statement (or other logic) to perform specific actions based on the value.

In the provided example, the switch statement checks the value of val and executes different blocks of code depending on whether val is R, G, or B. This is particularly useful when you need to perform different actions based on the specific value of the enum, rather than treating all values the same.

Impl

Utilizing the impl Keyword with Enums in Swag

In Swag, the impl keyword allows you to define methods and functions within the scope of an enum. This is particularly useful for associating specific behaviors directly with the enum values. The self keyword within these methods refers to the current enum instance, providing a clean and organized way to encapsulate logic related to the enum.

Implementing Methods for an Enum

In the following example, we utilize the impl enum syntax to define methods for the RGB enum. This syntax allows us to extend the functionality of the enum by associating methods with it. The methods we define will operate on the enum's values, providing a clear and structured approach to handling logic related to these values.

Applying the using Keyword with Enum Methods

The using keyword simplifies method calls by allowing you to omit the enum type when invoking methods. This results in more concise and readable code, especially when the enum type is used frequently within a block.

Introduction to Uniform Function Call Syntax (UFCS)

Uniform Function Call Syntax (UFCS) in Swag enhances code readability by allowing methods to be called directly on enum values. This feature leads to more intuitive and clean code, particularly when working with enums.

Union

Understanding union in Swag

A union is a specialized type of struct where all fields share the same memory location, meaning they all start at the same offset (0). This allows multiple fields to occupy the same space in memory, making it possible to store different types of data in the same memory space at different times. This feature is particularly useful for memory optimization in scenarios where only one of the fields needs to be used at any given moment.

Explanation of Union Behavior

In this example, the union type allows you to define multiple fields (x, y, z), all of which occupy the same memory location. Because these fields overlap in memory, changing the value of one field automatically changes the others. This behavior is useful in situations where you need to store and access different data types within the same memory space, albeit not simultaneously. Here, x, y, and z are all of type f32, so when x is set to 666, both y and z reflect this change, illustrating the shared memory concept inherent in unions.

Pointers

Single Value Pointers

A pointer to a single element is declared using the * symbol. This allows you to create a pointer that holds the address of one specific instance of a data type. Pointers can be used to reference any type of data, allowing for efficient memory management and manipulation of variables.

Null Pointers

In Swag, a pointer can be null, indicating that it does not point to any valid memory location. A null pointer is commonly used to signify that the pointer is uninitialized or that it intentionally points to "nothing". Checking for null pointers before dereferencing is a good practice to avoid runtime errors.

Taking the Address of a Variable

You can obtain the address of a variable using the & operator. This operation returns a pointer to the variable, which can then be stored and used to access or modify the variable's value indirectly through its memory address.

Dereferencing a Pointer

Dereferencing a pointer involves accessing the value stored at the memory location that the pointer refers to. In Swag, you use the dref intrinsic for dereferencing, which allows you to retrieve the actual data stored at the pointer's address.

Const Pointers

A const pointer in Swag refers to a pointer that cannot change the memory location it points to. However, the data at that memory location can still be mutable. Const pointers are useful when you want to ensure that a pointer always refers to the same memory address throughout its lifetime.

Combining const with Pointers

Swag allows you to combine const with pointers in different ways, depending on the level of immutability you need. You can create a pointer that is constant itself, a pointer to constant data, or both. The choice depends on whether you want to restrict the pointer from changing its target or the data being pointed to, or both.

Multiple Values Pointers

For cases where you need pointer arithmetic and want a pointer to multiple values (like an array or a memory block), you declare your pointer with ^ instead of *. This type of pointer is especially useful for iterating over a sequence of elements stored in contiguous memory locations.

Pointer Arithmetic and Array Elements

When you take the address of an array element, the resulting pointer is treated as pointing to multiple elements, allowing for pointer arithmetic. This enables operations like incrementing or decrementing the pointer, which is useful for traversing arrays.

Dereferencing with Indexes

When pointer arithmetic is enabled, you can dereference the pointer using an index, allowing access to elements in an array-like manner. This is particularly useful when working with arrays through pointers, as it allows for flexible element access.

References

References in Swag

Swag also supports references, which are pointers that behave like values. References in Swag provide a convenient way to work with memory addresses while abstracting away the need for explicit pointer syntax, making them easier and safer to use in many cases.

Assigning to References

When an assignment is made to a reference outside of its initialization, the operation changes the value of the variable being referenced, not the reference itself.

Reassigning References

Unlike in C++, you can change the reference itself (reassign it) rather than the value it points to. To reassign the reference, use the ref modifier in the assignment.

Passing References to Functions

Most of the time, you need to take the address of a variable to create a reference to it. The only exception is when passing a reference to a function parameter, and the reference is declared as const. In such cases, taking the address explicitly is not necessary.

Using References with Structs

This approach is particularly useful for structs, as it allows passing literals directly to functions.

Equivalent Reference Passing

Note that declaring a tuple type or a struct type as a parameter is equivalent to passing a constant reference.

Any

The any Type in Swag

any is a versatile type in Swag that can reference values of any other type. This allows for dynamic type handling within your code.

Working with any and Pointers

any acts as a reference to the value it holds, alongside the typeinfo that describes the value's type. You can use @dataof to obtain the pointer to the actual value.

Type Information and any

When #typeof is used on an any, it returns any as the type because any is the type of the reference. To obtain the underlying type of the value stored in any, use @kindof, which is evaluated at runtime.

Retrieving Values from any

You can retrieve the value stored in an any either directly or as a constant reference. This provides flexibility in how you interact with the stored value.

Arrays of any

You can create arrays containing multiple types using any. This allows you to maintain a heterogeneous collection where each element can be of a different type, enabling you to manage and manipulate data of various types within a single structure.

Nullability of any

An any value can be set to null and tested against null, similar to pointers or other nullable types. This allows for flexible handling of cases where a value may or may not be set, providing a robust approach to managing optional values.

Type Checking with any

An any value can be tested against a type using == and !=. This effectively uses @kindof to retrieve the underlying type for comparison. This is particularly useful when you need to confirm the type of the value inside any before performing type-specific operations.

Control flow

If

Basic Usage of if

A basic test with an if statement.

In Swag, curly braces {} are optional for control structures like if. However, if you choose to omit them, you must use a colon :. This syntax rule also applies to other control structures such as while and for.

Unlike in C/C++, the condition in an if statement does not need to be enclosed in parentheses. Parentheses can be used for clarity or grouping, but they are not mandatory.

Variable Declaration in if

You can declare and test a variable in an if statement simultaneously. In this context, the use of var, let, or const is mandatory.

The condition in the if statement will automatically convert the declared variable to a boolean. If the variable is non-zero, the condition evaluates to true, and the if block will execute.

Adding Conditions with where

When an if statement includes a variable declaration, you can add an additional condition using a where clause. The where clause is evaluated only if the initial test passes.

Loop

Introduction to for

The for construct in Swag is a tool for iteration, allowing developers to repeat a block of code a specified number of times. This guide provides an in-depth exploration of the for construct, covering its various features, including basic usage, indexing, naming, reverse loops, early exits, and advanced filtering with the where clause.

Basic Usage

The for expression dictates the number of iterations and is evaluated only once before the loop begins. This value must be a positive integer.

Using #index

Within a for, the compiler automatically provides the #index keyword, which holds the current iteration index, starting from 0.

Naming the Loop Index

Assigning a name to the for index can improve code readability and clarify the for's intent.

Looping Over Arrays and Slices

The for construct is versatile and can iterate over any collection type that supports the @countof intrinsic, such as arrays, slices, and strings.

Reverse Looping

To iterate in reverse order, append the #back modifier to the for statement.

break and continue

The break and continue keywords provide control over the for's execution flow. break exits the loop early, while continue skips the remainder of the current iteration and proceeds with the next.

Exiting Early with break

The break keyword allows you to exit the loop before completing all iterations, useful for optimizing performance or when a specific condition is met.

Skipping Iterations with continue

The continue keyword skips the rest of the current for iteration and jumps to the next, which is useful when certain conditions should bypass processing.

Ranges

The for construct supports iteration over a range of signed values, enabling flexible iteration over specified intervals.

Looping Over a Range with to

The to keyword defines a loop that iterates from one value to another, inclusive.

Excluding the Last Value with until

The until keyword enables iteration up to, but not including, the end value.

Reverse Range Looping

When using ranges, you can also iterate in reverse order by adding the #back modifier after the for statement.

Infinite Loop

A for without an expression but with a block of code creates an infinite loop, functionally equivalent to while true {}. Infinite loops are often controlled with break statements.

Using where Clause

The where clause provides conditional filtering within a loop, allowing specific iterations to execute based on defined criteria.

Basic where Clause

The where clause is appended directly after the for statement, applying a condition to the loop's index or value. Only iterations that satisfy this condition are executed.

where with Arrays

When looping over arrays, the where clause can filter elements based on their value or index, enabling targeted iteration.

Complex Conditions with where

The where supports combining multiple logical expressions, allowing for complex filtering conditions directly within the for.

where with Ranges

The where clause can also be applied to loops over ranges, providing precise control over which range values are processed in the for.

Combining back and where

You can combine the #back modifier with the where clause to filter values while iterating in reverse order.

For

Introduction to for Loops

The for loop also offers a versatile way to iterate over a range of values. The structure closely follows that of C/C++ loops, consisting of a variable declaration statement, a test expression, and an ending statement. This provides fine-grained control over the for's execution, making it a powerful tool for various iteration scenarios.

Accessing Loop Index with #index

Similar to other looping constructs like for, foreach, and while, the for loop in Swag provides access to the #index keyword. This keyword represents the current for index and is particularly useful when you need to keep track of the iteration count separately from the for variable.

Using break and continue in for Loops

In Swag, break and continue work within for loops just as they do in other for structures. Use break to exit the loop prematurely, effectively terminating the loop when a specific condition is met. The continue statement, on the other hand, skips the remainder of the current for iteration and jumps to the next iteration.

Nested for Loops

Swag supports nested for loops, which are useful for more complex iteration patterns. In nested loops, the #index keyword refers to the current index of the innermost for.

Iterating Over Arrays with for

The for for can also be used to iterate over elements of an array or other iterable collections. This method provides a straightforward way to process or manipulate each element within a collection (but we'll see later that foreach is better).

While

Introduction to while Loops

A while loop is a control flow statement that allows repeated execution of a block of code as long as the specified condition evaluates to true. Once the condition becomes false, the loop terminates.

Breaking Out of a while Loop

The break statement provides a way to exit a while loop before the loop’s condition becomes false. This is particularly useful when an early termination of the loop is needed based on a specific condition.

Skipping Iterations with continue

The continue statement allows you to skip the current iteration and proceed directly to the next iteration of the loop. This is useful for ignoring specific conditions within the loop while continuing its execution.

Nested while Loops

A while loop can contain another while loop, forming a nested loop structure. In such cases, the break and continue statements apply only to the loop in which they are directly placed.

Using while with Complex Conditions

The condition in a while loop can involve complex logical expressions, allowing for more sophisticated and controlled execution of the loop.

Switch

Introduction to switch in Swag

The switch statement in Swag operates similarly to those in C/C++, with a key distinction: Swag does not require an explicit break statement at the end of each case block. Instead, it prevents unintentional fallthrough behavior by design, except when the case is empty, where a break statement is necessary. This ensures that each case is independent unless explicitly designed otherwise, reducing the risk of errors in control flow.

Multiple Values in a case

Swag allows you to assign multiple values to a single case statement, simplifying the code when the same block of code should execute for several potential matches. This feature enhances the readability and maintainability of your switch statements.

Using switch with Various Types

The switch statement in Swag is versatile, supporting any type that implements the == operator. This flexibility extends beyond numeric types to include strings and other comparable types, making it a powerful tool for various decision-making scenarios.

Intentional Fallthrough with fallthrough

Swag allows for intentional fallthrough behavior, similar to C/C++, using the fallthrough keyword. This feature provides the option to continue execution from one case block to the next, which can be useful in scenarios where multiple cases share common logic.

Exiting a case Early with break

The break statement in Swag allows for early exit from a case block. This is particularly useful when only a portion of the block should be executed under specific conditions, enhancing control flow within your switch statements.

Handling Empty Cases with break

In Swag, a case statement cannot be left empty. If no action is required for a particular case, the break statement must be used explicitly to avoid compilation errors, ensuring clarity in control flow.

Variable and Expression Cases

Swag’s switch statement offers the flexibility to use variables and expressions in case conditions. This allows for dynamic evaluation based on runtime values, further extending the utility of the switch statement.

The Swag.Complete Attribute

The Swag.Complete attribute ensures exhaustive handling of all possible cases in an enum within a switch statement. If any enum value is not explicitly handled, the compiler will raise an error, enforcing robust and complete logic coverage.

Matching Ranges in a switch Statement

Swag supports matching a range of values in a switch statement, allowing you to group and handle multiple values that fall within a specific range efficiently. This is useful for concise and clear range-based logic within your code.

Overlapping Ranges

In Swag, if ranges within a switch statement overlap, the first valid range that matches will be executed, while subsequent overlapping ranges are ignored. This order of precedence must be carefully considered in your logic.

Using the where Clause in switch

The where clause in Swag allows you to add additional conditions to a case in a switch statement. This provides finer control over the logic, enabling complex decision-making scenarios where multiple variables influence the outcome.

Using where with default

The where clause can also be applied to a default case, providing conditional logic even when no specific case matches. This allows you to handle default scenarios with more precision, based on additional criteria.

Switching on Type with any or interface

When using a switch statement with a variable of type any or interface, Swag matches cases based on the underlying type of the variable. This behavior is akin to the @kindof intrinsic, which allows for dynamic type checking within a switch construct.

Switch Statement with Type Guard and Variable Binding

You can declare a variable with the var keyword before the case value to bind the matched value to a variable, which can then be used within the corresponding case block. Additionally, you can apply conditional checks directly within the case using the where clause to further refine the matching logic.

The switch statement implicitly checks the type of the variable x using a type guard (@kindof), allowing for more precise case matching based on the variable's runtime type.

Key Features:

1. Type Guarding: The switch statement evaluates the type of x, allowing cases to be matched based on its type.
2. Variable Binding: The matched value can be bound to a variable using the var keyword, making the value accessible within the case block.
3. Conditional Matching: The where clause enables additional conditions to be checked during case matching.

Example 1:

The first example checks if x is a string. If it is, the value is bound to the variable str. The @assert function is then used to ensure that the value of str is equal to "value".

Example 2:

The second example showcases conditional matching using the where clause. The switch statement evaluates whether x is a string and checks additional conditions specified in each case.

Switch Without an Expression

A switch statement in Swag can operate without an expression, behaving like a series of if/else statements. Each case is evaluated sequentially, and the first one that evaluates to true is executed, allowing for more complex conditional logic.

Break

Introduction to break in Swag

The break statement is a control structure in Swag, allowing you to exit from for, foreach, while, for, and switch constructs. Understanding how and when to use break is essential for effective flow control in your programs.

Default Behavior of break

By default, the break statement exits only the innermost loop or control structure in which it resides. This ensures that nested loops or structures can be controlled independently.

Named Scopes with break

Swag allows you to define named scopes using the #scope keyword. The break statement can then be directed to exit from the named scope, offering a structured approach to control flow within complex nested loops or conditions.

Using continue with Named Scopes

The continue statement can be used with a named scope to restart the execution from the beginning of the scope. This can be useful for iterating until a specific condition is met.

Unnamed Scopes for Flow Control

Named scopes are optional. You can also use unnamed scopes to manage control flow, offering a structured alternative to traditional if/else statements. This can help simplify complex conditions.

Using break with Simple Statements

A scope in Swag can also be followed by a simple statement rather than a block, providing additional flexibility in controlling the flow of execution.

Visit

Introduction to foreach

The foreach statement is designed to iterate over all elements within a collection. It provides a streamlined and efficient way to process each item in a collection, which can be an array, slice, string and even a struct.

Naming the Value and Index

Both the value and the loop index can be named explicitly. This enhances code readability, especially in cases involving nested loops or complex data structures.

Using Default Aliases

Both the value and the index are optional. If names are not explicitly provided, the default aliases #alias0 for the value and #alias1 for the index can be used.

Reverse Order with #back

To iterate over elements in reverse order, use the #back modifier. This is particularly useful when processing a collection from the last element to the first.

Visiting Arrays and Slices

The foreach statement can be used to iterate over arrays or slices, enabling straightforward processing of each element.

Multi-dimensional Arrays

foreach supports multi-dimensional arrays, facilitating the processing of complex data structures.

Modifying Elements with &

By prefixing the value name with &, foreach allows you to visit elements by address, enabling in-place modification of the elements.

Filtering with where

The where clause can be used with foreach to filter the elements processed based on specific conditions. This approach is efficient for conditionally applying logic to only the elements that meet certain criteria.

Structs

Declaration

Basic Struct Declaration

This section illustrates a basic struct declaration in Swag. Notice that the var keyword is not required when declaring fields within the struct. Each field is defined with a specific type.

Field Separators

Fields within a struct can be separated by either a comma , or a semicolon ;. The trailing separator is optional and can be omitted.

Anonymous Structs

Structs can be declared anonymously when used as variable types. This is particularly useful for lightweight, temporary groupings of data.

Default Field Values

Fields within a struct can be initialized with default values, providing a convenient way to ensure fields are set to a known state.

Struct Initialization

Struct variables can be initialized in multiple ways, providing flexibility in how you set up your structs.

Const Structs

A struct can be defined as a constant, provided that its values can be evaluated at compile-time. This ensures that the struct's values remain immutable throughout the program's execution.

Structs as Function Arguments

Functions can take a struct as an argument. This operation is performed by reference, with no copy made, which is equivalent to passing a const reference in C++.

Impl

Struct Methods and Constants

In Swag, structs can encapsulate methods and constants within them using the impl block. This encapsulation allows for better organization and modularity of the code, keeping the functionality related to the struct within the struct itself.

To access the constant or the function, use the MyStruct namespace.

Multiple impl Blocks

Swag allows multiple impl blocks for a single struct. This feature helps organize methods logically. Within an impl block, self and Self are defined to refer to the current instance and the struct type, respectively.

Method Syntax Sugar

Swag provides syntactic sugar for method definitions. If you use mtd (method) instead of func, the first parameter is implicitly using self. If you use mtd const, it becomes const using self. This feature simplifies method definitions, especially for common cases where self is required.

Method Reflection

To enable reflection on methods within an impl block, the struct must be annotated with #[Swag.ExportType("methods")]. By default, methods are not exported for reflection, but with this annotation, they can be accessed programmatically.

Offset

Custom Field Layout with Swag.Offset

You can force the layout of a field within a struct using the Swag.Offset attribute. This allows you to manually specify the memory offset of a field, which can be useful for creating custom memory layouts, such as overlapping fields or sharing memory space between different fields.

Using Swag.Offset for Indexed Field Access

In this example, Swag.Offset is used to reference a group of fields by index, enabling indexed access to multiple fields through a single array.

Packing

Default Struct Packing

By default, Swag aligns struct fields similarly to the C programming language. Each field is aligned based on the size of its type, ensuring optimal memory access and usage. This default behavior can be explicitly specified using #[Swag.Pack(0)], meaning no additional packing adjustments are applied. Below is an example illustrating this default alignment strategy.

Reducing Packing

Swag allows you to reduce the packing of struct fields using the #[Swag.Pack] attribute. This attribute specifies the alignment value to be applied to each field, enabling more compact struct representations. Below are examples demonstrating different levels of packing.

Struct Size and Alignment

The total size of a struct in Swag is always a multiple of the largest alignment value among its fields. This ensures that the struct remains correctly aligned when used within larger data structures or arrays.

Enforcing Alignment with Swag.Align

Swag provides the #[Swag.Align] attribute to enforce specific alignment constraints on an entire struct. This attribute can be used to ensure that a struct's alignment meets specific hardware or performance requirements.

Field-Specific Alignment

Swag allows setting specific alignment values for individual struct fields using the #[Swag.Align] attribute. This enables fine-grained control over memory layout, which can be crucial for certain low-level optimizations.

Special functions

A struct in Swag can define special operations within the impl block. These operations are predefined and recognized by the compiler. This enables the ability to overload operators and customize behavior when interacting with the struct.

Custom assignment

Custom Assignment Behavior with opAffect

The opAffect method in Swag allows you to define custom assignment behaviors for your struct using the = operator. By overloading opAffect, you can handle assignments of different types, enabling you to specify how your struct should behave when different types of values are assigned.

Optimizing Initialization with Swag.Complete

When opAffect fully initializes the struct, you can annotate it with #[Swag.Complete]. This prevents the struct from being initialized with default values before the assignment, enhancing performance by avoiding redundant assignments.

In this case, the struct v is directly initialized by opAffect(u64), skipping the default initialization step. This optimization leads to more efficient code by reducing unnecessary initializations.

Handling Function Arguments and Automatic Conversion

By default, function arguments do not automatically undergo conversion via opAffect. Explicit casting is necessary unless Swag.Implicit is used to allow automatic conversion.

Using opAffect in Constant Expressions

To use opAffect in a context where the struct needs to be a constant, you can mark the method with #[Swag.ConstExpr]. This allows the struct to be initialized at compile-time via opAffect.

Custom loop

Implementing opCount for Iteration

The opCount method in Swag allows you to specify the number of iterations when looping over an instance of a struct. By defining this method, you can control how many times a loop executes, effectively treating the struct as an iterable object.

With opCount defined, an instance of MyStruct can be looped over similarly to an array or other iterable types. This allows you to use the struct in a loop context, where the loop will execute a number of times based on the value returned by opCount.

Custom iteration

Introduction to opVisit

opVisit is a highly flexible macro used for iterating over the elements in a struct. This macro is not confined to just the struct's fields; it can also be used to traverse any data the struct contains, such as elements in dynamic arrays, internal buffers, or complex object graphs.

The #[Swag.Macro] attribute is mandatory when using opVisit. It defines the macro's behavior, allowing it to be integrated seamlessly into the codebase.

opVisit is a generic function that accepts two compile-time boolean parameters:

• ptr: When set to true, elements are visited by pointer (address), enabling reference-based operations.
• back: When set to true, elements are visited in reverse order (from last to first).

Iterating Over Struct Fields

This example demonstrates one way to use opVisit for iterating over the fields of a struct. The same approach can be extended to foreach more complex data structures.

Extending opVisit: Reverse Order Iteration

You can also implement different versions of opVisit to handle other data structures. For instance, you may want to foreach the fields in reverse order.

Reverse Order Iteration

The opVisitReverse variant allows us to foreach the struct's fields in reverse order, providing flexibility depending on the needs of your application.

Visiting Elements in Dynamic Arrays

Beyond struct fields, opVisit can be designed to foreach elements in dynamic arrays, buffers, or other types of data. The flexibility of opVisit means it can adapt to whatever data structure the struct holds.

For example, consider a struct with a slice:

Custom opVisit for Dynamic Arrays

You could define an opVisit that iterates over the elements of the buffer rather than the struct's fields.

Iterating Over a Dynamic Array

This example shows how to foreach each element in a dynamic array (slice) and perform operations such as summing the elements.

Custom copy and move

Swag supports both copy and move semantics for structures. In this example, we demonstrate these concepts using a Vector3 struct. Although a Vector3 struct typically wouldn't require move semantics (as it doesn't involve heap allocation), this example serves to illustrate how these features are implemented and can be utilized within the Swag language.

Move Semantics in Functions

Move semantics can be explicitly indicated in function parameters by utilizing && instead of &.

Custom literals

User-Defined Literals

User-defined literals allow you to extend the meaning of literals in the language, enabling the creation of custom types that can be initialized directly using literal values with specific suffixes. This feature is particularly useful for defining types like Duration, where different units of time (e.g., seconds, milliseconds, minutes) can be intuitively represented and manipulated.

Literal Suffixes

A literal suffix is a string of characters that immediately follows a numeric literal to specify a particular unit or type. For example, in 4'ms, 'ms' is the suffix indicating that the value is in milliseconds.

To define user-defined literals, you typically provide:

1. A structure representing the custom type (e.g., Duration).
2. Methods that handle the conversion of the literal values based on the suffix provided.

Defining a Custom Type: Duration

The Duration type is a struct designed to represent time intervals, internally stored in seconds. The type allows initialization through various time units like seconds, milliseconds, minutes, and hours.

To convert a given value and suffix to another value, you will use the opAffectLiteral special function.

You can then use the suffix right after the literal value, as long as the type Duration is specified.

Interface

Interfaces in Swag are virtual tables (a list of function pointers) that can be associated with a struct.

Unlike C++, the virtual table is not embedded within the struct. It is a separate object. This allows for implementing an interface for a given struct without altering the struct's definition.

Interface Declaration

Here we declare an interface IReset, with two functions set and reset.

Implementing an Interface

You can implement an interface for any given struct with impl and for. For example, here we implement interface IReset for struct Point2.

Implementing the Interface for Another Struct

Similarly, we implement the IReset interface for struct Point3.

Using the Interface

We can then use these interfaces on either Point2 or Point3.

Accessing Interface Methods Directly

You can also access all functions declared in an interface implementation block for a given struct with a normal call. They are located in a dedicated scope.

Interface as a Type

An interface is a real type, with a size equivalent to 2 pointers: a pointer to the object and a pointer to the virtual table.

Default Implementation in Interfaces

When you declare an interface, you can define a default implementation for each function. If a struct does not redefine the function, then the default implementation will be called instead.

Just declare a body in the interface function to provide a default implementation.

Here we define a specific version of isImplemented for Point2, and no specific implementation for Point3.

For Point3, isImplemented() will return false because this is the default implementation.

Functions

Declaration

Introduction to Function Declarations

A function declaration typically starts with the func keyword, followed by the function name and a pair of parentheses. If no parameters are needed, the parentheses are empty.

Returning Values from Functions

If a function is intended to return a value, use -> followed by the return type. The function body must include a return statement with the corresponding value.

Inferring Return Types

For simple expressions, the return type can be inferred automatically using the => operator instead of explicitly declaring it with ->. This reduces verbosity in cases where the type is obvious.

Shorter Syntax for Functions Without Return Values

When a function does not return a value, a concise syntax can be used. Instead of a full function body, a single expression can be provided after =.

Defining Parameters in Functions

Function parameters are defined within parentheses following the function name. Each parameter is declared with a name and type, separated by a colon. In this example, two parameters x and y of type s32, and an additional unused parameter of type f32 are defined.

Using Default Parameter Values

Parameters can be assigned default values. If the caller does not provide a value for such a parameter, the default value is used.

Inferred Parameter Types

If a parameter has a default value, its type can be inferred from the value provided. In this example, x and y are inferred as f32 due to the 0.0 literal.

Overloading Functions

Swag allows function overloading, where multiple functions can share the same name but differ in their parameter types or counts.

Nested Functions

Functions can be nested within other functions to provide encapsulation and organize code. These nested functions are not closures but are limited to the scope in which they are declared.

Named Parameters and Parameter Order

Swag supports named parameters, allowing you to specify arguments in any order when calling a function. This can enhance code readability and flexibility.

Returning Multiple Values with Anonymous Structs

Anonymous structs provide a convenient way to return multiple values from a function. This method facilitates accessing returned data either by destructuring or directly from the struct.

Lambda

Introduction to Lambdas in Swag

A lambda in Swag is a pointer to a function. This allows functions to be stored in variables, passed as arguments, or returned from other functions, making them versatile in functional programming.

Null Lambdas

A lambda can also be null, indicating that it does not point to any function. This is useful for optional callbacks or deferred initialization of function pointers.

Using Lambdas as Function Parameters

Lambdas can be passed as parameters, enabling higher-order functions where other functions are executed dynamically based on input.

Anonymous Functions

Anonymous functions, or function literals, can be defined directly in your code without the need for a named identifier, making them convenient for quick, inline functionality.

Passing Anonymous Functions as Parameters

Anonymous functions can be passed directly as arguments to other functions, without first being assigned to variables. This enables concise and flexible code.

Inferred Parameter Types in Anonymous Functions

Swag allows for inferred parameter types in anonymous functions, resulting in cleaner and more concise code, especially when the type can be unambiguously deduced from context.

Omitting Types When Assigning Lambdas

When assigning a lambda to a variable, parameter and return types can be omitted if they are inferable from the variable's type. This reduces verbosity while maintaining type safety.

Lambdas with Default Parameter Values

Lambdas in Swag can have default parameter values, enhancing their flexibility and allowing them to adapt to various contexts with minimal adjustments.

Closure

Introduction to Closures in Swag

Swag supports a limited implementation of the closure concept. A closure allows capturing variables from its surrounding scope. Swag currently permits capturing up to 48 bytes, ensuring no hidden allocations. However, only simple variables (i.e., variables without custom behaviors such as opDrop, opPostCopy, or opPostMove) are eligible for capture.

Declaring a Closure

A closure is declared similarly to a lambda, with captured variables specified between |...| before the function parameters. For a type, the syntax is func||(...).

Capturing Variables by Reference

Variables can also be captured by reference using &. By default, variables are captured by value.

Assigning Lambdas to Closure Variables

A closure variable can also hold a standard lambda (without capture). This provides flexibility in assigning different types of functions to the same variable.

Capturing Complex Types

You can capture arrays, structs, slices, etc., as long as they fit within the maximum capture size and the struct is a Plain Old Data (POD) type.

Modifying Captured Variables

Captured variables are mutable and part of the closure, allowing you to modify them. This enables the creation of stateful functions.

Mixin

Introduction to Swag Mixins

A mixin in Swag is declared similarly to a function but with the attribute #[Swag.Mixin]. Mixins allow injecting code into the caller's scope, manipulating variables, or executing code as if it were part of that scope. This documentation provides an overview of Swag Mixins with various examples, demonstrating their flexibility and use cases.

Basic Example of a Mixin

A mixin function can directly modify variables in the caller's scope. In this example, the mixin increments a variable a by 1 each time it is called.

Mixins with Parameters

Mixins behave like functions, allowing parameters, default values, and even return values. This example demonstrates a mixin with an increment parameter that defaults to 1.

Mixins with Code Blocks

A mixin can accept a special parameter of type code, representing a Swag code block defined at the call site. The mixin can execute this code block multiple times using the #inject keyword.

Mixing Code Blocks in Separate Statements

When the last parameter of a mixin is of type code, the code can be declared in a separate statement after the mixin call. This provides a more natural syntax for passing code blocks.

Creating Aliases with Mixins

You can use the special name #alias to create a named alias for an identifier. This enables flexible manipulation of variables through mixins.

Unique Variable Names with #mix?

Mixins can declare special variables named #mix?. These variables receive a unique name each time the mixin is invoked, preventing naming conflicts and allowing multiple mixin invocations in the same scope.

Macro

Introduction to Swag Macros

Macros in Swag are defined similarly to functions, with the key distinction being the #[Swag.Macro] attribute. This attribute indicates that the function is intended to be a macro, which can be reused and expanded at compile-time.

Macro Scope

Macros operate within their own scope, which is separate and isolated from the caller's scope. This is different from mixins, which share the caller's scope. The isolation provided by macros ensures that any variables defined inside the macro do not interfere with or modify variables outside the macro, preventing potential naming conflicts.

Resolving Identifiers Outside the Macro Scope

Macros typically have their own scope, which means variables inside them are isolated from the outer environment. However, using the #up keyword, you can explicitly reference and modify variables that are defined outside the macro. This allows the macro to interact with the caller's environment.

Macros with Code Parameters

Macros can take code parameters, enabling you to pass and insert code blocks dynamically within the macro. This feature is similar to mixins but within the macro's scope.

Forcing Code into the Caller’s Scope with #macro

The #macro keyword can be used to ensure that the code within a macro operates in the caller's scope. This technique negates the need for the #up keyword when referencing the caller's variables.

Performance Considerations with Macros

Macros in Swag can extend the language capabilities without relying on function pointers. This avoids the overhead associated with lambda calls, making macros a performance-efficient choice.

Handling break and continue in User Code with Macros

Macros allow you to customize the behavior of break and continue statements in loops. This can be particularly useful in complex nested loops where you want a break or continue statement to affect an outer loop, not just the immediate one.

By using a macro, you can define aliases for break and continue that allow you to control exactly which loop they affect.

Another example:

Using Aliases in Macros

Special variables named #alias<num> can be used within macros, similar to mixins. These aliases allow you to define and access specific variables within a macro.

Variadic parameters

Introduction to Variadic Functions

Variadic functions accept a variable number of arguments using .... This capability enables functions to handle a flexible number of parameters, making them more versatile in scenarios where the exact number of arguments is not known in advance.

Working with Variadic Parameters as Slices

When a function takes a variadic parameter, the parameters variable is treated as a slice of type any. This feature allows the function to flexibly handle different types of arguments at runtime.

Forcing Variadic Parameters to a Specific Type

If all variadic parameters are of the same type, you can enforce that type using type annotations. This practice makes the parameters' type explicit, ensuring they are not treated as any.

Passing Variadic Parameters Between Functions

You can pass variadic parameters from one function to another, preserving their types and values. This technique is useful when you need to delegate tasks to other functions without losing the variadic nature of the arguments.

Spreading Arrays or Slices to Variadic Parameters

You can spread the contents of an array or slice into variadic parameters using @spread. This feature is handy when you have a collection of values that you want to pass as individual arguments.

Advanced Example: Combining Variadic and Non-Variadic Parameters

This example demonstrates how to combine fixed parameters with variadic parameters and use them together in a function.

Example: Handling Different Types in Variadic Parameters

This example shows how to handle different types within a variadic function, such as summing integers and concatenating strings.

Ufcs

Introduction to Uniform Function Call Syntax (UFCS)

UFCS stands for Uniform Function Call Syntax. It allows any function to be called using the param.func() form when the first parameter of func() matches the type of param. This syntax provides a way to call static functions as if they were methods on an instance, enhancing readability and method-like behavior.

Static Functions as Methods

In Swag, all functions are static, meaning they are not inherently bound to instances of structs or classes. However, UFCS allows these functions to be called in a method-like style, making struct manipulation more intuitive and the code more readable.

UFCS with Multiple Parameters

UFCS works seamlessly with functions that take multiple parameters, as long as the first parameter matches the type of the instance. This allows for consistent and readable function calls, even with more complex function signatures.

UFCS and Function Overloading

UFCS supports function overloading, where the appropriate function is chosen based on the types of the parameters provided. This feature ensures that UFCS remains versatile and applicable across a wide range of function signatures, allowing for flexible and context-appropriate behavior.

Constexpr

Swag.ConstExpr Functions

A function marked with Swag.ConstExpr can be executed at compile time by the compiler if the input values are known at that stage. This allows the function's result to be "baked" into the code, reducing runtime computation and potentially improving performance.

Example: Compile-Time Computation

In the example below, the compiler will execute the sum function at compile time, embedding the result directly into the constant G. The value of G will be 3, computed during the compilation process, ensuring no runtime overhead for this calculation.

Example: Using Swag.ConstExpr with Complex Expressions

Swag.ConstExpr functions can handle more complex expressions as well. The following example shows how a compile-time function can perform multiple operations and still have its result computed during compilation.

Example: Compile-Time Execution of Array Initializations

Swag.ConstExpr functions can also be used to initialize arrays or other data structures at compile time. This example demonstrates how an array of precomputed values is created.

Forcing Compile-Time Execution with #run

If a function is not marked with Swag.ConstExpr, but you still want to execute it at compile time, you can use the #run directive. This forces the compiler to execute the function during compilation and use the result in your code.

Example: Compile-Time Evaluation of Conditional Logic

Using Swag.ConstExpr or #run, you can evaluate conditional logic at compile time, enabling the embedding of decision results directly into your constants.

Example: Compile-Time Initialization of Structs

You can initialize complex data structures, such as structs, at compile time using Swag.ConstExpr. This ensures that the structure's values are determined before runtime.

Example: Using #run with User-Defined Types

In cases where Swag.ConstExpr is not used, #run can force compile-time execution even for user-defined types like structs or enums.

Function overloading

Function Overloading with Swag.Overload

In Swag, it is possible to define multiple functions with the same name as long as their parameter signatures differ. This capability, known as function overloading, allows you to provide different implementations of a function depending on the number or types of arguments passed. To enable function overloading, the functions must be decorated with the Swag.Overload attribute. This ensures that the compiler can correctly distinguish between the different versions based on the arguments provided at the call site.

In the example above, the sum function is overloaded to handle both two-parameter and three-parameter cases. When the function is called, the compiler automatically selects the appropriate version based on the number of arguments. This allows for more flexible and intuitive code, where the same function name can be used for different operations depending on the context.

Discard

Return Value Usage

In Swag, there is a strict requirement that every function's return value must be utilized. This design choice helps prevent potential bugs that can arise from accidentally ignoring the result of a function call. If a function is invoked and its return value is not used, the compiler will generate an error. This ensures that developers are consciously handling all return values, which can be critical for maintaining the correctness of the code.

Swag.Discardable Attribute

There are scenarios where the return value of a function may be optional or non-critical to the operation. In such cases, the function can be marked with the Swag.Discardable attribute. This attribute permits the caller to ignore the return value without triggering a compiler error, making it clear that the result is not necessarily intended to be used.

Retval

The retval special type

In Swag, the retval type acts as an alias to the function's return type. This feature allows developers to handle the return value within the function in a more convenient and flexible manner. By using retval, you can define and manipulate the variable intended to be returned, without explicitly specifying its type. This abstraction simplifies code maintenance and enhances readability, especially when dealing with complex return types.

Optimizing return values

The retval type also serves as an optimization hint to the compiler. When used correctly, it allows the compiler to reference the caller's storage directly, bypassing unnecessary copies of the return value. This is particularly beneficial for functions returning large or complex types, such as structs, tuples, or arrays, where performance can be significantly improved by reducing memory operations.

Returning arrays efficiently

The use of retval is highly recommended when returning large data structures like arrays or structs. By leveraging retval, you can avoid unnecessary memory operations, such as clearing or copying large objects, resulting in more efficient and performant code. This approach is especially useful in performance-critical applications where minimizing overhead is crucial.

Foreign

Interoperability with External Modules

Swag provides the ability to interoperate with external modules, such as Dynamic Link Libraries (DLLs) on Windows, which export C functions. This interoperability allows Swag code to invoke functions from these external libraries, enabling seamless integration with system-level APIs and third-party libraries. This feature is particularly powerful for extending Swag applications with capabilities provided by external systems.

Declaring External Functions

To use functions from external modules, you declare them in your Swag code with the Swag.Foreign attribute. This attribute specifies the external module where the function is located. The module name can refer to either a Swag-compiled module or an external system module, depending on your needs. The exact location of these external modules varies by operating system, so it is important to specify the correct module name based on the target platform.

Example: Windows API

In this example, two functions (ExitProcess and Sleep) are declared as external functions that reside in the kernel32.dll module, a core system library on Windows. By declaring these functions with Swag.Foreign, you can directly invoke Windows API functions within your Swag code, allowing for system-level operations such as exiting a process or pausing execution for a specified amount of time.

Linking to External Libraries

When working with external modules, it is essential to ensure that the corresponding library is linked to the final executable. This linking process is crucial because it allows the linker to resolve the references to the external functions declared in your code.

• Use the #foreignlib directive to specify which external library should be linked during the compilation process.
• This directive informs the Swag compiler to include the specified external module during the linking stage, ensuring

that all external function calls are correctly resolved at runtime.

Special functions

Main Function (#main)

The #main function is the primary entry point for the program, similar to the main() function in languages like C or C++. This function is unique within each module, meaning you can only define it once per module.

In the context of an executable program, #main is where the program's execution begins. Any code placed within this function will be the first to execute when the program runs.

Handling Program Arguments

Unlike the main() function in C, the #main function in this language does not take arguments directly. Instead, command-line arguments can be retrieved using the intrinsic @args, which provides a slice containing all the arguments passed to the program.

Here’s an example demonstrating how to work with command-line arguments:

Pre-Main Function (#premain)

The #premain function is executed after all #init functions across all modules have completed, but before the #main function begins.

This function is typically used for tasks that need to be performed after module initialization, yet before the main program logic is executed. It's useful for setup tasks that depend on the initial state of the program being fully established.

Initialization Function (#init)

The #init function is executed at runtime during the module initialization phase. You can define multiple #init functions within the same module, allowing different parts of the module to initialize independently.

The execution order of #init functions within the same module is undefined, so you should not rely on a specific sequence of initialization tasks. However, all #init functions will execute before any code in the #main or #premain functions.

Drop Function (#drop)

The #drop function acts as a cleanup function and is called when a module is unloaded at runtime. It serves as the counterpart to #init, ensuring that any resources allocated during initialization are properly released.

Just like #init, you can define multiple #drop functions within a module, and the order of their execution is undefined. However, #drop functions are guaranteed to run in the reverse order of their corresponding #init functions, ensuring a logical cleanup process.

Test Function (#test)

The #test function is a specialized function designed for testing purposes. It is typically used within the tests/ folder of your workspace and is executed only when the program is run in test mode.

This function is crucial for validating the correctness and functionality of your code in a controlled environment before it is deployed or released. It allows you to define test cases and assertions to ensure that your code behaves as expected.

Intrinsics

Intrinsics in Swag

Intrinsics are built-in functions provided by the Swag compiler that offer low-level operations, often directly mapping to specific machine instructions or providing essential compiler utilities. All intrinsics in Swag are prefixed with @, which is reserved exclusively for these functions.

This document provides a categorized list of all intrinsics available in Swag.

Base Intrinsics

These base intrinsics provide fundamental functionalities that are commonly needed across various Swag programs.

Built-in Intrinsics

These intrinsics provide essential built-in operations related to type and memory management, typically for low-level or performance-critical code.

Memory-related Intrinsics

These intrinsics offer memory management operations, allowing for fine-grained control over memory allocation, deallocation, and manipulation.

Atomic Operations

Atomic operations provide thread-safe manipulation of variables in shared memory, ensuring data consistency without the need for explicit locking mechanisms.

Math Intrinsics

These intrinsics provide various mathematical operations, including trigonometric, logarithmic, and other common functions, offering precise control over mathematical calculations in Swag programs.

Init

@init Intrinsic

The @init intrinsic in Swag is used to reinitialize a variable or a memory block to its default value. This intrinsic is especially useful when you need to reset the state of variables or memory blocks without manually setting each field or element. The ability to reset variables to their default states or to a specific value simplifies state management in Swag applications.

Reinitializing a Single Variable

To reinitialize a single variable to its default value, simply pass the variable as an argument to @init.

Reinitializing Multiple Elements

You can also specify a pointer to a memory block and the count of elements to reinitialize a specific number of elements within that memory block. This is useful for resetting arrays or parts of them.

Initializing with a Specific Value

The @init intrinsic can also initialize a variable with a specific value instead of its default. This provides a flexible way to reset variables to any desired state.

Initializing Arrays with a Specific Value

The @init intrinsic can be applied to arrays to reinitialize all elements with a specific value, ensuring consistency across the array.

Reinitializing Structs

When applied to structs, @init restores the struct to its default state as defined in its declaration. This is particularly useful for resetting complex data structures.

Specifying Initialization Values for Structs

You can also initialize a struct with specific values directly using @init, providing a convenient way to set all fields at once.

Reinitializing Arrays of Structs

The @init intrinsic can be used with arrays of structs, allowing you to reinitialize each element with specific values. This is particularly useful for resetting large data structures efficiently.

Drop

@drop Intrinsic

The @drop intrinsic calls the opDrop method if it is defined for the struct. This ensures that any necessary cleanup operations (such as freeing resources) are performed before the variable is reinitialized. @drop is particularly useful in resource management, where explicit cleanup is required before resetting the variable.

Generics

Functions

Generic Functions

A function can be made generic by specifying type parameters after the func keyword. These type parameters allow the function to operate on various types using the same implementation. The generic type parameters are placed within parentheses after func. When calling the function, the generic types are specified using funcCall'(type1, type2, ...). If there is only one generic parameter, you can omit the parentheses.

Type Deduction

Generic types can often be deduced from the function's parameters, eliminating the need to specify the type explicitly at the call site.

Using Constants as Generic Parameters

In addition to types, you can also specify constants as generic parameters.

In the example below, N is a constant of type s32.

const can be omitted when declaring constants, as an identifier followed by a type is considered a constant.

You can also assign a default value to a constant parameter.

If you declare the constant using const, the type can be omitted, and it will be deduced from the assignment expression.

Mixing Types and Constants

You can mix types and constants in generic parameters.

Structs

Generic Structs

Structs in Swag can also be made generic, allowing them to operate with different types and constants.

Where constraints

Single Evaluation

The where clause in Swag is a powerful tool for applying constraints on function invocations, ensuring that they can only be called when specific conditions are met. This feature is particularly useful in generic functions where you want to restrict the permissible types or values passed as arguments.

When the where expression evaluates to false, the function will not be considered during the call. If no alternative overloads match, the compiler will raise an error. Notably, the where expression is evaluated only once, usually during the function's instantiation. This makes it ideal for applying constraints on generic parameters in a consistent and predictable manner.

Generic Specialization

The where clause also facilitates the creation of specialized versions of generic functions. This feature allows you to provide distinct implementations based on the type or value of the parameters, enhancing flexibility and efficiency.

Block-based where Clause

The where clause can also take the form of a block returning a bool value. This allows for more complex conditional logic that may involve multiple checks, making it suitable for advanced validation scenarios.

Custom Compile-time Errors

Using the @compilererror intrinsic, you can trigger custom compile-time errors when the where condition is not met. This provides a mechanism for generating clear and specific error messages, guiding users when a function is used incorrectly.

Generic Structs with where

The where clause can also be applied to generic structs. If the condition is not met, an error will be generated immediately since there is no overload resolution for structs, providing a direct mechanism for enforcing constraints on struct instantiation.

Multiple Evaluations

By utilizing the where<call> mode, the where clause is evaluated for each function call, rather than just once per function instantiation. This is particularly useful for conditions that depend on the actual arguments passed to the function, as long as these arguments can be evaluated at compile time.

Attributes

Attributes are tags associated with functions, structures etc...

User attributes

User Attributes in Swag

Attributes in Swag serve as a powerful mechanism for annotating various elements of the code, such as functions and structs, with metadata. These annotations, defined using the attr keyword, can be leveraged for a variety of purposes, including code generation, documentation enhancement, and runtime reflection. By attaching attributes, developers can enrich their code with additional information that can be accessed both at compile-time and runtime.

Attributes with Parameters

Attributes in Swag can accept parameters in a manner similar to functions. These parameters enable the customization of the attribute's behavior or configuration when it is applied to a code element.

Attributes with Default Values

Swag attributes support parameters with default values, providing flexibility when applying attributes. This means that when such attributes are used, some or all of the parameters can be omitted, and the default values will be applied automatically.

Restricting Attribute Usage

Swag allows developers to control where an attribute can be applied through the AttrUsage specifier. By restricting an attribute's usage to specific elements (such as functions or structs), you ensure that the attribute is only used in appropriate contexts, thereby enhancing code safety and clarity.

Applying Attributes

To apply attributes in Swag, use the syntax #[attribute, attribute...] immediately before the element you wish to annotate. This syntax supports the application of multiple attributes to a single element by listing them sequentially, separated by commas.

Multiple Usages

An attribute in Swag can be designed to be applicable to multiple types of code elements by specifying a combination of AttrUsage values using a bitwise OR operation. This capability allows a single attribute to be reused across different contexts, such as both functions and structs.

Retrieving Attributes at Runtime

Swag supports the retrieval and inspection of attributes at runtime through type reflection. This feature enables dynamic interaction with the metadata associated with various code elements, allowing developers to adapt behavior based on the presence or configuration of attributes.

Predefined attributes

This is the list of predefined attributes. All are located in the reserved Swag namespace.

Scoping

Namespace

Namespaces in Swag

Namespaces in Swag provide a mechanism to organize and encapsulate symbols such as functions, variables, and types within a specific scope. By grouping related symbols together under a namespace, you can avoid naming conflicts and make your codebase more modular and maintainable. Symbols within a namespace are accessible only through the namespace unless explicitly made available outside of it.

Nested Namespaces

Swag allows you to create nested namespaces, enabling hierarchical organization of symbols. In the following example, namespace C is nested inside B, which is itself nested inside A. This structure facilitates even finer control and organization, particularly useful in large projects.

Using using with Namespaces

The using keyword allows you to import symbols from a namespace into the current scope, eliminating the need to fully qualify those symbols with the namespace name. This makes the code more concise and improves readability, particularly when working with deeply nested namespaces.

Private Scopes with private

In addition to named namespaces, Swag allows you to define a private scope using the private keyword. A private scope creates a unique, unnamed namespace that restricts access to the enclosed symbols to the current file, effectively making them private. This is particularly useful for isolating symbols that should not be accessible outside the file.

Exporting Symbols

By default, all symbols defined in a Swag source file are exported and can be accessed by other files within the same module. However, using private scopes or explicit namespaces provides a layer of protection against unintentional name conflicts, particularly in larger projects where different files may define symbols with similar or identical names.

Defer

defer Statement

The defer statement allows you to specify an expression that will be automatically executed when the current scope is exited. Since defer operates purely at compile time, the deferred expression is not evaluated until the block of code in which it is defined is left. This feature is useful for managing resources, ensuring cleanup operations, and maintaining code clarity.

Defer in a Block

The defer statement can also encapsulate multiple expressions within a block. This allows you to group together operations that should all be executed upon exiting the scope, maintaining the integrity of your logic and ensuring that all necessary actions are performed.

Defer with Control Flow

The defer expression is executed whenever the scope is exited, including in the presence of control flow statements like return, break, or continue. This behavior makes defer particularly advantageous for scenarios that require guaranteed execution of specific operations, such as resource cleanup or ensuring that certain conditions are met, regardless of how the code block is terminated.

Defer Execution Order

When multiple defer statements are declared, they are executed in the reverse order of their declaration. This ensures that the most recently deferred operation occurs first upon scope exit, providing a predictable and manageable flow of operations.

Example: Defer for Resource Management

A common use case for defer is in resource management, such as the creation and subsequent release of resources. By placing the release logic immediately after the creation logic, the code becomes more readable and ensures that resources are always properly managed, even in the event of an error or early exit.

Example: Defer in Error Handling

In more complex functions, defer proves invaluable for ensuring that resources are cleaned up reliably, even in the presence of errors or early returns. This pattern is essential for writing robust, error-resilient code that gracefully handles failure scenarios while ensuring that all necessary cleanup is performed.

Using

using with Enums and Namespaces

The using statement allows you to bring the scope of a namespace, struct, or enum into the current scope. This makes it possible to reference members directly without the need for full qualification. For example, when working with enums, this can simplify the code by removing the need to constantly prefix enum values with the enum type name.

using with Variables

The using statement can also be applied to variables, particularly those of struct types. This allows you to access the fields of a struct directly within the current scope, eliminating the need to reference the variable name each time you access a field. This is particularly useful for reducing code verbosity and improving readability.

Declaring Variables with using

You can declare a variable with the using keyword, which immediately brings the variable’s fields into the current scope. This approach can streamline your code by allowing direct access to struct fields without the need to prefix them with the variable name, making the code cleaner and more concise.

using in Function Parameters

When applied to function parameters, using allows fields of a struct to be accessed directly within the function, similar to how a this pointer works in C++. This can simplify function code by eliminating the need to repeatedly dereference a pointer or reference a parameter name, making the function logic clearer and easier to follow.

using with Struct Fields

The using statement can also be applied to a field within a struct. This allows the fields of a nested struct to be accessed as if they were part of the containing struct. This feature is especially useful when working with inheritance or composition, enabling cleaner and more intuitive code by removing unnecessary layers of field access.

With

with Statement

The with statement is designed to reduce repetition by allowing you to access the fields and methods of a variable or object within a specified scope. Inside a with block, you can use the . prefix to refer to the fields or methods of the specified object, making the code more concise and easier to read.

with on a Variable

The with statement can be used with a variable to streamline access to its fields and methods, eliminating the need to repeatedly reference the variable name. This makes the code cleaner and reduces clutter, especially when working with objects that have multiple fields or methods.

with with Function Calls

The with statement also simplifies function calls on an object or struct by allowing direct invocation of methods and access to fields within the with block. This approach helps maintain cleaner and more intuitive code by reducing the repetition of the object or variable name.

with with a Namespace

The with statement can also be applied to a namespace, allowing you to call functions or access constants within that namespace without needing to fully qualify the names. This is particularly useful when working with large namespaces or when multiple calls to namespace members are required.

with with Variable Declaration

In addition to existing variables, the with statement can be used directly with variable declarations. This allows you to immediately work with the fields of the newly declared variable within the scope of the with block, streamlining initialization and setup tasks.

with with an Assignment Statement

The with statement can also be used with an assignment, allowing you to immediately access and modify the fields of the newly assigned value. This can be particularly helpful in scenarios where you want to initialize or adjust an object’s fields immediately after creation or assignment.

Type reflection

Types as Values in Swag

In Swag, types are treated as first-class values that can be inspected and manipulated at both compile-time and runtime. This powerful feature enables advanced metaprogramming capabilities, allowing developers to write more flexible and reusable code. The primary intrinsics for interacting with types are #typeof and @kindof, which provide the ability to introspect and work with types dynamically.

Using #typeof to Inspect Types

The #typeof intrinsic allows you to retrieve the type information of an expression. When an expression explicitly represents a type, you can also directly use the type itself. This is particularly useful for type inspection and validation at compile time.

Understanding the Result of #typeof

The result of the #typeof intrinsic is a constant pointer to a Swag.TypeInfo structure. This structure serves as a type descriptor, providing detailed information about the type it describes. The Swag.TypeInfo is an alias for the typeinfo type, and each type in Swag corresponds to a specific TypeInfo structure found in the Swag namespace, which is part of the compiler runtime.

Working with TypeInfo Structures

The TypeInfo structure includes a kind field that identifies the specific category of the type, such as native type, pointer, array, or struct. This kind field is crucial when dealing with types in a more abstract or generic manner, as it allows you to differentiate between various kinds of types and handle them appropriately.

#decltype

The #decltype intrinsic performs the reverse operation of #typeof or @kindof. It converts a typeinfo structure back into an actual compiler type. This is useful when you need to dynamically determine the type of a variable based on compile-time information and then use that type within your code.

Using #decltype with Compile-Time Expressions

#decltype can evaluate a compile-time constant expression (constexpr) that returns a typeinfo to determine the actual type. This is particularly powerful when the type depends on compile-time logic, allowing for dynamic yet type-safe programming patterns.

Error management and safety

Error management

A function marked with throw indicates that it can return an error by invoking the throw keyword, followed by an error value. The error value is a struct, which encapsulates the error details. If an error occurs, the caller has the option to either halt execution and propagate the error using try, or handle the error explicitly using the @err() intrinsic.

Using throw with Custom Errors

A function that has the potential to return an error must be annotated with the throw keyword. This annotation signals that the function can raise an error using the throw statement. When an error is thrown, it is represented as a structured value, typically using a custom-defined struct to encapsulate the error information.

When a function encounters an error and exits early, the actual return value is not what the function was originally intended to return. Instead, the function returns the default value for its return type. For example, if the return type is an integer, the default value would typically be 0.

Handling Errors with catch and @err()

When calling a function that can throw an error, it's essential to handle the error appropriately. This is where the catch keyword comes into play. The error can be caught using catch, and its value can be tested (or ignored) using the @err() intrinsic. If an error is caught, it is dismissed, allowing the program to continue execution from the point where the error was handled.

Error Handling with trycatch

The trycatch construct provides an alternative way to handle errors. It allows the function to dismiss the error and exit gracefully, returning the default value if necessary. This approach ensures that no error is propagated to the caller, effectively containing the error within the current function.

Propagating Errors with try

The try keyword allows a function to halt its execution and propagate any encountered errors to its caller. The function using try must be annotated with throw, indicating that it can pass errors up the call stack.

In this example, if the function myFunc1 encounters an error, it will propagate that error to its caller, requiring the caller to handle it.

This behavior is equivalent to the following code, which uses catch to catch the error and then explicitly re-throws it.

Forcing Panic with assume

The assume keyword allows the caller to force a panic if an error occurs, rather than handling or propagating the error. This is useful in scenarios where you expect the code to run without errors, and any error should result in an immediate halt.

Implicit assume

Instead of using throw, you can annotate the entire function with assume. This treats the entire function as if every error is critical, causing an automatic panic if any error occurs.

Blocks in Error Handling

Blocks can be used in place of a single statement to group multiple operations together in error-handling constructs like try, assume, catch, and trycatch. These blocks do not create a new scope but allow you to execute several related operations under a single error-handling strategy.

Implicit try

When a function is annotated with throw, any function calls within it that can raise errors will implicitly use try unless explicitly overridden. This implicit behavior reduces verbosity in scenarios where specific error handling is not required.

The error struct

As discussed, the error value is a struct. This allows you to add specific error parameters, such as line and column numbers for syntax errors.

Using defer for Controlled Cleanup

The defer statement schedules a block of code to be executed when the function exits, whether it's through a normal return or due to an error being thrown. Since throwing an error is functionally similar to returning, defer behaves consistently in both cases.

defer can be customized with specific modes (#err or #noerr) to control its execution based on the function's exit state:

defer<err>	Executes only when an error is raised via throw.
defer<noerr>	Executes only when the function returns normally without errors.
defer	Executes regardless of how the function exits (either by returning normally or by throwing an error).

Safety

Safety Checks in Swag

Swag provides various safety checks that can be enabled at different granularity levels—module, function, or even individual instruction—using the #[Swag.Safety] attribute.

These safety checks are designed to prevent common programming errors by triggering panics during unsafe operations, such as overflows, invalid math operations, or out-of-bounds access.

You can also configure safety checks globally based on the build configuration using buildCfg.safetyGuards.

Overflow Safety

When overflow safety is enabled, Swag will panic if arithmetic operations overflow or if bits are lost during an integer conversion.

Operators that can cause overflows include: + - * << >> and their compound assignments += -= *= <<= >>=.

Disabling Overflow Safety with #over

If an overflow is expected and should not cause a panic, the #over modifier can be used with the operation to bypass the safety check.

Global Overflow Safety Control

To disable overflow safety checks globally within a scope, use #[Swag.AllowOverflow(true)]. This prevents overflows from causing panics for all operations in the scope.

Promoting Operations to Prevent Overflow

For operations involving 8-bit or 16-bit integers, you can use the #prom modifier to promote the operation to 32-bit, thereby avoiding overflow by widening the operand types.

Information Loss During Casting

Swag checks for potential information loss during type casting operations, such as when converting between different integer types.

Disabling Overflow Safety Globally

Safety checks for overflow can be globally disabled, allowing operations that would typically panic due to overflow to proceed normally.

Dynamic Cast Type Safety

Swag will panic if a cast from the any type to another type is invalid, ensuring type safety when working with dynamic types.

Swag will also panic if casting from an interface to a pointer to struct that cannot be performed.

Array Bounds Checking

Swag will panic if an index is out of range when dereferencing a sized value such as an array, a slice, or a string.

Safety When Indexing a Slice

Swag ensures that indexing operations on slices are within bounds to prevent runtime errors.

Safety When Slicing a Sized Value

Swag will panic if a slice operation goes out of bounds, ensuring safe slicing of arrays or strings.

Math Safety

Swag will panic if certain math operations are invalid, such as division by zero or invalid arguments to math functions.

Checking Invalid Math Intrinsic Arguments

Swag also checks for invalid arguments passed to certain math intrinsics, causing a panic if the arguments are unsupported or invalid.

Switch Safety

Swag will panic if a switch statement marked with #[Swag.Complete] does not cover all possible cases, ensuring exhaustive pattern matching.

Boolean Safety

Swag will panic if a boolean value is not either true (1) or false (0), enforcing strict boolean type safety.

NaN Safety

Swag will panic if a floating-point NaN (Not a Number) is used in an operation, ensuring that NaNs do not propagate through calculations.

Compile-time evaluation

One of the most powerful features of Swag is its ability to execute everything at compile-time. This capability allows Swag to function not only as a compiled language but also as a scripting language, where the compiler effectively acts as an interpreter. This flexibility enables developers to leverage compile-time execution for tasks that traditionally require runtime evaluation, resulting in more efficient and versatile code.

Constexpr

Compile-Time Function Evaluation with #[Swag.ConstExpr]

The #[Swag.ConstExpr] attribute marks a function as capable of being evaluated during compile time. This enables the compiler to resolve the function's result at compile time, provided that all inputs are also known at compile time. This approach significantly optimizes the code by precomputing values and eliminating the need for these calculations at runtime.

Functions marked with #[Swag.ConstExpr] are ideal for returning constant values or performing operations that are determined before runtime, thereby improving efficiency.

Recursive Compile-Time Evaluation

The #[Swag.ConstExpr] attribute can also be applied to more complex functions, including those that perform recursion. This allows such recursive functions to be entirely evaluated at compile time, effectively reducing runtime overhead and improving overall performance.

Compile-Time Constant Expressions

In this section, #[Swag.ConstExpr] is utilized to define a straightforward constant expression. The function returns a fixed value that the compiler resolves during compilation.

Compile-Time Conditional Logic

This example illustrates how the function isEven determines if a number is even. By marking it with #[Swag.ConstExpr], the compiler can perform this logic during the compilation phase.

Compile-Time Slice Operations

In this example, #[Swag.ConstExpr] is used to calculate the sum of elements within an array. The summation is performed during the compilation, optimizing runtime performance.

Compile-Time Fibonacci Sequence

This example showcases how #[Swag.ConstExpr] enables a recursive function to compute the Fibonacci sequence at compile time, optimizing the execution.

Compile-Time Bitwise Operations

Bitwise operations can also be evaluated at compile time using #[Swag.ConstExpr]. This example demonstrates how to check if a specific bit is set within a number.

Run

Force Compile-Time Execution with #run

The #run directive allows you to invoke a function at compile time, even if that function is not marked with the #[Swag.ConstExpr] attribute. This powerful feature enables compile-time execution of any function, regardless of its original design or intent, whether it comes from external modules, system libraries, or is defined within your code.

This capability allows you to execute any function at compile time, whether it is a system function, a function from an external module, or a user-defined function.

#run Block

The #run directive can also be used in a block format. When placed inside a block, #run enables you to execute complex logic or initialize global variables at compile time. Multiple #run blocks can exist in a program, but the execution order is undefined, so care must be taken when relying on the order of these blocks.

An example of using #run to precompute global values at compile time.

The #run block below initializes the global array G with the values [1, 2, 4, 8, 16] at compile time, ensuring that the array is fully prepared before runtime.

#test blocks are executed after #run blocks, even when run at compile time (during testing). This allows you to validate the correctness of compile-time calculations, as demonstrated below by verifying the contents of G.

The flexibility of Swag allows it to function as a scripting language. In fact, if your project only contains #run blocks, you are effectively writing a script that runs during compilation.

#run Expression

The #run directive can also be used as an expression block. The return type of the block is inferred from the return statement within it.

This technique can also be utilized to initialize a static array.

String initialization is another use case for #run blocks. The block below demonstrates how to construct a string at compile time. This is safe because the #run block creates a copy of the string, ensuring it persists beyond the block's execution.

#run blocks can also initialize plain old data (POD) structs. If necessary, you can enforce POD status on a struct by tagging it with #[Swag.ConstExpr].

Compiler instructions

#assert

The #assert directive is used to perform a static assertion during the compilation process. It ensures that a particular condition is true at compile time. If the condition evaluates to false, compilation will fail, providing an error message. This is particularly useful for enforcing compile-time invariants and validating assumptions within your code.

#defined(SYMBOL)

The #defined(SYMBOL) intrinsic checks if a given symbol exists within the current context at compile time. It returns true if the symbol is defined, and false otherwise. This is useful for conditional compilation, allowing you to verify the existence of variables, constants, or functions before using them.

#if/#elif/#else

The #if/#elif/#else directives are used for static conditional compilation. They evaluate expressions at compile time and include or exclude code based on the result. This mechanism allows you to compile different sections of code based on predefined constants or compile-time conditions.

#error/#warning

The #error and #warning directives allow you to raise compile-time errors and warnings, respectively. #error will cause the compilation to fail with a custom error message, while #warning will produce a warning message during compilation but will not stop the process. These directives are useful for enforcing compile-time checks and providing informative messages during the build process.

#global

The #global directive can be placed at the top of a source file to apply global settings or attributes across the entire file. These directives control various aspects of the compilation and symbol visibility for the entire file.

Examples:

#foreignlib

The #foreignlib directive is used to link with an external library during the compilation process. This allows your program to utilize functions, variables, and resources defined in the external library. The library name should be provided as a string.

Example:

This example links the program with the "windows.lib" library, allowing the use of Windows API functions and resources defined within that library.

Code inspection

#message Function

The #message function in Swag is a special hook that gets invoked by the compiler when specific events occur during the build process. This function allows you to intercept certain stages of compilation and execute custom actions or checks. The parameter of #message is a mask that specifies the compilation stage or event that should trigger the function. By utilizing these hooks, developers can gain deeper insights into the compilation process and perform additional processing when necessary.

Function Message Mask

For instance, when you use the Swag.CompilerMsgMask.SemFunctions flag, the #message function will be called each time a function within the module has been successfully typed. This means the function has been fully analyzed and its type information is available. Within the @compiler() interface, you can use the getMessage() method to retrieve details about the event that triggered the call, such as the function's name and type information.

Semantic Pass Completion

The compiler will invoke the following #message function after the semantic pass has completed. The semantic pass occurs after all functions within the module have been parsed and typed. This stage is ideal for performing final checks or actions that need to consider the entire module's content.

Global Variables Message Mask

The #message function can also be triggered for each global variable in the module by using the Swag.CompilerMsgMask.SemGlobals flag. This allows you to process or validate each global variable as it is encountered by the compiler during the semantic analysis phase.

Global Types Message Mask

Similarly, the Swag.CompilerMsgMask.SemTypes flag triggers the #message function for each global type in the module, such as structs, enums, and interfaces. This allows you to inspect, analyze, or modify global types during compilation.

Meta programming

Swag provides the ability to construct and inject source code at compile time. This powerful feature allows you to dynamically generate code based on compile-time conditions or inputs, and have that code seamlessly integrated into the final program. The source code is supplied as a string, and it must be a valid Swag program.

This technique opens up possibilities for advanced metaprogramming, where code can be generated, modified, or extended during the compilation process, reducing redundancy and enabling more flexible, adaptive programs.

Ast

#ast Block

The #ast block is one of the simplest methods to generate Swag code dynamically at compile time. It allows you to write code that, when executed during compilation, produces a string. This string is then compiled in place as if it were written directly in the source code.

Basic #ast Usage

A #ast block can be as straightforward as a single expression that returns the string to be compiled. This feature is highly useful for injecting dynamically generated code during compilation.

#ast Block with return

The #ast block can contain more complex logic, including multiple statements and an explicit return. The returned string will be compiled at the location of the #ast block.

#ast for Structs and Enums

The #ast block can be used to dynamically generate the content of complex types like structs or enums. This approach is particularly valuable for creating code structures based on compile-time conditions or parameters.

#ast with Generics

The #ast block can be effectively used with generics, allowing for flexible and reusable code generation patterns. This can be particularly powerful when combined with static declarations.

Constructing Strings in #ast

The #ast block requires a string-like value to be returned, which can be dynamically constructed. In this example, the string is manually built, although a more sophisticated method like Core.String is typically recommended.

Real-World Example

The following is a practical example from the Std.Core module. It demonstrates how an #ast block can generate a structure where all the fields of another structure have their types converted to bool.

#ast at Global Scope

The #ast block can also be employed at the global scope to dynamically generate global variables, constants, or other declarations. This feature allows for a high degree of flexibility in defining global entities.

#placeholder Usage

When generating global symbols that may be referenced elsewhere in the code, it is necessary to use #placeholder. This directive informs Swag that the symbol will be generated later, preventing compilation errors when the symbol is referenced before it exists.

Here, thanks to the #placeholder, the #assert will wait for the symbol myGeneratedConst to be replaced with its actual value before performing the assertion.

Compiler interface

The compileString() function within the @compiler() interface is another method to compile generated code. This function should be invoked at compile time, typically within a #message call.

Below is an example from the Std.Ogl module (an OpenGL wrapper), which utilizes #message to identify functions annotated with a specific user attribute, Ogl.Extension, and subsequently generates code for each identified function.

First, we define a new attribute that can be associated with functions.

Example of applying the custom attribute to OpenGL functions.

The following will be used to track the functions with that specific attribute.

This #message will be called for each function of the Ogl module.

We will generate a glInitExtensions global function, so we register it as a placeholder.

This code is called once all functions of the module have been typed, and it handles the main code generation process.

Documentation

The Swag compiler is capable of generating comprehensive documentation for all modules within a specified workspace.

To generate documentation for your workspace, use the following command:

Swag supports various documentation generation modes, which should be specified in the module.swg file within the Swag.BuildCfg structure.

Kind	Purpose
Swag.DocKind.Api	Generates an api documentation (all public symbols)
Swag.DocKind.Examples	Generates a documentation like this one
Swag.DocKind.Pages	Generates different pages, where each file is a page (a variation of Examples)

Markdown files

If the module contains markdown files with the .md extension, they will be processed as if they were Swag comments.

Format of comments

Paragraphs

Inside a paragraph, you can end of line with \ to force a break without creating a new paragraph.

A paragraph that starts with --- is a verbatim paragraph where every blanks and end of lines are respected. The paragraph will be generated as is without any markdown change.

Lists

You can create a list of bullet points with *.

You can create an ordered list by starting the line with a digit followed by a ..

Definition Lists

You can add a definition title with the + character followed by a blank, and then the title. The description paragraph should come just after the title, with at least 4 blanks or one tabulation.

A description can contain complex paragraphs.

The description paragraph can contain some empty lines.

Quotes

You can create a quote with >

You can create a special quote by adding a title on the first line. There must be exactly one blank between > and the title, and the title case should be respected.

• NOTE:
• TIP:
• WARNING:
• ATTENTION:
• EXAMPLE:

Tables

You can create a table by starting a line with |. Each column must then be separated with |. The last column can end with |, but this is not mandatory.

You can define a header to the table if you separate the first line from the second one with a separator like ---. A valid separator must have a length of at least 3 characters, and must only contain - or :.

You can define the column alignment by adding : at the start and/or at the end of a separator.

Code

You can create a simple code paragraph with three backticks before and after the code.

You can also create that kind of paragraph by simply indenting the code with four blanks or one tabulation.

And if you want syntax coloration, add swag after the three backticks. Only Swag syntax is supported right now.

Titles

You can define titles with #, ## ... followed by a blank, and then the text. The real level of the title will depend on the context and the generated documentation kind.

References

You can create an external reference with [name](link).

Images

You can insert an external image with .

Markdown

Some other markers are also supported inside texts.

Api

In Swag.DocKind.Api mode, swag will collect all public definitions to generate the documentation. Std.Core is an example of documentation generated in that mode.

The main module documentation should be placed at the top of the corresponding module.swg file.

Other comments need to be placed just before a function, struct or enum.

The first paragraph is considered to be the short description which can appear on specific parts of the documentation. So make it... short.

If the first line ends with a dot ., then this marks the end of the paragraph, i.e. the end of the short description.

For constants or enum values, the document comment is the one declared at the end of the line.

References

You can create a reference to something in the current module with [[name]] or [[name1.name2 etc.]]

NoDoc

You can use the #[Swag.NoDoc] attribute to prevent a certain element from showing up in the documentation.

Examples

In Swag.DocKind.Examples mode, documentation is generated systematically, with each file representing a chapter or subchapter. The following guidelines outline the structure and formatting required for effective documentation creation.

File Naming Convention

File names must adhere to the format DDD_DDD_name, where each D represents a digit. This naming convention facilitates the hierarchical organization of the documentation.

Comment Format for Documentation

To include comments in your code that should be interpreted as part of the documentation (as opposed to standard Swag comments), use the following syntax:

These comments will be processed and included in the generated documentation, ensuring that inline comments are properly formatted and contribute to the final output.

Source of Documentation

The documentation you are reading is generated from the std/reference/language module. This directory contains examples and files structured according to these guidelines, showcasing how to effectively create and manage documentation in Swag.DocKind.Examples mode.

Pages

In Swag.DocKind.Pages mode, each file generates an individual webpage, with the page name matching the file name. Aside from this distinction, the behavior is consistent with that of Swag.DocKind.Examples mode.

File Naming and Page Generation

Each file in this mode generates a separate webpage. The page name will directly correspond to the file name.

Use Case

Swag.DocKind.Pages mode is particularly useful for generating individual web pages, as demonstrated in the example directory. This mode is ideal for creating standalone pages that can be linked together or accessed independently, making it a versatile option for web-based documentation projects.