Spicy

https://github.com/zeek/spicy
Admin
Spicy is a parser generator and domain-specific scripting language for creating robust C++ parsers...
Tokens:141,452
Snippets:1,845
Trust Score:9.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Spicy Driver Example with &convert

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Example of using the spicy-driver with input for the &convert example.

```bash
# printf 12345 | spicy-driver -d foo.spicy
[$x=12345]
```

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

### Build and Install Spicy

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Standard commands to build, test, and install Spicy after configuration. Ensure your prefix/bin is in the PATH if installing to a non-standard location.

```bash
make
make test
make install
```

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

### Build and Install Spicy from Source

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

The standard process to configure, build, and install Spicy from its source code. Customize the installation path using the --prefix option.

```bash
# ./configure && make && make install
```

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

### Spicy Driver Example with Unit-Level &convert

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Example output for the unit-level &convert scenario.

```bash
# printf 12345678 | spicy-driver -d foo.spicy
[12, 34, 56, 78]
```

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

### Spicy Driver Example

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Example of using the spicy-driver with a simple input.

```bash
# printf '\01\02\03\04\05\06\07' | spicy-driver -d foo.spicy
[$x=1, $y=7]
```

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

### Download and Install Pre-built Binaries (macOS)

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Use these commands to download, unpack, and install Spicy binaries from a TAR archive on macOS. Ensure you remove any previous installation first and unpack via the command line to avoid macOS quarantining the files.

```none
# curl -L <link-per-above> -o spicy.tar.gz
# rm -rf /opt/spicy && mkdir /opt/spicy
# tar xf spicy.tar.gz -C /opt/spicy --strip-components 1
```

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

### Install Hilti Toolchain Components

Source: https://github.com/zeek/spicy/blob/main/hilti/toolchain/CMakeLists.txt

Installs the Hilti library, hiltic runtime, and hilti-config runtime to their respective installation directories. Also installs headers and removes a symlink.

```cmake
install(TARGETS hilti LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
install(TARGETS hiltic RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
install(TARGETS hilti-config RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

install_headers(include hilti)
install_headers(${PROJECT_BINARY_DIR}/include/hilti hilti)
install(CODE "file(REMOVE \"\$ENV\{DESTDIR\}\${CMAKE_INSTALL_FULL_INCLUDEDIR}/hilti/hilti\")")
```

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

### Install Spicy-Build Program

Source: https://github.com/zeek/spicy/blob/main/spicy/toolchain/CMakeLists.txt

Installs the 'spicy-build' program to the system's binary directory. It is copied from the runtime output directory.

```cmake
install(PROGRAMS ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/spicy-build DESTINATION ${CMAKE_INSTALL_BINDIR})
```

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

### Install Pre-commit Hooks

Source: https://github.com/zeek/spicy/blob/main/doc/development/coding-style.md

Install pre-commit hooks to enforce linting and formatting on each commit. Run this command from the root of the repository checkout.

```none
$ pre-commit install && pre-commit install --hook-type commit-msg
pre-commit installed at .git/hooks/pre-commit
pre-commit installed at .git/hooks/commit-msg
```

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

### Install Spicy Headers

Source: https://github.com/zeek/spicy/blob/main/spicy/toolchain/CMakeLists.txt

Installs the Spicy header files into the system's include directory, under a 'spicy' subdirectory. Both project-specific and binary-directory headers are installed.

```cmake
install_headers(include spicy)
install_headers(${PROJECT_BINARY_DIR}/include/spicy spicy)
```

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

### Install Runtime Libraries

Source: https://github.com/zeek/spicy/blob/main/hilti/runtime/CMakeLists.txt

Installs the main Hilti runtime and its debug variant as either ARCHIVE or LIBRARY based on the target type and destination.

```cmake
install(TARGETS hilti-rt hilti-rt-debug ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
```

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

### Install spicy-dump Executable

Source: https://github.com/zeek/spicy/blob/main/spicy/toolchain/bin/spicy-dump/CMakeLists.txt

Installs the spicy-dump executable to the runtime destination directory.

```cmake
install(TARGETS spicy-dump RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
```

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

### Spicy Driver Example with &requires (Success)

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Example of successful parsing when the &requires condition is met.

```bash
# printf '\001' | spicy-driver -d foo.spicy
[$x=1]
```

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

### Spicy Driver Batch Input Example

Source: https://github.com/zeek/spicy/blob/main/doc/toolchain.md

Example of how to generate a Spicy batch file using a Zeek script. This is used for processing multiple interleaved input flows in parallel.

```none
code.
```

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

### Vector Parsing Example Output

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Example output when parsing a vector of 5 uint8 elements.

```text
[$x=[1, 2, 3, 4, 5]]
```

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

### Spicy Driver Command Example

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

An example command line execution using the spicy-driver to parse data with a specified Spicy module.

