Crate janetrs

Expand description

§Janetrs

A crate with high level bindings to Janet C API.

§Goals

Provide a safe and ergonomic interface to the Janet C API to create Janet clients and Janet modules/libraries using Rust.

This project still are in it’s early stages, so breaking changes may happen, there is no minimal supported Rust version (MSRV) yet.

Notice that most doc tests will fail if the feature “amalgation” or “link-system” aren’t set, because most of then need it for the Janet runtime to function properly.

§Cargo Features

std (default): Enable some trait impl for types that only exist on the std
unicode (default): Enable more methods for JanetString and JanetBuffer
inline-more: More aggressive inlining
amalgation (default): Link the Janet runtime to the package, enabling to use the client module
system: Use system header to get Janet functions
link-system: Link the Janet runtime to the package from the system, enabling to use the client module
nightly: Enable some parts of the crate that uses nightly features, to use this feature you must compile the crate using a nightly rust version

§Environment variables

These variables are only used when the amalgation feature is enabled

It is possible to use environment variables to overwrite some Janet definitions.

JANET_RECURSION_GUARD=<integer>
JANET_MAX_PROTO_DEPTH=<integer>
JANET_MAX_MACRO_EXPAND=<integer>
JANET_STACK_MAX=<integer>

§Licensing

This software is licensed under the terms of the MIT Public License.

§TODO: Types/Traits: Lacking or Incomplete

Marshaling

[ ]: Lacking [I]: Incomplete [X]: Done

Probably there is much more missing, for that you can use the lowlevel module to access the raw C API of Janet if needed

§TODO: Lib level

Better docs.
Marshalling mechanism

Modules§

allocator: This module provides a allocator that uses the Janet scratch memory API to create objects tracked by the Janet Garbage Collector.
array: Janet array (vector) type.
buffer: Janet buffer (string) type.
clientamalgation or link-system: This module implements anything required to run a Janet client.
env: Module for the Janet VM environment structure, methods and functions.
fiber: Janet fibers (soft threads) type.
function: Janet function types.
io: Module for I/O related types and functions
janet_abstract: Module of the JanetAbstract abstractions.
lowlevel: This module has a expose the entire Janet C-API structures, constants and functions.
pointer: Module for the Janet Pointer type.
string: Janet String type.
structs: Janet Struct (immutable HashMap) type.
symbol: Janet symbols and keywords types.
table: Janet table (mutable HashMap) type.
tuple: Janet tuple type.
util: Module for stuff that are not required either to use in a application or to write janet modules.

Macros§

array: Creates a JanetArray containing the arguments.
assert_deep_eq: Like assert_eq, but using deep_eq` internally instead.
assert_deep_ne: Like assert_ne, but using deep_ne` internally instead.
bad_slot: A macro helper to use the default message when getting the wrong types in the function argument when the situations that are more complex than the ones handled in JanetArgs, like multiple accepted types.
check_janet_version: Checks the specified version of Janet is equal of the used Janet. Emits a boolean.
declare_janet_mod: Declare a Janet module.
janet_modDeprecated: A macro to make life easier creating modules for Janet from Rust.
jcatch: Execute a function (JanetCFunction, Rust function or extern C function) and catch any janet panic that may happen as a Result.
jpanic: Causes a panic in the Janet side (exception). Differently of the Rust panic! macro, this macro does not terminate the current thread. Instead, it sends a error signal with the passed message where the Janet runtime takes care to properly exit.
jtrystd: Macro that tries to run a expression, and if it panics in the Rust side, it tries to recover from that and pass the Rust panic string to a Janet Panic.
structs: Creates a JanetStruct containing the arguments key-value pairs.
table: Creates a JanetTable containing the arguments key-value pairs.
tuple: Creates a JanetTuple containing the arguments.

Structs§

Janet: Janet is the central structure of the Janet Language.
JanetAbstract: Type that represents the Janet Abstract type.
JanetArray: Janet arrays are a fundamental datatype in Janet. Janet Arrays are values that contain a sequence of other values.
JanetBuffer: Janet buffers are the mutable version of JanetStrings. Since Janet strings can hold any sequence of bytes, including zeros, buffers share this same property and can be used to hold any arbitrary memory, which makes them very simple but versatile data structures. They can be used to accumulate small strings into a large string, to implement a bitset, or to represent sound or images in a program.
JanetFiber: A lightweight green thread in Janet. It does not correspond to operating system threads.
JanetFunction: A representation of a Janet function defined at the Janet side.
JanetGc: The Janet Garbage Collector type.
JanetGcLockGuard: An RAII implementation of a “scoped lock” of the Janet GC. When this structure is dropped (falls out of scope), the lock will be unlocked.
JanetGcRootGuard: An RAII implementation of a rooted Janet value. When this structure is dropped (falls out of scope), the rooting will be undone.
JanetKeyword: Janet keyword. Janet being a lisp-like language a keyword is not a especial word of the language, it is a normal string that can be defined by the user.
JanetPointer: Janet pointer type.
JanetRng: Type representing the Janet pseudorandom number generator
JanetString: Janet strings are a immutable type that are similar to Janet buffers.
JanetStruct: JanetStructs are immutable data structures that map keys to values.
JanetSymbol: Janet symbol type. Usually used to name things in Janet.
JanetTable: Janet tables are mutable data structures that map keys to values. Values are put into a Janet table with a key, and can be looked up later with the same key. Tables are implemented with an underlying open hash table, so they are quite fast and cache friendly.
JanetTuple: Janet tuples are immutable, sequential types that are similar to Janet arrays.

Enums§

JanetConversionError: The error when converting Janets to C Janet types.
JanetSignal: Signals that can be produced by a JanetFunction and JanetCFunction representing that those worked correctly or not.
JanetType: Representation of all Janet types.
TaggedJanet: Janet type in the form of a Tagged Union.

Traits§

DeepEq: A trait to express a deep equality.
IsJanetAbstract: The trait that encodes the information required to instantiate the implementer as JanetAbstract.
JanetArgs: Trait that only exist to extend methods over [Janet] so it’s easier to get janet_fn args.
JanetExtend: Trait that express the ability of a Janet collection to extend it with another collection.
JanetTypeName: Trait defining the name of the type known to Janet

Type Aliases§

JanetCFunction: C function pointer that is accepted by Janet as a type.

Attribute Macros§

cjvg: Conditional Janet Version Gate
janet_fn: Macro that creates from a high-level Janet function (fn(&mut [Janet]) -> Janet) to the kind of function the Janet C API is expecting (fn(i32, *mut janetrs::lowlevel::Janet) -> janetrs::lowlevel::Janet) with a modified name with _c postfix.
janet_version: Conditional Janet Version Gate

Crate janetrsCopy item path