µcad

https://docs.microcad.xyz/language/book/
Admin
µcad is a purely declarative markup programming language that evaluates programs like mathematical...
Tokens:38,017
Snippets:386
Trust Score:6.2
Update:10 months ago
Show doc for...
Tokens:
Raw
### CLI Export Examples with Default Formats

Source: https://docs.microcad.xyz/language/book/export

These examples illustrate how the CLI automatically determines the output file extension based on the node type. 'my_sketch.µcad' is exported to 'my_sketch.svg', and 'my_part.µcad' is exported to 'my_part.stl'.

```bash
microcad-cli export my_sketch.µcad # This is a sketch and will output `my_sketch.svg`
microcad-cli export my_part.µcad # This is a part and will output `my_part.stl`
```

--------------------------------

### Export using CLI

Source: https://docs.microcad.xyz/language/book/print

Shows basic command-line interface (CLI) usage for exporting a µcad file. The first example exports 'myfile.µcad' to its default format (SVG for sketches). The second example specifies a custom output filename and format.

```bash
µcad export myfile.µcad # -> myfile.svg

microcad-cli export myfile.µcad custom_name.svg # -> custom_name.svg
```

--------------------------------

### µcad Workbench Structure Example

Source: https://docs.microcad.xyz/language/book/structure/workbenches/index

Demonstrates the various elements of a µcad workbench, including parameters, init code, initializers, functions, properties, and building code. This example shows how to define a sketch workbench named 'Wheel' that creates a circle, with options for initialization and property access.

```µcad
// Sketch with a `radius` as building plan.
// Which will automatically become a property.
sketch Wheel(radius: Length) {
    
    // Init code...
    const FACTOR = 2;

    // Initializer #1
    init(diameter: Length) {
        // must set `radius`
        radius = diameter / FACTOR;
    }

    // No code in between!

    // Initializer #2
    init(r: Length) {
        // must set `radius`
        radius = r;
    }

    // Function (sub routine)
    fn into_diameter(r: Length) {
        return r * FACTOR;
    }

    // Building code...

    // Set a property which can be seen from outside.
    prop diameter = into_diameter(radius);
    
    // Local variable `r`
    r = radius;
    
    // Create a circle.
    std::geo2d::Circle(r);
}

use std::debug 

// Call sketch with diameter.
d = Wheel(diameter = 2cm);
// Check radius property.
assert_eq([d.radius, 1cm]);

// Call sketch with radius.
r = Wheel(radius = 2cm);
// Check diameter property.
assert_eq([r.diameter, 4cm]);

d - r;

```

--------------------------------

### µcad: Expanded Argument Multiplicity Example

Source: https://docs.microcad.xyz/language/book/flow/calls/multiplicity

Shows the expanded form of the argument multiplicity example, illustrating the individual calls generated by µcad when an array of values is provided for translation parameters. This clarifies the underlying execution without explicit loops.

```µcad
r = std::geo2d::Rect(width = 2mm, height = 2mm);

use std::ops::translate;
r.translate(x = -4mm, y = -4mm);
r.translate(x = -4mm, y = 4mm);
r.translate(x = 4mm, y = -4mm);
r.translate(x = 4mm, y = 4mm);

```

--------------------------------

### Define and Call a Simple Function

Source: https://docs.microcad.xyz/language/book/print

Provides an example of defining a function named 'print_error' that accepts a String parameter and prints an error message. It then shows how to call this function multiple times.

```ucad
// define function print_error with text as parameter of type String
fn print_error( text: String ) {
    // code body
    std::print("ERROR: {text}");
}

print_error("first");
print_error("second");
```

--------------------------------

### µcad Workbench - Initializers

Source: https://docs.microcad.xyz/language/book/structure/workbenches/index

Demonstrates the use of initializers in µcad workbenches. This example shows a 'Wheel' sketch with an initializer that attempts to redefine the 'radius' parameter, highlighting potential conflicts if initializers have the same parameters as the building plan.

```µcad
sketch Wheel(radius: Length) {
    init( radius: Length ) {} // error: same parameters as in building plan
    std::geo2d::Circle(1mm);
}

Wheel(radius = 1.0mm);

```

--------------------------------

### Import and Use External Module in Microcad

Source: https://docs.microcad.xyz/language/book/print

This example demonstrates how to include code from an external Microcad file. The 'mod' statement loads the 'second.µcad' file, making its public functions, like 'f()', available for use.

```microcad
mod second;
second::f(); 

```

--------------------------------

### Workbench Function for Geometry

Source: https://docs.microcad.xyz/language/book/print

An example of a workbench function 'PunchedDisk' that uses another internal function 'inner' to calculate geometry parameters. It demonstrates creating a sketch with defined operations.

```ucad
sketch PunchedDisk(radius: Length) {
    use std::geo2d::Circle;

    // calculate inner from radius in a method
    fn inner() { return radius/2; }

    // generate donut (and call inner)
    Circle(radius) - Circle(inner());
}

PunchedDisk(radius = 1cm);
```

--------------------------------

### µcad Workbench - Initializers with Parameter Mapping

Source: https://docs.microcad.xyz/language/book/structure/workbenches/index

