Public API

Evaluation Functions

NickelEval.nickel_eval Function

nickel_eval(code::String) -> Any

Evaluate Nickel code and return a Julia value.

Returns native Julia types: Int64, Float64, Bool, String, nothing, Vector{Any}, Dict{String,Any}, or NickelEnum.

Examples

julia> nickel_eval("1 + 2")
3

julia> nickel_eval("{ a = 1, b = 2 }")
Dict{String, Any}("a" => 1, "b" => 2)

julia> nickel_eval("let x = 5 in x * 2")
10

source

nickel_eval(code::String, ::Type{T}) -> T

Evaluate Nickel code and convert to type T. Supports Dict, Vector, and NamedTuple conversions.

Examples

julia> nickel_eval("42", Int)
42

julia> nickel_eval("{ a = 1, b = 2 }", Dict{String, Int})
Dict{String, Int64}("a" => 1, "b" => 2)

julia> nickel_eval("[1, 2, 3]", Vector{Int})
[1, 2, 3]

julia> nickel_eval("{ x = 1.5, y = 2.5 }", @NamedTuple{x::Float64, y::Float64})
(x = 1.5, y = 2.5)

source

NickelEval.nickel_eval_file Function

nickel_eval_file(path::String) -> Any

Evaluate a Nickel file. Supports import statements resolved relative to the file's directory.

Returns native Julia types: Int64, Float64, Bool, String, nothing, Vector{Any}, Dict{String,Any}, or NickelEnum.

Examples

julia> nickel_eval_file("config.ncl")
Dict{String, Any}("host" => "localhost", "port" => 8080)

source

Export Functions

NickelEval.nickel_to_json Function

nickel_to_json(code::String) -> String

Evaluate Nickel code and export to a JSON string.

Examples

julia> nickel_to_json("{ a = 1, b = "hello" }")
"{\"a\": 1,\"b\": \"hello\"}"

source

NickelEval.nickel_to_toml Function

nickel_to_toml(code::String) -> String

Evaluate Nickel code and export to a TOML string.

Examples

julia> nickel_to_toml("{ a = 1 }")
"a = 1\n"

source

NickelEval.nickel_to_yaml Function

nickel_to_yaml(code::String) -> String

Evaluate Nickel code and export to a YAML string.

Examples

julia> nickel_to_yaml("{ a = 1 }")
"a: 1\n"

source

FFI Functions

NickelEval.check_ffi_available Function

check_ffi_available() -> Bool

Check if the Nickel C API library is available.

source

NickelEval.build_ffi Function

build_ffi()

Build the Nickel C API library from source. Requires Rust (cargo). Restarts the FFI after building so you don't need to restart Julia.

source

String Macro

NickelEval.@ncl_str Macro

@ncl_str -> Any

String macro for inline Nickel evaluation.

Examples

julia> ncl"1 + 1"
2

julia> ncl"{ x = 10 }"["x"]
10

source

Lazy Evaluation

NickelEval.nickel_open Function

nickel_open(f, code::String)
nickel_open(code::String) -> NickelValue

Evaluate Nickel code shallowly and return a lazy NickelValue. Sub-expressions are evaluated on demand when accessed via .field or ["field"].

Do-block (preferred)

nickel_open("{ x = 1, y = 2 }") do cfg
    cfg.x  # => 1 (only evaluates x)
end

Manual

cfg = nickel_open("{ x = 1, y = 2 }")
cfg.x  # => 1
close(cfg)

source

NickelEval.NickelValue Type

NickelValue

A lazy reference to a Nickel expression. Accessing fields (.field or ["field"]) evaluates only the requested sub-expression. Use collect to materialize the full subtree into plain Julia types.

Examples

nickel_open("{ x = 1, y = { z = 2 } }") do cfg
    cfg.x        # => 1
    cfg.y.z      # => 2
    collect(cfg)  # => Dict("x" => 1, "y" => Dict("z" => 2))
end

source

NickelEval.NickelSession Type

NickelSession

Owns a Nickel evaluation context for lazy (shallow) evaluation. Tracks all allocated expressions and frees them on close.

Not thread-safe. All access must occur on a single thread.

source

NickelEval.nickel_kind Function

nickel_kind(v::NickelValue) -> Symbol

Return the kind of a lazy Nickel value without evaluating its children.

Returns one of: :record, :array, :number, :string, :bool, :null, :enum.

source

Types

NickelEval.NickelEnum Type

NickelEnum

Represents a Nickel enum value.

Fields

• tag::Symbol: The enum variant name

• arg::Any: The argument (nothing for simple enums)

Examples

result = nickel_eval("let x = 'Some 42 in x")
result.tag   # => :Some
result.arg   # => 42
result == :Some  # => true

result = nickel_eval("let x = 'None in x")
result.tag   # => :None
result.arg   # => nothing

source

NickelEval.NickelError Type

NickelError <: Exception

Exception thrown when Nickel evaluation fails.

Fields

• message::String: The error message from Nickel

Examples

try
    nickel_eval("{ x = }")  # syntax error
catch e
    if e isa NickelError
        println("Nickel error: ", e.message)
    end
end

source