```bash
printf '\13GET /a/b/c\n' | spicy-driver -d -p Test::A foo.spicy
```

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

### For Loop Example with Array

Source: https://github.com/zeek/spicy/blob/main/doc/programming/language/statements.md

Demonstrates iterating over an array of numbers using a for loop.

```spicy
module Test;

for ( i in [1, 2, 3] )
    print i;

for ( i in b"abc" ) {
    print i;
}

global v = vector("a", "b", "c");

for ( i in v )
    print i;
```

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

### Install Dependencies using Homebrew (macOS)

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Installs necessary build tools and libraries for Spicy using the Homebrew package manager on macOS.

```bash
# brew install bison flex cmake ninja python@3.8 sphinx-doc
# pip3 install btest
```

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

### Random Access Parsing Example

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Demonstrates random access by parsing input data twice with different sub-units. The 'start' iterator remembers its offset, allowing re-access to previously parsed data.

```spicy
module Test;

public type Foo = unit {
    on %init() { self.start = self.input(); }

    a: A { self.set_input(self.start); }
    b: B;

    on %done() { print self; }

    var start: iterator<stream>;
};

type A = unit {
    x: uint32;
};

type B = unit {
    y: bytes &size=4;
};
```

```text
# printf '\00\00\00\01' | spicy-driver -d foo.spicy
[$a=[$x=1], $b=[$y=b"\00\00\00\01"], $start=<offset=0 data=b"\00\00\00\01">]
```

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

### Install Spicy Binaries

Source: https://github.com/zeek/spicy/blob/main/spicy/toolchain/CMakeLists.txt

Installs the Spicy compiler ('spicyc'), configuration tool ('spicy-config'), and driver ('spicy-driver') executables to the system's binary directory, defined by CMAKE_INSTALL_BINDIR.

```cmake
install(TARGETS spicyc spicy-config spicy-driver RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
```

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

### Install Spicy Library

Source: https://github.com/zeek/spicy/blob/main/spicy/toolchain/CMakeLists.txt

Installs the Spicy library to the appropriate directory on the system. The destination is determined by CMAKE_INSTALL_LIBDIR.

```cmake
install(TARGETS spicy LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
```

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

### Install Spicy using RPM package

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Use this command to install Spicy when you have an RPM package. Ensure the package is in the current directory.

```none
# rpm -i spicy.rpm
```

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

### Install Spicy using DEB package

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Use this command to install Spicy when you have a DEB package. Ensure the package is in the current directory.

```none
# dpkg --install spicy.deb
```

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

### Install Dependencies using MacPorts (macOS)

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Installs necessary build tools and libraries for Spicy using the MacPorts package manager on macOS.

```bash
# port install flex bison cmake ninja python38 py38-pip
# pip install btest
```

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

### Install Headers

Source: https://github.com/zeek/spicy/blob/main/hilti/runtime/CMakeLists.txt

Installs header files to their respective locations within the Hilti runtime include directory. This includes main headers, generated headers, and 3rdparty headers.

```cmake
install_headers(include hilti/rt)
install_headers(${PROJECT_BINARY_DIR}/include/hilti/rt hilti/rt)
install(CODE "file(REMOVE \"$ENV{DESTDIR}${CMAKE_INSTALL_FULL_INCLUDEDIR}/hilti/rt/hilti\")")
```

```cmake
# Install the 3rdparty headers that we need individually.
install_headers(${PROJECT_SOURCE_DIR}/3rdparty/ArticleEnumClass-v2
                hilti/rt/3rdparty/ArticleEnumClass-v2)
install_headers(${PROJECT_SOURCE_DIR}/3rdparty/SafeInt hilti/rt/3rdparty/SafeInt SafeInt.hpp)
install_headers(${PROJECT_SOURCE_DIR}/3rdparty/tinyformat hilti/rt/3rdparty/tinyformat)
install_headers(${PROJECT_SOURCE_DIR}/3rdparty/json/include/nlohmann hilti/rt/3rdparty/nlohmann)
install_headers(${PROJECT_SOURCE_DIR}/3rdparty/json/single_include/nlohmann
                hilti/rt/3rdparty/nlohmann)
```

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

### Spicy Configuration with Compiler Launcher

Source: https://github.com/zeek/spicy/blob/main/NEWS.rst

Example of configuring Spicy with a compiler launcher. The behavior can be controlled or disabled via the HILTI_CXX_COMPILER_LAUNCHER environment variable.

```bash
--with-hilti-compiler-launcher=ccache
```

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

### Install development version of Spicy with Homebrew

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Install the current development version of Spicy from the main branch using Homebrew on macOS with the --HEAD flag.

```none
# brew install --HEAD spicy
```

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

### Install nlohmann/json Library Components

Source: https://github.com/zeek/spicy/blob/main/3rdparty/json/CMakeLists.txt