Shows how initializers in µcad can be used to set building plan properties. This example defines a 'Wheel' sketch with an initializer that takes 'diameter' and sets the 'radius' property internally, while also handling a 'thickness' parameter from the building plan.

```µcad
sketch Wheel(radius: Length, thickness: Length) {
    // initializer with diameter
    init( diameter: Length, thickness: Length ) {
        // must set `radius` in code 
        radius = diameter / 2;

        // thickness (from the building plan) does not need 
        // to be set, because it was automatically set by 
        // parameter of this initializer
    }

    // Now radius and thickness can be used
    std::geo2d::Circle(radius) - std::geo2d::Circle(radius - thickness);
}

// call with building plan
Wheel(radius=5cm, thickness=1cm);
// call with initializer
Wheel(diameter=10cm, thickness=1cm);

```

--------------------------------

### Example Usage of Measures

Source: https://docs.microcad.xyz/language/book/types/models/measures

An example demonstrating how to use the built-in `area` measure with a 2D object in µcad.

```APIDOC
## Example Usage of Measures

### Description
This example calculates the area of a circle using the built-in `area` measure and compares it with the standard circle area formula.

### Code Example
```cpp
__builtin::debug::assert_eq([
    // use measure area() on a circle
    std::geo2d::Circle(radius=10mm).area(),

    // circle area formula for comparison
    10mm * 10mm * std::math::PI
]);
```

### Note
Currently, it is not possible to declare custom measures in µcad.
```

--------------------------------

### Vec3 Named Tuple Alias Example in µcad

Source: https://docs.microcad.xyz/language/book/types/collections/tuples/aliases

Presents an example of the 'Vec3' type alias for a named tuple representing a three-dimensional vector. It shows how to define a Vec3 and verify the sum of its coordinates.

```ucad
v: Vec3 = (x = 2.0, y = 3.0, z = 4.0);

std::debug::assert(v.x + v.y + v.z == 9.0);
```

--------------------------------

### Define Building Code for Sketch

Source: https://docs.microcad.xyz/language/book/print

This code defines a sketch named 'Wheel' with a radius parameter. The building code, starting after initializers, creates a 2D circle object using the provided radius. This is a fundamental example of object generation within the Microcad language.

```microcad
sketch Wheel(radius: Length) {
    // building code starts here
    std::geo2d::Circle(radius);
}

Wheel(radius = 1.0mm)
```

--------------------------------

### Using Init Code for Constants in Workbench Definition

Source: https://docs.microcad.xyz/language/book/print

Shows how to use 'init code' at the beginning of a workbench definition to declare constants. These constants, like 'FACTOR', can then be used within initializers, functions, and the main building code. The example defines a constant, uses it in an initializer and a function, and also in calculating a property.

```custom_scripting_language
sketch Wheel(radius: Length) {
    // init code
    const FACTOR = 2.0;

    // initializer
    init(diameter: Length) { into_radius(radius); }

    // function
    fn into_radius( diameter: Length ) {
        // use constant FACTOR from init code
        return diameter / FACTOR;
    }

    // set property diameter and use FACTOR from init code
    prop diameter = radius * FACTOR;
    
    // code body
    std::geo2d::Circle(radius);
}

__builtin::debug::assert(Wheel(5cm).radius == 5cm);
__builtin::debug::assert(Wheel(5cm).diameter == 10cm);

```

--------------------------------

### Import a Whole Module using 'use' in Microcad

Source: https://docs.microcad.xyz/language/book/print

This Microcad example shows how to import an entire module (std::geo2d) using the 'use' statement. This makes module symbols accessible via the module's namespace, useful when referencing multiple items from it.

```microcad
use std::geo2d;

geo2d::Circle(r = 40mm);

```

--------------------------------

### Declare Weight Quantity in µcad

Source: https://docs.microcad.xyz/language/book/types/quantities

Shows how to declare Weight quantities and provides examples for grams, kilograms, and pounds. It includes an assertion to check the equality of gram and kilogram values.

```µcad
gram = 1000.0g;
kilogram = 1.0kg;
pound = 2.204623lb;

std::debug::assert([gram, kilogram].all_equal());

```

--------------------------------

### Combining Literals into Expressions in µcad

Source: https://docs.microcad.xyz/language/book/expressions

Shows how to combine simple literals to form more complex expressions. This example multiplies a scalar literal by a quantity literal, resulting in a new quantity. The output of such expressions is not visible unless they generate a model.

```µcad
5 * 4.0mm;
```

--------------------------------

### Create a 2D Circle in Microcad

Source: https://docs.microcad.xyz/language/book/print

This snippet demonstrates the creation of a 2D circle with a specified radius using the std::geo2d library in Microcad. It's a fundamental example of generating geometric shapes.

```microcad
// simply draw a circle
std::geo2d::Circle(radius = 1cm);

```

--------------------------------

### µcad Workbench - Building Plan Properties

Source: https://docs.microcad.xyz/language/book/structure/workbenches/index

Illustrates how parameters defined in the building plan of a µcad workbench automatically become accessible properties. This example shows a 'Wheel' sketch where the 'radius' parameter is directly used to create a circle and is asserted externally.

