Developer Tools

vintrospect

Tells you what a module exports, read from its real syntax tree.

Released v1.0.0 · 2026-09-28

Import

use "stdlib/introspect.ven"

Reads a Venutian source file and reports what it actually exports: its functions with their real parameter lists, its shapes with their real fields, and its behavior blocks, without running the file. It is a tool for other tools, giving them a structured answer to what a module offers instead of requiring them to parse the source themselves.

vintrospect.ven

p = new_map()
map_set(p, "name", "count")
map_set(p, "type_name", "Number")
map_set(p, "default", nothing)
print json_encode(param_signature_info(p), no)

Reference (11 functions)

param_signature_info
params_info
function_info
functions_info
field_info
shape_info
behavior_info
Module-level structure
module_structure
Entry point
introspect_module
CLI front end
print_usage
run_introspect_cli

API reference

`param_signature_info(param)`

p = new_map()
map_set(p, "name", "count")
map_set(p, "type_name", "Number")
map_set(p, "default", nothing)
print json_encode(param_signature_info(p), no)
:: {"name": "count", "type": "Number", "has_default": false, "is_star": false, "is_starstar": false}

`params_info(params)`

Maps param_signature_info over a whole list of real Param nodes.

p = new_map()
map_set(p, "name", "count")
map_set(p, "type_name", "Number")
map_set(p, "default", nothing)
p2 = new_map()
map_set(p2, "name", "extra")
map_set(p2, "type_name", nothing)
map_set(p2, "default", "[]")
print json_encode(params_info([p, p2]), no)
:: [{"name": "count", "type": "Number", "has_default": false, "is_star": false, "is_starstar": false}, {"name": "extra", "type": null, "has_default": true, "is_star": false, "is_starstar": false}]

`function_info(fn)`

fn = new_map()
map_set(fn, "name", "add")
map_set(fn, "is_tool", no)
map_set(fn, "params", [])
map_set(fn, "line", 12)
print json_encode(function_info(fn), no)
:: {"name": "add", "is_tool": false, "params": [], "line": 12}

`functions_info(fns)`

Maps function_info over a whole list of real FunctionDecl nodes.

fn = new_map()
map_set(fn, "name", "add")
map_set(fn, "is_tool", no)
map_set(fn, "params", [])
map_set(fn, "line", 12)
print json_encode(functions_info([fn]), no)
:: [{"name": "add", "is_tool": false, "params": [], "line": 12}]

`field_info(field)`

f = new_map()
map_set(f, "name", "x")
map_set(f, "type_name", "Number")
print json_encode(field_info(f), no)
:: {"name": "x", "type": "Number"}

`shape_info(shape_decl)`

f = new_map()
map_set(f, "name", "x")
map_set(f, "type_name", "Number")
shp = new_map()
map_set(shp, "name", "Point")
map_set(shp, "parent_names", [])
map_set(shp, "fields", [f])
map_set(shp, "line", 20)
print json_encode(shape_info(shp), no)
:: {"name": "Point", "parents": [], "fields": [{"name": "x", "type": "Number"}], "line": 20}

`behavior_info(behavior_decl)`

fn = new_map()
map_set(fn, "name", "add")
map_set(fn, "is_tool", no)
map_set(fn, "params", [])
map_set(fn, "line", 12)
beh = new_map()
map_set(beh, "shape_name", "Point")
map_set(beh, "methods", [fn])
print json_encode(behavior_info(beh), no)
:: {"shape": "Point", "methods": [{"name": "add", "is_tool": false, "params": [], "line": 12}]}

Module-level structure

`module_structure(statements)`

decl_fn = new_map()
map_set(decl_fn, "node_type", "FunctionDecl")
map_set(decl_fn, "name", "add")
map_set(decl_fn, "is_tool", no)
map_set(decl_fn, "params", [])
map_set(decl_fn, "line", 1)
decl_shape = new_map()
map_set(decl_shape, "node_type", "ShapeDecl")
map_set(decl_shape, "name", "Point")
map_set(decl_shape, "parent_names", [])
map_set(decl_shape, "fields", [])
map_set(decl_shape, "line", 2)
print json_encode(module_structure([decl_fn, decl_shape]), no)
:: {"functions": [{"name": "add", "is_tool": false, "params": [], "line": 1}], "shapes": [{"name": "Point", "parents": [], "fields": [], "line": 2}], "behaviors": []}

Entry point

`introspect_module(path, tests_dir = nothing)`

Introspects one real .ven file: its exported surface, and optionally its tests.

write_file("probe_fixture.ven", "make greet(name)\n    give \"hi \" + name\n\nshape Point\n    x: Number\n    y: Number\n")
print json_encode(introspect_module("probe_fixture.ven", "tests"), no)
:: {"module": "probe_fixture", "path": "probe_fixture.ven", "functions": [{"name": "greet", "is_tool": false, "params": [{"name": "name", "type": null, "has_default": false, "is_star": false, "is_starstar": false}], "line": 1}], "shapes": [{"name": "Point", "parents": [], "fields": [{"name": "x", "type": "Number"}, {"name": "y", "type": "Number"}], "line": 4}], "behaviors": [], "tests": []}

CLI front end

`print_usage()`

Prints this CLI's one-line usage message.

print_usage()
:: usage: venutian introspect <path-to-.ven-file>

`run_introspect_cli(args)`

Runs the venutian introspect CLI: parses argv and prints the JSON result.

run_introspect_cli(["probe_fixture.ven", "tests"])
:: {
  "module": "probe_fixture",
  "path": "probe_fixture.ven",
  "functions": [
    {
      "name": "greet",
      "is_tool": false,
      "params": [
        {
          "name": "name",
          "type": null,
          "has_default": false,
          "is_star": false,
          "is_starstar": false
        }
      ],
      "line": 1
    }
  ],
  "shapes": [
    {
      "name": "Point",
      "parents": [],
      "fields": [
        {
          "name": "x",
          "type": "Number"
        },
        {
          "name": "y",
          "type": "Number"
        }
      ],
      "line": 4
    }
  ],
  "behaviors": [],
  "tests": []
}

API reference

Module-level structure

Entry point

CLI front end

Get notified when vintrospect changes