Installs the nlohmann/json library, including headers, configuration files, and targets, when JSON_Install is enabled. This ensures the library is available for other projects.

```cmake
install(
    DIRECTORY ${NLOHMANN_JSON_INCLUDE_BUILD_DIR}
    DESTINATION ${NLOHMANN_JSON_INCLUDE_INSTALL_DIR}
)
install(
    FILES ${NLOHMANN_JSON_CMAKE_PROJECT_CONFIG_FILE} ${NLOHMANN_JSON_CMAKE_VERSION_CONFIG_FILE}
    DESTINATION ${NLOHMANN_JSON_CONFIG_INSTALL_DIR}
)
if (NLOHMANN_ADD_NATVIS)
    install(
        FILES ${NLOHMANN_NATVIS_FILE}
        DESTINATION .
    )
endif()
export(
    TARGETS ${NLOHMANN_JSON_TARGET_NAME}
    NAMESPACE ${PROJECT_NAME}::
    FILE ${NLOHMANN_JSON_CMAKE_PROJECT_TARGETS_FILE}
)
install(
    TARGETS ${NLOHMANN_JSON_TARGET_NAME}
    EXPORT ${NLOHMANN_JSON_TARGETS_EXPORT_NAME}
    INCLUDES DESTINATION ${NLOHMANN_JSON_INCLUDE_INSTALL_DIR}
)
install(
    EXPORT ${NLOHMANN_JSON_TARGETS_EXPORT_NAME}
    NAMESPACE ${PROJECT_NAME}::
    DESTINATION ${NLOHMANN_JSON_CONFIG_INSTALL_DIR}
)
install(
    FILES "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.pc"
    DESTINATION ${NLOHMANN_JSON_PKGCONFIG_INSTALL_DIR}
)
```

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

### Install latest Spicy release with Homebrew

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Install the most recent stable release of Spicy using the Homebrew package manager on macOS.

```none
# brew install spicy
```

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

### Foreach Hook Example Output

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Output from the 'foreach' hook, showing the element value and the partially built vector at each step.

```text
1, []
2, [1]
3, [1, 2]
4, [1, 2, 3]
5, [1, 2, 3, 4]
```

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

### Spicy: Using Units with Defaulted Parameters as Entry Points

Source: https://github.com/zeek/spicy/blob/main/doc/release-notes.md

Example of using units with all defaulted parameters as entry points, supporting GH-941.

```spicy
unit MyUnit {
  param1: int = 1;
  param2: string = "default";
}

entry MyUnit{};

```

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

### Output of Block-Scoped Variables Example

Source: https://github.com/zeek/spicy/blob/main/doc/programming/language/variables.md

Illustrates the output when running the function with block-scoped local variables and shadowing.

```none
One
Two
Inner
Outer
```

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

### Install Spicy using TAR archive

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Unpack the TAR archive into /opt/spicy. Remove any previous installation first. This command strips the top-level directory from the archive.

```none
# rm -rf /opt/spicy && mkdir /opt/spicy
# tar xf spicy.tar.gz -C /opt/spicy --strip-components=1
```

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

### Running a Spicy Parser

Source: https://github.com/zeek/spicy/blob/main/doc/host-applications.md

Example of invoking a Spicy parser from the command line to parse HTTP request line data.

```bash
# ./my-driver my_http.hlto MyHTTP::RequestLine "$(cat data)"
```

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

### Instantiate fuzz_parser for DNS

Source: https://github.com/zeek/spicy/blob/main/ci/fuzz/CMakeLists.txt

Example of calling the `fuzz_parser` function to create a fuzz target for the dns::Message parser.

```cmake
fuzz_parser(PARSER "dns::Message" SOURCES ${CMAKE_SOURCE_DIR}/spicy-dns/analyzer/analyzer.spicy
            MODULES DNS)
```

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

### Parse HTTP Request with Spicy Driver

Source: https://github.com/zeek/spicy/blob/main/doc/index.md

This example demonstrates how to use the spicy-driver to parse an HTTP request line using the defined Spicy grammar. The output shows the parsed structure.

```bash
# echo "GET /index.html HTTP/1.0" | spicy-driver http-request.spicy
[$method=b"GET", $uri=b"/index.html", $version=[$number=b"1.0"]]

```

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

### Instantiate fuzz_parser for PNG

Source: https://github.com/zeek/spicy/blob/main/ci/fuzz/CMakeLists.txt

Example of calling the `fuzz_parser` function to create a fuzz target for the PNG::File parser.

```cmake
fuzz_parser(PARSER "PNG::File" SOURCES ${CMAKE_SOURCE_DIR}/spicy-png/analyzer/analyzer.spicy
            MODULES PNG)
```

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

### Configure HILTI_CONFIG_TOOLCHAIN_CXX_INCLUDE_DIRS

Source: https://github.com/zeek/spicy/blob/main/hilti/toolchain/CMakeLists.txt