```µcad
// sketch with a `radius` as building plan
sketch Wheel(radius: Length) {
    // access property `radius` from the building plan
    std::geo2d::Circle(radius);
}

std::debug::assert_eq([Wheel(5cm).radius, 5cm]);

```

--------------------------------

### Generate Arrays as Ranges in µcad

Source: https://docs.microcad.xyz/language/book/types/collections/arrays

Explains how to create arrays using range expressions like `[1..5]` in µcad. It highlights that ranges are inclusive of endpoints and demonstrates examples with positive and negative integers.

```ucad
std::debug::assert_eq([[1..5], [1,2,3,4,5]]);
std::debug::assert_eq([[-2..2], [-2,-1,0,1,2]]);
```

--------------------------------

### Prohibiting Code Between Initializers in Workbench

Source: https://docs.microcad.xyz/language/book/print

Demonstrates a rule in the language where it is not allowed to place any executable code between two 'init' blocks within a workbench definition. The example shows an error occurring when code is inserted between two initializers.

```custom_scripting_language
sketch Wheel(radius: Length) {
    init( width:Length ) { radius = width / 2; }
    
    radius = 1; // error: code between initializers not allowed

    init( height:Length ) { radius = height / 2; }
}

Wheel(radius = 1.0mm);

```

--------------------------------

### Warning for Redundant Arguments in µcad

Source: https://docs.microcad.xyz/language/book/flow/calls/arguments

Shows an example where providing redundant or misspelled arguments to a function might result in a warning or an error, depending on the specific implementation. This highlights the need for precise argument matching.

```ucad
fn f( x: Length, y: Length, z: Length ) {}
f( (x=1cm, y=2cm, v=5cm), z=3cm);  // error: Missing arguments: x,y
```

--------------------------------

### List Available Exports in a µcad File via CLI

Source: https://docs.microcad.xyz/language/book/export

This command lists all the exportable nodes within a µcad file, including those with assigned export attributes. The output format is a comma-separated list of node names or filenames.

```bash
microcad-cli export myfile.µcad --list # List all exports in this file: `rect, circle.svg`.
```

--------------------------------

### Aliasing Symbols with 'use as'

Source: https://docs.microcad.xyz/language/book/structure/use

Illustrates using the 'use as' syntax to locally rename imported symbols. This is particularly helpful for avoiding name conflicts or for using shorter, more convenient aliases. The example renames 'std::geo2d::Circle' to 'disk'.

```ucad
use std::geo2d::Circle as disk;

disk(r = 4mm);
```

--------------------------------

### Color Named Tuple Alias Example in µcad

Source: https://docs.microcad.xyz/language/book/types/collections/tuples/aliases

Demonstrates the usage of the 'Color' type alias for a named tuple representing RGBA color values. It shows how to declare a color and assert its red channel value.

```ucad
color: Color = (r = 100%, g = 50%, b = 25%, a = 100%);

std::debug::assert(color.r == 100%);
```

--------------------------------

### Define and Call Function with Return Value (µcad)

Source: https://docs.microcad.xyz/language/book/flow/calls/function_calls

Shows how to define a function that returns a value in µcad. It includes an example of calling the function and asserting its return value using `std::debug::assert_eq`. The `return` keyword is essential.

```µcad
// function definition
fn f() {
    // return statement
    return 1; 
}

// function call (and result check)
std::debug::assert_eq([ f(), 1 ]);

```

--------------------------------

### Define and Call Function with Parameters (µcad)

Source: https://docs.microcad.xyz/language/book/flow/calls/function_calls

Illustrates defining a function that accepts parameters and returns a value based on those parameters in µcad. It provides examples of calling the function with different arguments and verifying the results. The parameter list is defined within parentheses after the function name.

```µcad
// function definition with parameter
fn f(n: Integer) {
    return n * 2; 
}

// function calls with parameter (and result checks)
std::debug::assert_eq([ f(1), 2 ]);
std::debug::assert_eq([ f(2), 4 ]);

```

--------------------------------

### Define a Sketch Workbench with Parameters and Initializers

Source: https://docs.microcad.xyz/language/book/print

Demonstrates a complete workbench definition including a building plan with a 'radius' parameter, init code, multiple initializers to set the radius based on different inputs (diameter or direct radius), a helper function, and building code to define a 'diameter' property and create a Circle object. It also shows how to invoke the sketch and assert its properties.

```custom_scripting_language
// Sketch with a `radius` as building plan.
// Which will automatically become a property.
sketch Wheel(radius: Length) {
    
    // Init code...
    const FACTOR = 2;

    // Initializer #1
    init(diameter: Length) {
        // must set `radius`
        radius = diameter / FACTOR;
    }

    // No code in between!

    // Initializer #2
    init(r: Length) {
        // must set `radius`
        radius = r;
    }

    // Function (sub routine)
    fn into_diameter(r: Length) {
        return r * FACTOR;
    }

    // Building code...

    // Set a property which can be seen from outside.
    prop diameter = into_diameter(radius);
    
    // Local variable `r`
    r = radius;
    
    // Create a circle.
    std::geo2d::Circle(r);
}

use std::debug::*;

// Call sketch with diameter.
d = Wheel(diameter = 2cm);
// Check radius property.
assert_eq([d.radius, 1cm]);

// Call sketch with radius.
r = Wheel(radius = 2cm);
// Check diameter property.
assert_eq([r.diameter, 4cm]);

d - r;

```

