# Copyright (c) 2020-2023 by the Zeek Project. See LICENSE for details.

module spicy;

# Ignore this module for code generation, we just need the declarations.
%skip-implementation;

# Note: Retain the formatting here, doc/scripts/autogen-spicy-lib is picking up on that.

## Specifies an address' IP family.
public type AddressFamily = enum {
    IPv4, # IP4 address
    IPv6  # IPv6 address
} &cxxname="hilti::rt::AddressFamily";

## Captures the state of base64 encoding/decoding for the corresponding library functions.
public type Base64Stream = __library_type("spicy::rt::base64::Stream");

## Specifies the bit order for individual bit ranges inside a bitfield.
public type BitOrder = enum {
    LSB0,     # bits are interpreted as lowest-significant-bit coming first
    MSB0      # bits are interpreted as most-significant-bit coming first
} &cxxname="hilti::rt::integer::BitOrder" ;

## Specifies byte order for data operations.
public type ByteOrder = enum {
    Little,   # data is in little-endian byte order
    Big,      # data is in big-endian byte order
    Network,  # data is in network byte order (same a big endian)
    Host      # data is in byte order of the host we are executing on
} &cxxname="hilti::rt::ByteOrder" ;

## Specifies the character set for bytes encoding/decoding.
public type Charset = enum {
    ASCII,
    UTF8
} &cxxname="hilti::rt::bytes::Charset";

## Specifies how data is handled that's not representable in a specified character set.
public type DecodeErrorStrategy = enum {
    IGNORE,  # data is skipped but processing continues
    REPLACE, # data is replaced with a valid place-holder and processing continues
    STRICT   # runtime error is triggered
} &cxxname="hilti::rt::bytes::DecodeErrorStrategy";

## Represents the error value of ``result<T>`` instances. Use ``error"My error message"``
## to create an error value of this type.
public type Error = __error;

## Captures state for incremental regular expression matching.
public type MatchState = struct {
} &cxxname="hilti::rt::regexp::MatchState";

## Captures stream statistics.
public type StreamStatistics = struct {
    num_data_bytes: uint64;     ## number of data bytes processed
    num_data_chunks: uint64;    ## number of data chunks processed, excluding empty chunks
    num_gap_bytes: uint64;      ## number of gap bytes processed
    num_gap_chunks: uint64;     ## number of gap chunks processed, excluding empty chunks
} &cxxname = "hilti::rt::stream::Statistics";

## Specifies a transport-layer protocol.
public type Protocol = enum {
    TCP,
    UDP,
    ICMP
} &cxxname="hilti::rt::Protocol";

## Specifies the type of a real value.
public type RealType = enum {
    IEEE754_Single, # single precision in IEEE754 format
    IEEE754_Double  # double precision in IEEE754 format
} &cxxname="hilti::rt::real::Type" ;

## Specifies the policy for a sink's reassembler when encountering overlapping data.
public type ReassemblerPolicy = enum {
    First # take the original data & discard the new data
} &cxxname="spicy::rt::sink::ReassemblerPolicy";

## Specifies a side an operation should operate on.
public type Side = enum {
    Left,    # operate on left side
    Right,   # operate on right side
    Both     # operate on both sides
} &cxxname="hilti::rt::bytes::Side" ;

## Specifies direction of a search.
public type Direction = enum {
    Forward, # search forward
    Backward, # search backward
} &cxxname="hilti::rt::stream::Direction";

## Captures the state of gzip decompression for the corresponding library functions.
public type ZlibStream = __library_type("spicy::rt::zlib::Stream");

## Initializes a zlib stream for decompression.
##
## ``window_bits``: Same as the corresponding parameter for zlib's `inflateInit2`
## (see https://www.zlib.net/manual.html).
##
## Will throw a `ZlibError` exception if initialization fails.
public function zlib_init(window_bits: int64) : ZlibStream &cxxname="spicy::rt::zlib::init" &have_prototype;

## Decompresses a chunk of data through the given zlib stream.
public function zlib_decompress(inout stream_: ZlibStream, data: bytes) : bytes &cxxname="spicy::rt::zlib::decompress" &have_prototype;