Sets the HILTI_CONFIG_TOOLCHAIN_CXX_INCLUDE_DIRS, specifying include paths for the Hilti toolchain, including installation directories and build artifacts.

```cmake
set_config_val(
    HILTI_CONFIG_TOOLCHAIN_CXX_INCLUDE_DIRS
    "!INSTALL!${CMAKE_INSTALL_FULL_INCLUDEDIR} !BUILD!${PROJECT_SOURCE_DIR}/hilti/toolchain/include !BUILD!${PROJECT_BINARY_DIR}/include")
```

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

### Spicy Parsing Success Example

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Demonstrates a successful parsing scenario where the input `\x01` (ASCII 1) satisfies the `&requires` condition `self.x < 5` for the `Foo` unit.

```text
# printf '\001' | spicy-driver -d foo.spicy
[$x=1]

```

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

### Instantiate and Parse Data with Spicy Runtime

Source: https://github.com/zeek/spicy/blob/main/doc/host-applications.md

Compiles a host application and demonstrates instantiating a specific Spicy parser and feeding it data, then printing the parsed fields.

```bash
# clang++ -o my_http my_http-host.cc my_http___linker__.cc  my_http_MyHTTP.cc $(spicy-config --cxxflags --ldflags)
# ./my_http $'GET index.html HTTP/1.0\n'
GET, /index.html, 1.0
```

```bash
# clang++ -o my_http my_http-host.cc my_http___linker__.cc  my_http_MyHTTP.cc $(spicy-config --cxxflags --ldflags)
# ./my_http $'GET index.html HTTP/1.0\n'
GET, /index.html, 1.0
method: GET
uri: /index.html
version: number: 1.0
```

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

### List Available Parsers in Host Application

Source: https://github.com/zeek/spicy/blob/main/doc/host-applications.md

Compiles a host application and demonstrates how to list all available Spicy parsers compiled into the process using the runtime library.

```bash
# clang++ -o my_http my_http-host.cc my_http___linker__.cc  my_http_MyHTTP.cc $(spicy-config --cxxflags --ldflags)
# ./my_http
Available parsers:

    MyHTTP::RequestLine
```

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

### Initialize Type References in Spicy

Source: https://github.com/zeek/spicy/blob/main/doc/programming/language/types.md

Demonstrates how to initialize 'type' instances using 'typeinfo' or direct assignment. Shows printing of different type references.

```spicy
type S = struct {
    a: int32;
    b: int32;
};

global s1: type = typeinfo(bool);
global s2: type = typeinfo(S);
global s3: type = S;
global s4: type = typeinfo(0.5);

print s1, s2, s3, s4; # will output "bool, X::S, X::S, real"
```

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

### Spicy Driver Example with &requires (Failure)

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Example of parsing failure when the &requires condition is not met.

```bash
# printf '\010' | spicy-driver -d foo.spicy
[error] processing failed with exception of type spicy::rt::ParseError: &requires failed: ($$ < 5) (foo.spicy:7:13-7:30)
```

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

### Basic Bitfield Parsing Example

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Demonstrates parsing a bitfield where individual bits are accessed by labels. The type of the field becomes a tuple of the bit range values.

```shell
printf '\01\02\03\04' | spicy-driver -d foo.spicy
```

```text
0, 2, 0
[$f=(x1: 0, x2: 2, x3: 0)]
```

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

### Creating a Port Instance

Source: https://github.com/zeek/spicy/blob/main/doc/programming/language/types.md

Illustrates the creation of a port instance using a numerical port number and a protocol.

```spicy
port(443, tcp)
```

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

### Conditional Parsing Example Output

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Output of the conditional parsing example, showing which fields were parsed based on the conditions.

```text
[$a=1, $b=2, $c=(not set), $d=3]
```

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

### Build Custom Host Application with Spicy

Source: https://github.com/zeek/spicy/blob/main/doc/getting-started.md

A basic C++ program demonstrating how to use Spicy parsers within a custom application. Compile with spicy-build, providing your own main function.

```cpp
#include <iostream>

#include <hilti/rt/libhilti.h>

#include <spicy/rt/libspicy.h>

using spicy::rt::fmt;

int main(int argc, char** argv) {
    hilti::rt::init();
    spicy::rt::init();

    spicy::rt::Driver driver;
    auto parser = driver.lookupParser("MyHTTP::RequestLine");
    assert(parser);

    try {
        driver.processInput(**parser, std::cin);
    } catch ( const std::exception& e ) {
        std::cerr << e.what() << std::endl;
    }

    spicy::rt::done();
    hilti::rt::done();
    return 0;
}
```

```bash
# spicy-build -S -o a.out my_http.cc my_http.spicy
# echo "GET /index.html HTTP/1.0" | ./a.out
GET, /index.html, 1.0
# echo 'Hello, World!' | ./a.out
parse error: failed to match regular expression (my_http.spicy:7)
```

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