--------------------------------

### Alias Module Symbols with 'use as'

Source: https://docs.microcad.xyz/language/book/print

Demonstrates how to alias specific symbols or entire modules using the 'use as' keyword for clarity and to resolve name conflicts. This is useful when importing from modules that might have overlapping names.

```ucad
use std::geo2d::Circle as disk;
disk(r = 4mm);

use std::geo2d as geo;
geo::Circle(r = 4mm);
```

--------------------------------

### Scalar Literals in µcad

Source: https://docs.microcad.xyz/language/book/expressions/literals

Scalar literals represent floating-point numbers, which can include a decimal point and an exponent. They can also be represented as percentages. Examples show various formats, including those starting or ending with a decimal point, scientific notation, and percentage values.

```plaintext
1.23;
0.3252;
.4534;
1.;
-1200.0;
12.0E+12;
50%    // = 0.5
```

--------------------------------

### Export µcad File via CLI

Source: https://docs.microcad.xyz/language/book/export

This snippet demonstrates the basic command to export a µcad file using the CLI. The output filename defaults to the input filename with the appropriate extension. For example, exporting 'myfile.µcad' will result in 'myfile.svg' if it's a sketch.

```bash
µcad export myfile.µcad # -> myfile.svg
```

--------------------------------

### Export Specific Node from µcad File via CLI

Source: https://docs.microcad.xyz/language/book/export

This command allows you to export a specific node from a µcad file by its name, using the `--target` option. This is useful for exporting individual components from a mixed-content file. For example, exporting the 'rect' node results in 'rect.svg'.

```bash
microcad-cli export myfile.µcad --target rect  # Export rectangle node to `rect.svg`
```

--------------------------------

### Vec2 Named Tuple Alias Example in µcad

Source: https://docs.microcad.xyz/language/book/types/collections/tuples/aliases

Illustrates the use of the 'Vec2' type alias for a named tuple representing a two-dimensional vector. Includes an example of declaration and an assertion for the sum of its components.

```ucad
v: Vec2 = (x = 2.0, y = 3.0);

std::debug::assert(v.x + v.y == 5.0);
```

--------------------------------

### µcad Function and Workbench Calls

Source: https://docs.microcad.xyz/language/book/print

Demonstrates how to define and call functions and workbenches in µcad. Functions return values, while workbenches return object nodes. Operations are called differently. Argument matching uses named parameters.

```µcad
// function definition
fn square(x: Scalar) { return x * x; }

// call function square with parameter 2 and store result in s
s = square(x = 2);

// check value
std::debug::assert_eq( [s, 4] );
```

```µcad
// definition of a sketch workbench
sketch Square(size: Length) { 
    std::geo2d::Rect(size);
}

// call square with a size and store object node in s
s = Square(size=2cm);

// translate object s
s.std::ops::translate(x = 1cm);
```

```µcad
// function definition
fn f() {}

// function call
f();
```

```µcad
// function definition
fn f() {
    // return statement
    return 1; 
}

// function call (and result check)
std::debug::assert_eq([ f(), 1 ]);
```

```µcad
// function definition with parameter
fn f(n: Integer) {
    return n * 2;
} 

// function calls with parameter (and result checks)
std::debug::assert_eq([ f(1), 2 ]);
std::debug::assert_eq([ f(2), 4 ]);
```

```µcad
fn f( x: Length, y: Length, z: Length ) {}

f(x = 1cm, y = 2cm, z = 3cm);
```

--------------------------------

### µcad Constant Assignment Examples

Source: https://docs.microcad.xyz/language/book/assignments/const

Demonstrates constant assignments in µcad. Constants are stored in the symbol table and can be declared publicly within modules. Examples show basic constant declaration, public constants in modules, and their usage.

```ucad
const TEXT = "Hello";

mod my_module {
    pub const TEXT = "Hello";
}

std::print(TEXT);
std::print(my_module::TEXT);

```

--------------------------------

### Quantity Declaration with Literals

Source: https://docs.microcad.xyz/language/book/print

Demonstrates declaring quantities with units using literals. Shows defining a length, using a default value in a function parameter, and performing arithmetic operations with quantities.

```µcad
// declare variable `height` of type `Length` to 1.4 Meters
height = 1.4m;

// use as *default* value in parameter list
fn f( height = 1m ) {}

// calculate a `Length` called `width` by multiplying the
// `height` with `Scalar` `2` and add ten centimeters
width = height * 2 + 10cm;
```

--------------------------------

### Building Code with Initializer

Source: https://docs.microcad.xyz/language/book/print

This snippet demonstrates how building code executes after initializers in a sketch definition. The 'Wheel' sketch has an initializer that sets the radius based on a provided diameter, and the building code then uses this radius to draw a circle.

```microcad
sketch Wheel(radius: Length) {
    // initializer
    init( diameter: Length ) { radius = diameter / 2; }

    // building code starts here
    std::geo2d::Circle(radius);
}
```

--------------------------------

### Set Color Attribute to White