## Finalizes a zlib stream used for decompression.
public function zlib_finish(inout stream_: ZlibStream) : bytes &cxxname="spicy::rt::zlib::finish" &have_prototype;

## Encodes a stream of data into base64.
public function base64_encode(inout stream_: Base64Stream, data: bytes) : bytes &cxxname="spicy::rt::base64::encode" &have_prototype;

## Decodes a stream of base64 data back into the clear.
public function base64_decode(inout stream_: Base64Stream, data: bytes) : bytes &cxxname="spicy::rt::base64::decode" &have_prototype;

## Finalizes a base64 stream used for decoding or encoding.
public function base64_finish(inout stream_: Base64Stream) : bytes &cxxname="spicy::rt::base64::finish" &have_prototype;

## Returns the initialization value for CRC32 computation.
public function crc32_init() : uint64 &cxxname="spicy::rt::zlib::crc32_init" &have_prototype;

## Computes a running CRC32.
public function crc32_add(crc: uint64, data: bytes) : uint64 &cxxname="spicy::rt::zlib::crc32_add" &have_prototype;

## Returns the current wall clock time.
public function current_time() : time &cxxname="hilti::rt::time::current_time" &have_prototype;

## Constructs a time value from a tuple of broken-out elements specifying local time.
##
## - *y*: year (1970-...)
## - *m*: month (1-12)
## - *d*: day (1-31)
## - *H*: hour (0-23)
## - *M*: minute (0-59)
## - *S*: second (0-59)
public function mktime(y: uint64, m: uint64, d: uint64, H: uint64, M: uint64, S: uint64) : time &cxxname="hilti::rt::time::mktime" &have_prototype;

## Returns a bytes value rendered as a hex string.
public function bytes_to_hexstring(value: bytes) : string &cxxname="spicy::rt::bytes_to_hexstring" &have_prototype;

## Returns the value of an environment variable, if set.
public function getenv(name: string) : optional<string> &cxxname="hilti::rt::getenv" &have_prototype;

## Formats a time according to user-specified format string.
##
## This function uses the currently active locale and timezone to format
## values. Formatted strings cannot exceed 128 bytes.
##
## The format string can contain format specifiers supported by POSIX strftime, see
## https://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html.
##
## This function can raise ``InvalidArgument`` if the timestamp could not be
## converted to local time or formatted.
public function strftime(format: string, timestamp: time) : string &cxxname="hilti::rt::strftime" &have_prototype;

## Parses time from a string.
##
## This function uses the currently active locale and timezone to parse values.
##
## The format string can contain format specifiers supported by POSIX strptime, see
## https://pubs.opengroup.org/onlinepubs/009695399/functions/strptime.html.
##
## This function raises ``InvalidArgument`` if the string could not be parsed
## with the given format string, or ``OutOfRange`` if the parsed time value cannot
## be represented.
public function strptime(buf: string, format: string) : time &cxxname="hilti::rt::strptime" &have_prototype;

## Parses an address from a string. The address can be in standard IPv4 or IPv6
## ASCII represententation. The function raises ``InvalidArgument`` if the string
## could not be parsed.
public function parse_address(s: string) : addr &cxxname="hilti::rt::address::parse" &have_prototype;

## Parses an address from a bytes instance. The address can be in standard IPv4
## or IPv6 ASCII represententation. The function raises ``InvalidArgument`` if the
## string could not be parsed.
public function parse_address(b: bytes) : addr &cxxname="hilti::rt::address::parse" &have_prototype;

## Reports a confirmation to the host application indicating that the parser
## appears to be processing the expected input format. It's up to the host
## application how to use this information.
public function accept_input() : void &cxxname="spicy::rt::accept_input";

## Reports a violation to the host application indicating that the parser
## appears not to be processing the expected input format.  It's up to the
## host application how to use this information.
##
## Note that this does not automatically abort processing. If that's desired,
## you need to trigger a parse error as well, e.g., by throwing an error,
## `throw "<error message>"`.
##
## reason: user-presentable description of why the input seems wrong
public function decline_input(reason: string) : void &cxxname="spicy::rt::decline_input";