### Print Build Summary

Source: https://github.com/zeek/spicy/blob/main/CMakeLists.txt

Outputs a detailed summary of the Spicy build configuration to the console, including version, paths, compiler information, and enabled features.

```cmake
message(
    "\n====================|  Spicy Build Summary  |===================="
    "\n"
    "\nVersion:               ${SPICY_VERSION_LONG}"
    "\n"
    "\nBuild type:            ${CMAKE_BUILD_TYPE}"
    "\nBuild directory:       ${PROJECT_BINARY_DIR}"
    "\nInstall prefix:        ${CMAKE_INSTALL_PREFIX}"
    "\nBuild shared libs:     ${BUILD_SHARED_LIBS}"
    "\n"
    "\nHost system:           ${SPICY_HOST_SYSTEM}"
    "\nC compiler:            ${SPICY_C_COMPILER}"
    "\nC++ compiler:          ${SPICY_CXX_COMPILER}"
    "\n"
    "\nBuilding toolchain:    ${HAVE_TOOLCHAIN}"
    "\n"
    "\nUse ccache:            ${USE_CCACHE}"
    "\nUse clang-tidy:        ${SPICY_CLANG_TIDY}"
    "\nUse gold linker:       ${GOLD_FOUND}"
    "\nUse sanitizers:        ${SPICY_SANITIZERS}"
    "\nUse backtrace:         ${HILTI_HAVE_BACKTRACE}"
    "\n"
    "\nWarnings are errors:   ${USE_WERROR}"
    "\nPrecompile headers:    ${HILTI_DEV_PRECOMPILE_HEADERS}"
    "\n"
    "\nBison version:         ${BISON_VERSION}"
    "\nCMake version:         ${CMAKE_VERSION}"
    "\nFlex version:          ${FLEX_VERSION}"
    "\nzlib version:          ${ZLIB_VERSION_STRING}"
    "\n"
    "\n================================================================\n")
```

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

### Basic Sink Connection and Data Writing

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Demonstrates connecting a sink to a new unit instance and writing data to it. The data is then processed by the connected unit.

```spicy
module Test;

public type Foo = unit {

    sink data;

    on %init {
        self.data.connect(new Bar);
        self.data.write(b"567", 5);
        self.data.write(b"89", 8);
        self.data.write(b"012", 0);
        self.data.write(b"34", 3);
    }
};

public type Bar = unit {
    s: bytes &eod;
    on %done { print self.s; }
};
```

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

### Compiling and Running a Spicy Parser with parse1()

Source: https://github.com/zeek/spicy/blob/main/doc/host-applications.md

This command demonstrates how to compile a host application that uses a Spicy-generated parser with the `parse1` signature and then run it with sample input.

```bash
# clang++ -o my_http my_http-host.cc my_http___linker__.cc my_http_MyHTTP.cc $(spicy-config --cxxflags --ldflags)
# ./my_http $'GET index.html HTTP/1.0\n'
GET, /index.html, 1.0

```

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

### Configure Spicy Build Options

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Use these configure options to optimize the Spicy build process. Enabling ccache and Ninja can significantly speed up compilation times.

```bash
--enable-ccache
--enable-debug
--enable-sanitizer
--generator=Ninja
```

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

### Spicy: Precompilation Support for libspicy.h

Source: https://github.com/zeek/spicy/blob/main/doc/release-notes.md

Indicates precompilation support for `libspicy.h` has been added.

```c++
#include <spicy/libspicy.h>

```

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

### Add Zeek tap for Homebrew on macOS

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Before installing Spicy via Homebrew on macOS, you need to add the Zeek tap to your Homebrew installation.

```none
# brew tap zeek/zeek
```

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

### Set Initial Sequence Number for Spicy Driver

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Control the starting sequence number for the input stream when using spicy-driver. By default, it starts at zero.

```spicy
sink::set_initial_sequence_number(0);
```

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

### Run All Linters

Source: https://github.com/zeek/spicy/blob/main/doc/development/coding-style.md

Execute all configured linters standalone using the pre-commit tool. This is useful for checking code style without making a commit.

```none
$ pre-commit run -a
```

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

### Compiling and Running a Spicy Parser with parse2()

Source: https://github.com/zeek/spicy/blob/main/doc/host-applications.md

This command demonstrates how to compile a host application that uses a Spicy-generated parser with the `parse2` signature. This signature allows providing a pre-instantiated struct to be filled.

```bash
# clang++ -o my_http my_http-host.cc my_http___linker__.cc my_http_MyHTTP.cc $(spicy-config --cxxflags --ldflags)

```

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

### begin

Source: https://github.com/zeek/spicy/blob/main/doc/programming/language/types.md

Returns an iterator to the beginning of the container's content.

```APIDOC
## begin(<container>) → <iterator>

Returns an iterator to the beginning of the container’s content.
```

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