Source: https://docs.microcad.xyz/language/book/attributes

This example shows how to set the 'color' attribute of a model node 'c' to white. Similar to the red color example, this affects the node's visual representation. The assertion confirms the color is set to white (R=1.0, G=1.0, B=1.0, A=1.0).

```µcad
#[color = "#FFFFFF"]
c = std::geo2d::Circle(42.0mm);

std::debug::assert_eq([c#color, (r = 1.0, g = 1.0, b = 1.0, a = 1.0)]);

```

--------------------------------

### Create and Use Arrays in microcad

Source: https://docs.microcad.xyz/language/book/print

Demonstrates the creation and basic operations of arrays in microcad, including initialization, counting elements, and accessing the head and tail. Arrays store multiple values of the same type.

```microcad
[
    // First element
    1,

    // Second element
    2
];
```

```microcad
std::debug::assert_eq([std::count([1,2,3]), 3]);
```

```microcad
std::debug::assert_eq([std::head([1,2,3]), 1]);
std::debug::assert_eq([std::tail([1,2,3]), [2,3]]);
```

--------------------------------

### Define a 3D Part

Source: https://docs.microcad.xyz/language/book/print

This is a basic definition of a 3D 'part' named 'MyPart'. Parts are the primary way to create 3D objects in Microcad. This example shows an empty part definition.

```microcad
part MyPart() {}
```

--------------------------------

### Load TOML File and Access Values in µcad

Source: https://docs.microcad.xyz/language/book/print

Demonstrates how to load a TOML configuration file using `std::import` and access its values within the µcad language. This is useful for managing settings or data external to the main code.

```µcad
data = std::import("example.toml");

std::debug::assert_eq([data.M10.diameter, 10.0]);
std::debug::assert_eq([data.M6.pitch, 1.0]);
```

--------------------------------

### µcad Conditional Statements (If-Else)

Source: https://docs.microcad.xyz/language/book/print

Shows how to use 'if-else' and chained 'if-else if-else' statements in µcad workbenches to control the execution flow and select different geometric constructions based on input parameters. Also demonstrates function-level conditional logic with 'or' and 'and' operators.

```µcad
use std::ops::*;
use std::math::*;
use std::geo2d::*;

sketch MySketch(a: Integer) {
    if a == 1 {
        Circle(1cm)
    } else {
        Rect(1cm)
    }
}

MySketch([1,2]).align(X, 1cm);
```

```µcad
use std::ops::*;
use std::math::*;
use std::geo2d::*;

sketch MySketch(a: Integer) {
    if a == 1 {
        Circle(1cm)
    } else if a == 2 {
        Rect(1cm)
    } else {
        Hexagon(1cm)
    }
}

MySketch([1,2,3]).align(X, 1cm);
```

```µcad
fn f(x: Integer) {
    if x == 5 or x == 4 {
        std::print("match");
    } else if x > 0 and x < 4 {
        std::print("no match");
    } else {
        std::print("invalid");
    }
}

f(5);  // prints "match"
f(1);  // prints "no match"
f(-1); // prints "invalid"
f(6);  // prints "invalid"
```

--------------------------------

### Integer Literals in µcad

Source: https://docs.microcad.xyz/language/book/expressions/literals

Integer literals represent whole numbers, optionally with a sign. They do not include units. Examples demonstrate positive, negative, and zero values.

```plaintext
50;
1350;
-6
```

--------------------------------

### Array Unit Bundling and Arithmetic in µcad

Source: https://docs.microcad.xyz/language/book/types/collections/arrays

Demonstrates how µcad supports unit bundling with arrays, allowing units to be applied after array brackets. It also shows basic arithmetic operations (addition, subtraction, multiplication, division, negation) on arrays with units.

```ucad
std::debug::assert_eq([ [1mm, 2mm, 3mm], [1, 2, 3]mm ]);
```

```ucad
std::debug::assert_eq([ [1,2]mm + 2mm, [3,4]mm ]);
```

```ucad
std::debug::assert_eq([ [1,2]mm - 2mm, [-1,0]mm ]);
```

```ucad
std::debug::assert_eq([ [-0.5mm,0.5mm]*2, [-1,1]mm ]);
```

```ucad
std::debug::assert_eq([ [-1.0mm,1.0mm]/2, [-0.5, 0.5]mm ]);
```

```ucad
std::debug::assert_eq([ [-1.0mm,1.0mm], -[1.0mm, -1.0mm] ]);
```

--------------------------------

### µcad Variable Declaration Rule: Initialization Required

Source: https://docs.microcad.xyz/language/book/types/index

Shows an example of an invalid variable declaration in µcad. Declarations without initialization are not permitted and will result in a parse error.

```µcad
x: Length;         // parse_error
```

--------------------------------

### Create and Initialize Arrays as Lists in µcad

Source: https://docs.microcad.xyz/language/book/types/collections/arrays

Demonstrates the creation and initialization of arrays as ordered collections of values in µcad. This includes basic array literal syntax and comments.

```ucad
[
    // First element
    1,

    // Second element
    2
];
```

--------------------------------

### Declare Volume Quantity in µcad

Source: https://docs.microcad.xyz/language/book/types/quantities

