# (c) 2021 Ashok P. Nadkarni
# See LICENSE for license terms.

namespace eval $NS {
    # Leading space intentional to match main content below to not confuse ruff
    variable _ruff_preamble "        This is the reference for commands in the `$::NS` namespace."
    append _ruff_preamble " See the \[Start page\]($::NS.html) for an introductory usage guide."
    append _ruff_preamble { See [Concepts][::Concepts] for a mapping of C types and program elements to the script level.}
    append _ruff_preamble {

        The package is loaded in standard fashion with `package require`:

        ````
        package require cffi
        ````
    }

    proc call {fnptr args} {
        # Invokes a C function through a function pointer.
        #  fnptr - A pointer value tagged with a
        #   [prototype][::Concepts::Prototypes and function pointers]
        #  args - additional arguments to pass to the C function
        #
        # The passed pointer $fnptr tag must corresponding to a function
        # prototype defined through the [prototype function] or
        # [prototype stdcall] commands.
        #
        # Returns the value returned by the invoked C function.
    }

    proc limits {type} {
        # Get the lower and upper limits for an integral base type
        #   type - the base type
        # Returns a pair containing the minimum and maximum values
        # for the specified type.
    }

    proc savederrors {} {
        # Return `errno` and `GetLastError()` values from the last
        # CFFI call annotated with `saveerrors`.
        #
        # For functions annotated with `saveerrors`, CFFI internally saves the
        # `errno` and (on Windows) `GetLastError()` values. The `savederrors`
        # command retrieves these as a pair with the first element being the
        # saved `errno` value and the second the `GetLastError()` result. The
        # latter is always 0 on non-Windows platforms.
    }
}

namespace eval ${NS}::pkgconfig {
    proc list {} {
        # Returns the list of keys containing information about
        # the package configuration.
    }
    proc get {key} {
        # Gets the value of a configuration key.
        # key - one of the keys returned by [pkgconfig list] command
        #
        # The following keys are supported.
        # `backend` - returns `libffi` or `dyncall` indicating the
        #   backend FFI library in use
        # `version` - the package version
        # `compiler` - identifies the compiler used to build the
        #   extension.
        #
    }
    namespace export *
    namespace ensemble create
}

namespace eval ${NS}::help {
    proc function {NAME} {
        # Returns a string describing the syntax and parameter definitions
        # for a CFFI wrapped function.
        #   NAME - name of a wrapped function
    }
    proc functions {{PATTERN *}} {
        # Returns a list of CFFI-wrapped functions matching the pattern `PATTERN`.
        #   PATTERN - glob pattern to match
        #
        # Note that like Tcl's `info commands` the pattern is interpreted relative
        # to the current namespace. So for example, to obtain the list of
        # commands within a namespace, the namespace must also be included
        # in the pattern. For example,
        #
        # ````
        # cffi::help functions ::libzip::*
        # ````
    }
    proc struct {NAME} {
        # Returns a string describing field types in a [Struct].
        #   NAME - name of a [Struct]
    }
    proc union {NAME} {
        # Returns a string describing field types in a [Union].
        #   NAME - name of a [Union]
    }
    proc alias {NAME} {
        # Returns a string describing an [alias] definition.
        #   NAME - name of a [alias]
    }
    proc enum {NAME} {
        # Returns a string describing an [enum] definition.
        #   NAME - name of a [enum]
    }

    namespace export *
    namespace ensemble create
}