### unit::find

Source: https://github.com/zeek/spicy/blob/main/doc/autogen/types/unit.rst

Searches a *needle* pattern inside the input region defined by where the unit began parsing and its current parsing position. If executed from inside a field hook, the current parasing position will represent the *first* byte that the field has been parsed from. By default, the search will start at the beginning of that region and scan forward. If the direction is spicy::Direcction::Backward, the search will start at the end of the region and scan backward. In either case, a starting position can also be explicitly given, but must lie inside the same region.

```APIDOC
## unit::find

### Description
Searches a *needle* pattern inside the input region defined by where the unit began parsing and its current parsing position. If executed from inside a field hook, the current parasing position will represent the *first* byte that the field has been parsed from. By default, the search will start at the beginning of that region and scan forward. If the direction is ``spicy::Direcction::Backward``, the search will start at the end of the region and scan backward. In either case, a starting position can also be explicitly given, but must lie inside the same region.

### Method
unit::find

### Parameters
* **needle** (bytes) - Required - The pattern to search for.
* **dir** (spicy::Direction) - Optional - The direction to search in (default is forward).
* **start** (iterator<stream>) - Optional - An explicit starting position within the region.

### Response
* **return value** (optional<iterator<stream>>) - An iterator to the found pattern, or null if not found.
```

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

### Subunit with Parameters and Container Usage

Source: https://github.com/zeek/spicy/blob/main/doc/programming/parsing.md

Demonstrates how a subunit 'Bar' can receive parameters, specifically 'mult', and be used within a container 'Foo'. The example shows 'Bar' being instantiated multiple times within 'Foo's list of 'y', each with a different multiplier effect on the parsed integer.

```spicy
module Test;

type Bar = unit(mult: int8) {
    x: int8 &convert=($$ * mult);
    on %done { print self.x; }
};

public type Foo = unit {
    x: int8;
    y: Bar(self.x)[];
};

```

```text
# printf '\05\01\02\03' | spicy-driver -d foo.spicy
5
10
15

```

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

### string::starts_with

Source: https://github.com/zeek/spicy/blob/main/doc/autogen/types/string.rst

Checks if the string value starts with a specified prefix.

```APIDOC
## string::starts_with

### Description
Returns true if the string value starts with *prefix*.

### Parameters
* `prefix` (string): The prefix to check for.

### Returns
`true` if the string starts with the prefix, `false` otherwise.
```

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

### Build Spicy Documentation

Source: https://github.com/zeek/spicy/blob/main/doc/installation.md

Command to build the Spicy documentation. The generated HTML documentation will be located in build/doc/html.

```bash
make
```

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

### bytes::starts_with

Source: https://github.com/zeek/spicy/blob/main/doc/autogen/types/bytes.rst

Returns true if the bytes value starts with *prefix*.

```APIDOC
## bytes::starts_with

### Description
Returns true if the bytes value starts with *prefix*.

### Method
bytes::starts_with

### Parameters
#### Path Parameters
- **prefix** (bytes) - Required - The prefix to check for.

### Return Value
bool
```

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

### Get Current Time

Source: https://github.com/zeek/spicy/blob/main/doc/programming/library.md

Retrieves the current system time from the wall clock.

```spicy
function spicy::current_time() : time
```

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

### Spicy Unit Initialization with Struct Constructor

Source: https://github.com/zeek/spicy/blob/main/doc/release-notes.md

Illustrates unit initialization using a struct constructor expression, supporting GH-1036.

```spicy
type MyUnit;
  x: int;
  y: int;

let u = MyUnit(x=1, y=2);

```

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

### stream::iterator::Deref (*)

Source: https://github.com/zeek/spicy/blob/main/doc/autogen/types/stream-iterator.rst

Dereferences the iterator to get the character at the current position.

```APIDOC
## stream::iterator::Deref uint<64> op:* t:iterator<stream> op:*

### Description
Returns the character the iterator is pointing to.

### Method
`*` (Operator Overload)

### Parameters
- **t:iterator<stream>** - The iterator instance.

### Response
#### Success Response (uint<64>)
- **Character**: The byte value of the character at the iterator's position.
```

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

### bytes::iterator::Deref

Source: https://github.com/zeek/spicy/blob/main/doc/autogen/types/bytes-iterator.rst

Dereferences the iterator to get the byte value it points to.

```APIDOC
## bytes::iterator::Deref

### Description
Returns the character the iterator is pointing to.

### Signature
`uint<8> operator*(const iterator<bytes>& t)`
```

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

### vector::sub

Source: https://github.com/zeek/spicy/blob/main/doc/autogen/types/vector.rst

Extracts a subsequence of vector elements between specified start and end indices.