Illustrates the declaration of Volume quantities, formed by multiplying three Length quantities. It includes a volume calculation example and a demonstration of various volume units.

```µcad
a = 3mm;
b = 2mm;
c = 4mm;

volume = a * b * c;

std::debug::assert(volume == 24mm³);

// Here is an example for units:
cubic_millimeter = 1000000.0mm³;
cubic_centimeter = 100.0cl;
cubic_meter = 0.001m³;
cubic_inch = 61.0237in³;
liter = 1.0l;
centiliter = 100.0cl;
milliliter = 1000.0ml;

std::debug::assert(cubic_millimeter == 1.0l);
std::debug::assert(cubic_centimeter == 1.0l);
std::debug::assert(cubic_meter == 1.0l);
std::debug::assert(centiliter == 1.0l);
std::debug::assert(milliliter == 1.0l);

```

--------------------------------

### Variations of Named Tuple Calls in µcad

Source: https://docs.microcad.xyz/language/book/flow/calls/arguments

Demonstrates various ways to call a function using named tuples, including fully named tuples, tuple variables, and combinations with single values. This highlights the versatility of named tuple argument passing.

```ucad
fn f( x: Length, y: Length, z: Length ) {}

// Every parameter given by name
f( x=1cm, y=2cm, z=3cm);

// Parameters given by named tuple
f( (x=1cm, y=2cm, z=3cm) );

// Parameters given by named tuple variable
p = (x=1cm, y=2cm, z=3cm);
f( p );

// Parameters given by named tuple and a single value
f( (x=1cm, y=2cm), z=3cm );
f( y=2cm, (x=1cm, z=3cm) );

// Parameters given by named tuple variable and a single value
q = (x=1cm, y=2cm);
f( q, z=3cm );
```

--------------------------------

### Declare Area Quantity in µcad

Source: https://docs.microcad.xyz/language/book/types/quantities

Demonstrates the declaration of Area quantities, which result from multiplying two Length quantities. It shows a basic area calculation and examples of using different areal units.

```µcad
a = 3cm;
b = 2cm;
area = a * b;
std::debug::assert(area == 6cm²);

// Here is an example of how to use different areal units:
square_millimeter = 100000mm²;
square_centimeter = 1000cm²;
square_meter = 0.1m²;
square_inch = 155in²;

std::debug::assert(square_millimeter == 0.1m²);
std::debug::assert(square_centimeter == 0.1m²);

```

--------------------------------

### Error: Public Function in Workbench

Source: https://docs.microcad.xyz/language/book/print

Illustrates an error scenario where 'pub fn' is used inside a workbench definition, which is not permitted. Public functions can only be defined within standard modules.

```ucad
part PunchedDisk(radius: Length) {
    pub fn inner() { return radius/2; }   // error: cant use pub fn inside workbench
}

PunchedDisk(4.0mm);
```

--------------------------------

### Declare Angle Quantity in µcad

Source: https://docs.microcad.xyz/language/book/types/quantities

Provides examples for declaring Angle quantities in different units like radians, degrees, gradians, and turns. It uses an assertion to confirm the equivalence of these angle representations.

```µcad
pi = std::math::PI;
radian = 1rad * pi;
degree = 180°;
degree_ = 180deg;
grad = 200grad;
turn = 0.5turns;

std::debug::assert( [degree, degree_, grad, turn, radian].all_equal() );

```

--------------------------------

### Grouping Units with Arrays for Tuple Assignment in µcad

Source: https://docs.microcad.xyz/language/book/types/collections/tuples/assignments

Explains how to group units using arrays, which are then converted into tuples during assignment. This method is practical for scenarios where direct tuple grouping is not supported.

```µcad
(width, height) = [1,2]m;
assert_eq([width,1m]);
assert_eq([height,2m]);

```

--------------------------------

### Disallow Code Between Initializers in Microcad XYZ

Source: https://docs.microcad.xyz/language/book/structure/workbenches/index

Illustrates the restriction against placing any executable code between initializers within a sketch. This example shows an error occurring when code is inserted between two `init` blocks.

```Microcad XYZ
__
sketch Wheel(radius: Length) {
    init( width:Length ) { radius = width / 2; }
    
    radius = 1; // error: code between initializers not allowed

    init( height:Length ) { radius = height / 2; }
}

Wheel(radius = 1.0mm);

```

--------------------------------

### Prohibited Statements in Workbench Code (Microcad XYZ)

Source: https://docs.microcad.xyz/language/book/structure/workbenches/index

Highlights the statements that are not allowed within workbench code in Microcad XYZ. The example demonstrates an error that occurs when using the `sketch` statement inside a workbench.

```Microcad XYZ
__
sketch Wheel(radius: Length) {
    sketch Axis(length: Length) {}  // error
    std::geo2d::Circle(radius);
}

Wheel(radius = 1.0mm);

```

--------------------------------

### Generate Arrays Using Ranges in microcad

Source: https://docs.microcad.xyz/language/book/print

Illustrates how to create arrays using range expressions in microcad. Ranges include both endpoints and support integers. Invalid ranges (e.g., decreasing endpoints or non-integer endpoints) will result in errors.

