Crate janetrs

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: Enable some trait impl for types that only exist on the std and the Error trait
• unicode: Enable more methods for JanetString and JanetBuffer
• inline-more: More aggressive inlining
• amalgation: Link the Janet runtime to the package, enabling to use the client module
• unicode: Enable some unicode methods for JanetString and JanetBuffer
• 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

Re-exports

• pub use evil_janet as lowlevel;

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 environment structure and methods.
• 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.
• 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.
• 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.
• JanetConversionError
  The error when converting Janets to C Janet types.
• 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

• 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 tranforms a high-level Janet function (fn(&mut [Janet]) -> Janet) to the thing the Janet C API is expecting (fn(i32, *mut janetrs::lowlevel::Janet) -> janetrs::lowlevel::Janet)
• janet_version
  Conditional Janet Version Gate