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

namespace eval ${NS}::dyncall {
    variable _ruff_preamble {
        This namespace contains classes wrapping the `dyncall` library for
        calling C functions in shared library. The namespace is automatically
        loaded with the `cffi` package.
    }
}

oo::class create ${NS}::dyncall::Symbols {
    constructor {{path {}}} {
        # Wraps a shared library / DLL to allow access to its symbols.
        #   path - path to the shared library
        #
        # It is strongly recommended that the path to the shared library be
        # specified as an absolute path. Otherwise, it is located in a
        # system-specific manner involving operating system version, environment
        # variables, registry settings (on Windows), phase of the moon etc..
        # This is not advisable for both reliability and security reasons.
        #
        # When no longer needed, the object can be deleted in the usual manner
        # (via `rename` to an empty string) or by invoking its `destroy` method.
        #
        # Objects of this class provide access to the symbols defined in
        # the file without actually loading the file and resolving addresses.
        # They can only therefore be used to search for symbols, locate symbols
        # based on their index, and if the library has been loaded already,
        # based on the symbol address.
        #
        # An error is raised if the file does not exist or does not contain an
        # exports table.
        #
        # Returns the name of the created object.
    }
    destructor {
        # Destroys the object.
        #
        # The managed shared library may be unloaded if there is nothing else
        # holding a reference to it.
    }
    method count {} {
        # Returns the number of symbols defined in the library.
    }
    method index {index} {
        # Returns the name of the symbol at a specified index.
        #  index - index into symbol table
        # The returned value may be an empty string if there is an entry
        # in the symbol table at that index but no name.
    }
    method ataddress {addr} {
        # Returns the name of the symbol at a specified address.
        #  addr - memory address
        # The shared library must have been loaded into the process.
    }
}