```microcad
std::debug::assert_eq([[1..5], [1,2,3,4,5]]);
std::debug::assert_eq([[-2..2], [-2,-1,0,1,2]]);
```

```microcad
[6..1];  // error
[2..-2];  // error
```

```microcad
[1.0..2.0];  // parse_error
```

--------------------------------

### Define and Call Function in µcad

Source: https://docs.microcad.xyz/language/book/flow/calls

Demonstrates how to define a simple function 'square' that returns the square of its input scalar. It also shows how to call this function with a parameter and store the result. An assertion is used to verify the output.

```µcad
// function definition
fn square(x: Scalar) { return x * x; }

// call function square with parameter 2 and store result in s
s = square(x = 2);

// check value
std::debug::assert_eq( [s, 4] );
```

--------------------------------

### Function with Invalid Return Value in µcad

Source: https://docs.microcad.xyz/language/book/structure/functions

Shows an example of a function `pow` where returning a value in multiple branches, including a default return at the end, leads to an error. This highlights restrictions on return statements.

```µcad
fn pow( x: Scalar, n: Integer ) {
    if n > 1 {
        return x * pow(x, n-1); // return recursive product
    }
    return x;   // error
}

std::print(pow(8.0,2));

```

--------------------------------

### Importing All Symbols from a Module with Wildcard

Source: https://docs.microcad.xyz/language/book/structure/use

Explains the use of the wildcard '*' in a 'use' statement to import all symbols from a module into the current scope. This is the most concise way to use multiple symbols from a single module, but requires careful management to avoid name collisions.

```ucad
use std::geo3d::*;

Sphere(r = 4mm);
Cube(size = 40mm);
```

--------------------------------

### Declare Properties in Building Plan and Code

Source: https://docs.microcad.xyz/language/book/print

This code illustrates two ways to declare properties: as a parameter ('outer') and using the 'prop' keyword within the building code ('inner'). It defines a 'Wheel' sketch, generates it, and then prints the values of both properties, demonstrating their accessibility.

```microcad
// `outer` will automatically become a property because
// it is declared in the building plan:
sketch Wheel(outer: Length) {
    use std::geo2d::Circle;

    // `inner` is declared as property and maybe read from 
    // outside this workbench
    prop inner = outer / 2;

    // generate wheel (and use property inner)
    Circle(outer) - Circle(inner);
}

// evaluate wheel
t = Wheel(1cm);

// extract and display `outer` and `inner` from generated wheel
std::print("outer: {t.outer}");
std::print("inner: {t.inner}");
```

--------------------------------

### µcad Tuple with Named Values

Source: https://docs.microcad.xyz/language/book/types/collections/tuples/index

Demonstrates the creation and assertion of a tuple with named values in µcad. It showcases how to access tuple elements by their identifiers and verify the entire tuple's structure and content.

```µcad
use std::debug::assert_eq;

tuple = (width=10cm, depth=10cm, volume=1l);

assert_eq([tuple.width, 10cm]);
assert_eq([tuple.depth, 10cm]);
assert_eq([tuple.volume, 1l]);

assert_eq([tuple, (width=10cm, depth=10cm, volume=1l)]);

```

--------------------------------

### Invalid Statements in Workbench Code

Source: https://docs.microcad.xyz/language/book/print

This example shows an error that occurs when using disallowed statements like 'sketch' within workbench code. The code attempts to define a nested sketch 'Axis' inside 'Wheel', which is not permitted and will result in a compilation error.

```microcad
sketch Wheel(radius: Length) {
    sketch Axis(length: Length) {}  // error
    std::geo2d::Circle(radius);
}

Wheel(radius = 1.0mm);
```

--------------------------------

### Export Specific Node using CLI

Source: https://docs.microcad.xyz/language/book/print

Illustrates how to use the µcad CLI to export a specific node from a µcad file. The '--list' option shows available exports, and '--target' selects a node for export.

```bash
microcad-cli export myfile.µcad --list # List all exports in this file: `rect, circle.svg`.
microcad-cli export myfile.µcad --target rect  # Export rectangle node to `rect.svg`
```

--------------------------------

### µcad Logging: Error and Todo

Source: https://docs.microcad.xyz/language/book/print

Shows how to use `std::log::error` for critical issues and `std::log::todo` as a placeholder for unfinished code in µcad. `std::log::error` will halt execution, while `std::log::todo` is a reminder for future implementation.

```µcad
std::log::error("this should not have happened"); // error
```

```µcad
a = 0;

if a == 0 {
    std::log::info("a is zero");
} else {
    std::log::todo("print proper message");
}
```

--------------------------------

### Define a 2D Sketch

Source: https://docs.microcad.xyz/language/book/print

This code defines a 2D sketch named 'MySketch' using basic geometric shapes (Circle and Rect). Sketches are used for creating 2D objects and can be extruded into 3D parts. This example demonstrates a simple combination of 2D shapes.

```microcad
use std::geo2d::*;
sketch MySketch( radius: Length) {
    Circle(radius) - Rect(radius);
}

MySketch(1cm);
```

--------------------------------

### Property Declaration without 'prop' Keyword

Source: https://docs.microcad.xyz/language/book/print