```APIDOC
## vector::sub (range)

### Description
Extracts a subsequence of vector elements spanning from index *begin* to (but not including) index *end*.

### Method
vector::sub

### Parameters
#### Path Parameters
- **begin** (uint<64>) - Required - The starting index (inclusive).
- **end** (uint<64>) - Required - The ending index (exclusive).

### Return Value
vector
```

```APIDOC
## vector::sub (end)

### Description
Extracts a subsequence of vector elements spanning from index *begin* to (but not including) index *end*.

### Method
vector::sub

### Parameters
#### Path Parameters
- **end** (uint<64>) - Required - The ending index (exclusive).

### Return Value
vector
```

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

### Initialize Zlib Stream

Source: https://github.com/zeek/spicy/blob/main/doc/programming/library.md

Initializes a zlib stream for decompression. The `window_bits` parameter corresponds to zlib's inflateInit2. An exception is thrown if initialization fails.

```spicy
function spicy::zlib_init(window_bits: int64) : ZlibStream
```

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

### stream::view::offset

Source: https://github.com/zeek/spicy/blob/main/doc/autogen/types/stream-view.rst

Returns the starting offset of the view within its associated stream.

```APIDOC
## stream::view::offset

### Description
Returns the offset of the view's starting position within the associated stream value.

### Returns
- uint<64> - The starting offset of the view.
```

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

### Precompile Spicy Code to Object File

Source: https://github.com/zeek/spicy/blob/main/doc/getting-started.md

Compile Spicy code into a HILTI object file (`.hlto`) using `spicyc -c` and then execute it. This allows for modular compilation.

```none
# spicyc -j -o hello.hlto hello.spicy
# spicyc -j hello.hlto
Hello, world!
```

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

### Spicy Struct Initialization

Source: https://github.com/zeek/spicy/blob/main/doc/release-notes.md

Demonstrates struct initialization in Spicy, supporting GH-842.

```spicy
type MyStruct = struct {
  x: int;
  y: int;
};

let s = MyStruct { x=1, y=2 };

```

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

### stream::view::limit

Source: https://github.com/zeek/spicy/blob/main/doc/autogen/types/stream-view.rst

Returns a new view with a specified length from the current start.

```APIDOC
## stream::view::limit

### Description
Returns a new view that keeps the current start but cuts off the end *i* characters from that beginning. The returned view will not be able to expand any further.

### Parameters
- **i** (uint<64>) - The number of characters to limit the view to from the start.

### Returns
- view<stream> - A new, limited view.
```

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

### Initialize CRC32 Computation

Source: https://github.com/zeek/spicy/blob/main/doc/programming/library.md

Returns the initial value required for starting a CRC32 checksum calculation.

```spicy
function spicy::crc32_init() : uint64
```

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

### Setup Autogenerated and Build Directories

Source: https://github.com/zeek/spicy/blob/main/hilti/toolchain/CMakeLists.txt

Configures paths for autogenerated header and source files, and ensures necessary build directories exist. Use this to manage output locations for generated code and executables/libraries.

```cmake
set(AUTOGEN_H "${PROJECT_BINARY_DIR}/include/hilti/autogen")
set(AUTOGEN_CC "${PROJECT_BINARY_DIR}/hilti/src/autogen")
file(MAKE_DIRECTORY "${AUTOGEN_H}" "${AUTOGEN_CC}")
file(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/bin" "${PROJECT_BINARY_DIR}/lib")
```

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

### Get Environment Variable

Source: https://github.com/zeek/spicy/blob/main/doc/programming/library.md

Retrieves the value of a specified environment variable, returning an optional string.

```APIDOC
## function spicy::getenv(name: string) : optional<string>

Returns the value of an environment variable, if set.
```

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

### Configure HILTI_CONFIG_LIBRARY_DIRS

Source: https://github.com/zeek/spicy/blob/main/hilti/toolchain/CMakeLists.txt

Sets the HILTI_CONFIG_LIBRARY_DIRS configuration value, specifying both installation and build paths for Hilti libraries.

```cmake
set_config_val(
    HILTI_CONFIG_LIBRARY_DIRS
    "!INSTALL!${CMAKE_INSTALL_FULL_DATADIR}/hilti !BUILD!${PROJECT_SOURCE_DIR}/hilti/lib")
```

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

### Build Executable from Spicy Code

Source: https://github.com/zeek/spicy/blob/main/doc/getting-started.md

Use `spicy-build` to compile Spicy code into a standalone executable file. This is the standard way to create deployable Spicy applications.

```none
# spicy-build -o a.out hello.spicy
# ./a.out
Hello, world!
```

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

### Define Benchmark Executable and Link Libraries

Source: https://github.com/zeek/spicy/blob/main/spicy/runtime/tests/benchmarks/CMakeLists.txt

Creates the benchmark executable and links it against the necessary Spicy runtime, Hilti runtime, and benchmark libraries. Compile options are adjusted for non-MSVC builds.

```cmake
add_executable(spicy-rt-parsing-benchmark EXCLUDE_FROM_ALL parsing.cc ${_generated_sources})
if (NOT MSVC)
    target_compile_options(spicy-rt-parsing-benchmark PRIVATE -Wall -Wno-error)
endif ()
target_link_libraries(spicy-rt-parsing-benchmark
                          PRIVATE $<IF:$<CONFIG:Debug>,spicy-rt-debug,spicy-rt>)
target_link_libraries(spicy-rt-parsing-benchmark
                          PRIVATE $<IF:$<CONFIG:Debug>,hilti-rt-debug,hilti-rt>)
target_link_libraries(spicy-rt-parsing-benchmark PRIVATE benchmark)
```

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

### Get Iterator to Container Beginning

Source: https://github.com/zeek/spicy/blob/main/doc/programming/language/statements.md

The begin operator returns an iterator pointing to the first element of a container.

```spicy
begin(<container>)
```

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

### Set Host System Information

Source: https://github.com/zeek/spicy/blob/main/CMakeLists.txt

Sets variables to capture the host system's name, version, and processor architecture.

```cmake
set(SPICY_HOST_SYSTEM "${CMAKE_SYSTEM_NAME} ${CMAKE_SYSTEM_VERSION} (${CMAKE_SYSTEM_PROCESSOR})")
```

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

### Instantiate fuzz_parser for PE

Source: https://github.com/zeek/spicy/blob/main/ci/fuzz/CMakeLists.txt

Example of calling the `fuzz_parser` function to create a fuzz target for the pe::ImageFile parser.

```cmake
fuzz_parser(PARSER "pe::ImageFile" SOURCES ${CMAKE_SOURCE_DIR}/spicy-pe/analyzer/analyzer.spicy
            MODULES PE)
```

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

### Run Spicy Parser with spicy-driver

Source: https://github.com/zeek/spicy/blob/main/doc/getting-started.md

Demonstrates how to use the `spicy-driver` tool to compile and run a Spicy parser script against standard input. Shows expected output for valid and invalid input.

```bash
# echo "GET /index.html HTTP/1.0" | spicy-driver my_http.spicy
GET, /index.html, 1.0

```

```bash
# echo "GET XXX/1.0" | spicy-driver my_http.spicy
[fatal error] terminating with uncaught exception of type spicy::rt::ParseError: parse error: parse error: failed to match regular expression (my_http.spicy:7)

```

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

### Instantiate fuzz_parser for TFTP

Source: https://github.com/zeek/spicy/blob/main/ci/fuzz/CMakeLists.txt

Example of calling the `fuzz_parser` function to create a fuzz target for the TFTP::Packet parser.

```cmake
fuzz_parser(PARSER "TFTP::Packet" SOURCES ${CMAKE_SOURCE_DIR}/spicy-tftp/analyzer/tftp.spicy
            MODULES TFTP)
```

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

### Instantiate fuzz_parser for DHCP

Source: https://github.com/zeek/spicy/blob/main/ci/fuzz/CMakeLists.txt

Example of calling the `fuzz_parser` function to create a fuzz target for the DHCP::Message parser.

```cmake
fuzz_parser(PARSER "DHCP::Message" SOURCES ${CMAKE_SOURCE_DIR}/spicy-dhcp/analyzer/analyzer.spicy
            MODULES DHCP)
```

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

### Get Iterator to Container End

Source: https://github.com/zeek/spicy/blob/main/doc/programming/language/statements.md

The end operator returns an iterator pointing past the last element of a container.

```spicy
end(<container>)
```

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

### Dynamic Loading with hilti-config

Source: https://github.com/zeek/spicy/blob/main/doc/host-applications.md

Use the `--dynamic-loading` flag with `hilti-config` when the resulting binary will dynamically load precompiled Spicy parsers.

```bash
hilti-config --dynamic-loading
```

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

### Run Zeek with Profiling Enabled

Source: https://github.com/zeek/spicy/wiki/Performance-profiling-of-Spicy-parsers

Execute Zeek with a Spicy analyzer compiled in profiling mode and enable profiling globally using `Spicy::enable_profiling=T`. This will output detailed timing results at the end of the trace.

```bash
# zeek -r -Cr trace.pcap my-analyzer.hlto Spicy::enable_profiling=T
```

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

### Configure Toolchain Library Directories

Source: https://github.com/zeek/spicy/blob/main/hilti/toolchain/CMakeLists.txt

Sets HILTI_CONFIG_TOOLCHAIN_CXX_LIBRARY_DIRS, specifying build and installation directories for libraries used by the Hilti toolchain.

```cmake
set_config_val(HILTI_CONFIG_TOOLCHAIN_CXX_LIBRARY_DIRS
               "!BUILD!${CMAKE_LIBRARY_OUTPUT_DIRECTORY} !INSTALL!${CMAKE_INSTALL_FULL_LIBDIR}")
```
Tokens:
Raw