Skip to content

CLAUDE.md

Latest commit

 

History

History
126 lines (92 loc) · 5.39 KB

CLAUDE.md

File metadata and controls

126 lines (92 loc) · 5.39 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What Bracmat Is

Bracmat is a programming language implemented in C (C99) for exploration and transformation of complex/unstructured data via pattern matching on tree structures (strings, XML, HTML, JSON, algebraic expressions). It includes a floating-point array subsystem called UFP (Unfancyfied Floating Point) added in 2023.

Build Commands

The project has two compilation modes that must both remain working:

From src/ (modular — each .c compiled separately):

cd src
make          # Standard build with readline (Linux/macOS), requires libreadline-dev
make potu1    # Single-source mode (-DSINGLESOURCE), no readline
make potusafe # Sandboxed build (no file ops, system calls — for JNI/Python use)
make potuurl  # Like potu, plus HTTP/HTTPS fetching via libcurl (-DHAVE_LIBCURL)

From singlesource/ (single auto-generated file):

cd singlesource
make              # Builds bracmat from generated bracmat.c
gcc bracmat.c -lm # Minimal manual build (C99 required)
make bracmaturl   # Like bracmat, plus libcurl support (-DHAVE_LIBCURL)

singlesource/bracmat.c is auto-generated by the Bracmat script singlesource/one.bra — do not hand-edit it. Regenerate it by running make in singlesource/.

Install dependencies (Linux):

sudo apt-get install libreadline-dev       # required for potu / potuurl
sudo apt-get install libcurl4-openssl-dev  # required for potuurl / bracmaturl

Running Tests

The test suite is valid.bra in the root. Run it interactively:

./src/bracmat
{?} get$"valid.bra"
{?} !r

Or in batch mode:

./src/bracmat "get'\"valid.bra\";!r"

Every bug fix and new feature requires a corresponding test added to valid.bra.

Profiling and Coverage

cd src && make profiling   # Runs valid.bra; output: bracmat1.prof
cd src && make coverage    # Runs valid.bra; then: gcov a-potu.c

Architecture

Source Organization (src/)

The ~40 .c files compile in two modes:

  • Normal mode: each .c file compiled independently; each must include all needed headers.
  • SINGLESOURCE mode: potu.c #includes all other .c files in dependency order (low-level first). The .h files that contain declarations become inactive in this mode. This order mirrors singlesource/bracmat.c.

Core Evaluation Pipeline

  1. input.c — Parses Bracmat source into an internal tree of psk (pointer-to-sk) nodes.
  2. evaluate.c — Main evaluator; dispatches on operator type (: match, & and, | or, = assign, $ call, etc.).
  3. treematch.c / stringmatch.c — Tree and string pattern matching respectively; ?var unifies, !var dereferences, @ filters atoms, # filters numbers.
  4. canonization.c — Simplifies/normalizes expressions after evaluation.
  5. functions.c — ~80 built-in functions (lst, put, get, str, map, vap, etc.). When built with -DHAVE_LIBCURL, get$ also accepts http:// / https:// URLs and fetches content via libcurl.

Data Representation

All data is a binary tree of sk nodes (defined in nodestruct.h). Node flags (30+ bits) encode the operator, type filters, and reference count in a single union. Key flag/macro definitions are in flags.h and nodedefs.h. Memory is managed via reference counting in memory.c.

Type Subsystems

Module Purpose
rational.c Exact rational arithmetic
calculation.c UFP floating-point arrays (64-bit doubles, multidimensional, no pattern matching)
hash.c Hash-table objects
xml.c XML/SGML/HTML parsing
json.c JSON parsing and output
object.c / objectdef.c OOP: classes, instances, methods
variables.c Dynamic (not lexical) scoping, unification
encoding.c / unicaseconv.c / unichartypes.c Unicode support; tables generated from UnicodeData.txt via UnicodeData.bra

Entry Point

potu.c is the main entry point. It handles interactive REPL (with optional GNU readline), batch/command-line mode, and — when SINGLESOURCE is defined — #includes all other .c files.

External Integrations

  • Python: Python-module/prythat.pyx (Cython wrapper)
  • Java: java-JNI/dk_cst_bracmat.c (JNI wrapper)
  • WebAssembly: WebAssembly/ (emscripten; see emscriptenHowToHTML.sh)

Sandboxed Build Flags

The potusafe / bracmatsafe targets disable: -DNO_C_INTERFACE -DNO_FILE_RENAME -DNO_FILE_REMOVE -DNO_SYSTEM_CALL -DNO_LOW_LEVEL_FILE_HANDLING. Use this variant when embedding Bracmat as a library in JNI or Python modules.

Key Bracmat Syntax Reference

Construct Meaning
?x Unify/bind variable x
!x Dereference variable x
@ Atom (non-compound) filter in pattern
# Number filter in pattern
e1:e2 Match e1 against pattern e2
e1&e2 Evaluate e1, then e2 (and)
e1|e2 Try e1, on failure try e2 (or)
f$arg Call function f with argument arg
v=body Define/assign v

Utility Scripts

  • lex.bra — Detects unused variables/functions and variables used outside their lexical scope.
  • project.bra — Wizard to scaffold a new Bracmat program.
  • help.bra / doc/help — Language documentation in Bracmat format; get$"help" in the REPL loads it. Generates HTML or LaTeX docs.