This example shows the consequence of omitting the 'prop' keyword when declaring a variable within building code. The variable 'inner' is treated as a local variable and cannot be accessed from outside the sketch, leading to an error when attempting to print its value.

```microcad
sketch Wheel(outer: Length) {
    use std::geo2d::Circle;

    // `inner` is declared as variable and may not be read
    // from outside this workbench
    inner = outer / 2;

    Circle(outer) - Circle(inner);
}

t = Wheel(outer = 1cm);

// you can still extract and display `outer`
std::print("outer: {t.outer}");
// but you cannot access `inner` anymore
std::print("inner: {t.inner}"); // error
```

--------------------------------

### Importing an Entire Module with 'use'

Source: https://docs.microcad.xyz/language/book/structure/use

Shows how to import an entire module using the 'use' statement. This makes all symbols within the module available directly, provided their names do not conflict with existing symbols. Useful when many symbols from a module are frequently used.

```ucad
use std::geo2d;

geo2d::Circle(r = 40mm);
```

--------------------------------

### Module with Public and Private Functions

Source: https://docs.microcad.xyz/language/book/print

Shows a module 'math' containing both a private function 'pow' and a public function 'square'. 'square' can be called externally, while 'pow' is only accessible within the 'math' module.

```ucad
// module math
mod math {
    // pow cannot be called from outside math
    fn pow( x: Scalar, n: Integer ) {
        if n == 1 {
            x   // return x
        } else {
            x * pow(x, n-1) // return recursive product
        }
    }

    // square is callable from outside math
    pub fn square(x: Scalar) {
        // call internal pow
        pow(x, 2)
    }
}

// call square in math
math::square(2.0);
math::pow(2.0, 5);  // error: pow is private
```

--------------------------------

### Named Argument Matching in µcad

Source: https://docs.microcad.xyz/language/book/flow/calls/arguments

Demonstrates calling a function with all arguments specified by name. This approach improves code readability by explicitly labeling each argument with its parameter name.

```ucad
fn f( x: Length, y: Length, z: Length ) {}

f(x = 1cm, y = 2cm, z = 3cm);
```

--------------------------------

### Variable vs. Property Declaration in Microcad XYZ

Source: https://docs.microcad.xyz/language/book/structure/workbenches/index

Contrasts declaring a variable versus a property within a sketch. This example shows that a variable declared without the `prop` keyword cannot be accessed from outside the workbench, leading to an error.

```Microcad XYZ
__
sketch Wheel(outer: Length) {
    use std::geo2d::Circle;

    // `inner` is declared as variable and may not be read
    // from outside this workbench
    inner = outer / 2;

    Circle(outer) - Circle(inner);
}

t = Wheel(outer = 1cm);

// you can still extract and display `outer`
std::print("outer: {t.outer}");
// but you cannot access `inner` anymore
std::print("inner: {t.inner}"); // error

```

--------------------------------

### µcad Value Assignment Scope Restrictions

Source: https://docs.microcad.xyz/language/book/assignments/values

Shows that value assignments in µcad are restricted to code bodies and cannot be used within modules or initialization code. This example demonstrates errors when attempting to assign variables in these disallowed contexts.

```ucad
mod my_module {
    a = 1; // error
}

sketch MySketch() {
    a = 1;   // error
    init(_x : Scalar) {}
}

MySketch();
```

--------------------------------

### Define Constants with Init Code in Microcad XYZ

Source: https://docs.microcad.xyz/language/book/structure/workbenches/index

Demonstrates how to use init code to define constants that can be accessed throughout the sketch, including within initializers, functions, and property assignments. This init code must be placed at the top of the workbench body.

```Microcad XYZ
__
sketch Wheel(radius: Length) {
    // init code
    const FACTOR = 2.0;

    // initializer
    init(diameter: Length) { into_radius(radius); }

    // function
    fn into_radius( diameter: Length ) {
        // use constant FACTOR from init code
        return diameter / FACTOR;
    }

    // set property diameter and use FACTOR from init code
    prop diameter = radius * FACTOR;
    
    // code body
    std::geo2d::Circle(radius);
}

__builtin::debug::assert(Wheel(5cm).radius == 5cm);
__builtin::debug::assert(Wheel(5cm).diameter == 10cm);

```

--------------------------------

### µcad Variable Assignment and Usage

Source: https://docs.microcad.xyz/language/book/assignments/values

Demonstrates how to assign values to variables in µcad, reuse them in expressions, and verify their values using assertions. Variables are immutable within their scope. This example requires the `std::debug` module for assertions.

```ucad
a = 5;
b = a * 2;
std::debug::assert_eq([a,5]);
std::debug::assert_eq([b,10]);
```

--------------------------------

### Define and Call a Function in microcad

Source: https://docs.microcad.xyz/language/book/flow/calls/index

Demonstrates how to define a simple function 'square' that takes a scalar input and returns its square. It then shows how to call this function with an argument and verify the result using an assertion. This requires the Scalar type and std::debug::assert_eq.

```microcad
// function definition
fn square(x: Scalar) { return x * x; }

// call function square with parameter 2 and store result in s
s = square(x = 2);

// check value
std::debug::assert_eq( [s, 4] );

```
Tokens:
Raw