Skip to content
jonruttanPublic

About

The object, type and heap layer under x-lang's C engine: atoms, pairs and a collector, in C89.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

x-expr -- Computational Expressions in C

x-expr, with Bitwise the owl

A minimal C library providing a foundation object system with atoms, pairs, garbage collection, and a light type system. It is the object, type and heap layer under x-engine-c, the C engine of x-lang, which carries it as the submodule ext/x-expr and reaches the C library only through this library's x_sys_* and x_lib_* functions.

Features

  • Minimal, self-contained object system (atoms and pairs)
  • Light type system with runtime type checking
  • Optional garbage collection (-DX_HEAP)
  • No stdlib dependency (provides its own system abstractions)
  • ANSI C compliant, portable across architectures
  • Suitable as a foundation for Lisp-like interpreters

Quick Start

#include "x-base.h"

/* Create a base environment */
struct x_base_t conf = { STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO };
x_obj_t *base = x_base_make(NULL, conf);

/* Make atoms and pairs */
x_obj_t *a = x_mksatom(base, X_OBJ_FLAG_NONE, (x_obj_t *)42);
x_obj_t *p = x_mkspair(base, X_OBJ_FLAG_NONE, a, NULL);

/* Access data */
printf("%ld\n", x_atomint(a));             /* 42 */
printf("%ld\n", x_atomint(x_firstobj(p))); /* 42 */

See examples/hello.c for a complete working program.

Building

make          # Build static library (libx-expr.a)
make test     # Run unit tests
make doc      # Generate HTML + man page documentation
make install  # Install to /usr/local (override with PREFIX=...)

Run make help for the full list of targets.

Compile-Time Flags

Supported -- tested in CI:

Flag Default Description
X_HEAP on Enable heap management and mark-sweep garbage collection
X_USE_STDLIB off Delegate x-lib functions to standard library equivalents
DEBUG off Enable debug output macros (x_debug, x_obj_dump)

Experimental -- functional but not CI-tested:

Flag Default Description
X_PROFILE off Enable allocation profiling counters
X_SYS_CLOCK off Enable CPU clock measurement (x_sys_clock)
X_USE_STDLIB_NONSTD off Use non-standard library extensions (requires X_USE_STDLIB)

Internal -- for x-expr development:

Flag Default Description
X_OPT_MEMZERO off Zero allocated memory in x_lib_memdup
X_SYS_FUNC identity Macro to redirect system calls at compile time

Pass flags to the compiler: make CFLAGS+="-DX_HEAP -DDEBUG"

API Overview

Header Purpose
x.h Core types (x_int_t, x_char_t), architecture detection, error handling
x-sys.h System-level wrappers (malloc, free, read, write, exit)
x-lib.h Portable string, memory, and math utilities
x-stdlib.h Stand-ins for standard C library functions, or wrappers over the real ones under X_USE_STDLIB
x-obj.h Object system: atoms, pairs, flags, type checking, allocation
x-base.h Base environment: I/O, hooks, heap config, field accessors
x-heap.h Mark-sweep garbage collection (requires X_HEAP)
x-lisp.h Lisp-style aliases: cons, car, cdr, setcar, setcdr

Base Tree Layout

The base environment is a nested pair tree whose field positions are accessed via macros in x-base.h. The library is before 1.0 and the layout is not frozen: it changed between 0.1.0 and 0.2.0. Read a field through its macro, not by position.

Thread Safety

x-expr assumes single-threaded execution. The heap chain, garbage collector, and field stack operations are not synchronized. If you need to use x-expr from multiple threads, you must provide your own external synchronization around all object allocation, GC, and base environment mutation.

Usage as a Submodule

Add x-expr to your project:

git submodule add https://github.com/jonruttan/x-expr.git ext/x-expr

In your Makefile, add the include path and sources:

X_EXPR_DIR=ext/x-expr
CFLAGS+=-I$(X_EXPR_DIR)/include -DX_HEAP
X_EXPR_SOURCES=$(wildcard $(X_EXPR_DIR)/src/*.c)

Project Structure

include/     C headers
src/         C source files
tests/       Unit tests using test-runner submodule
examples/    Example programs
docs/        Documentation and contributor guide

Documentation

Generate the API reference with make doc. Output is written to docs/ref/html/ (HTML) and docs/ref/man/ (man pages).

Contributing

See docs/contributing.md for development setup, code style, and pull request guidelines.

Licence

MIT No Attribution (MIT-0). See LICENSE.

Bitwise

About

The object, type and heap layer under x-lang's C engine: atoms, pairs and a collector, in C89.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages