Homoiconic C

A universal language for code and data.

Introduction

Homoiconic C (HC) is a single universal language for code and data. This monorepo contains the first implementation of HC as an interpreter written in TypeScript running on Deno.

The repository includes several packages:

• @swanfactory/hclang - Core library published to JSR
• CLI - Interactive REPL and command-line tools
• MAML - Multipurpose Abstract Markup Language, a radically simple proposal for replacing web technologies (HTML, CSS, JavaScript, SVG) with a single format based on HC
• Web - Web components and Fresh framework integration

HC can also be used to define easily-parseable variants of other common file formats (e.g., HCSV, HCSON).

Quick Start

Try it Online

Visit hclang.deno.dev to try HC directly in your browser with no installation required.

Use as a Library

# Deno
deno add jsr:@swanfactory/hclang

# Node.js/npm
npx jsr add @swanfactory/hclang

Then in your code:

import { execute } from "@swanfactory/hclang";

const result = execute("1 + 1");
console.log(result); // Output: '2'

See the library documentation for more details.

Run the CLI

With Node.js 24 or newer, run the current CLI directly from npm. Deno is not required:

# Interactive REPL
npx hclang@latest

# Evaluate a file
npx hclang@latest path/to/program.hc

# Verify executable examples in an HC document
npx hclang@latest path/to/examples.hc --testdoc

From source:

git clone https://github.com/TheSwanFactory/hclang.git
cd hclang
deno task hc

This will launch the interactive HC interpreter.

Run Tests

deno task test

Usage

Available Tasks

The root deno.json provides several tasks:

Task	Description
deno task hc	Launch the HC REPL
deno task setup	Install pre-commit hooks
deno task test	Run all tests (setup, format, lint, and tests)
deno task test:setup	Run all pre-commit hooks on all files
deno task test:cli	Test CLI package
deno task test:lib	Test library package
deno task test:maml	Test MAML package
deno task test:web	Test web package
deno task test:bs	Test BitScheme documentation
deno task test:doc	Test HC documentation examples
deno task build	Build native, npm, and web artifacts
deno task build:npm	Generate the Node.js CLI package in dist/npm
deno task test:npm	Pack and smoke-test the CLI package through npx

BitScheme

BitScheme is a specialized scripting language for declaratively parsing, manipulating, and generating binary data. It includes executable documentation that can be tested:

deno task test:bs

This runs the BitScheme interpreter on its own documentation, executing embedded code examples and verifying outputs.

Debug Mode

Enable verbose debugging output:

export DEBUG=true
deno task hc

Development

Setup

1. Clone the GitHub repository:

   git clone https://github.com/TheSwanFactory/hclang.git
   cd hclang

2. Install Deno:

   # macOS
   brew install deno
   
   # Other platforms: see https://deno.land/

3. (Optional) Install pre-commit for automatic code quality checks:

   # macOS
   brew install pre-commit
   
   # Other platforms: pip install pre-commit

   Pre-commit hooks are automatically installed when you run deno task test or manually with deno task setup.

4. Run tests:

   deno task test

   This will automatically set up pre-commit hooks, format code, run linters, and execute the test suite.

Project Structure

This is a Deno workspace (monorepo) with the following packages:

hclang/
├── cli/          # HC command-line interface & REPL
├── lib/          # Core library (published to JSR)
├── maml/         # MAML markup language
├── web/          # Web components
├── doc/          # Documentation and papers
└── deno.json     # Workspace root configuration

VS Code Extension

The VS Code extension for HC is now included in this repository at vscode-extension/. It provides comprehensive syntax highlighting for all HC language features based on the complete grammar specification.

Installation:

# Install from source
deno task vscode:install

# Or package for distribution
deno task vscode:package

# Or publish to marketplace
deno task vscode:publish

The extension recognizes .hc files and provides:

• Syntax highlighting for all HC elements (numbers, strings, identifiers, operators, etc.)
• Smart bracket matching for {}, [], ()
• Auto-closing pairs
• Comment toggling with #

Note: The old standalone language-hclang repository is now deprecated in favor of this integrated extension.

Publishing

For maintainers publishing new versions:

1. Ensure all tests pass:

   deno task test

2. Update version everywhere:

   deno task bump

   This updates deno.json, lib/version.ts, and all workspace package versions, then commits the changes.

3. Merge the PR to the master branch.

   GitHub Actions compares the version in deno.json with the version before the merge. When the version changed, it publishes the libraries to JSR, publishes the exact hclang tarball exercised through npx, and creates a GitHub Release tagged v<version> with generated notes. Each registry is checked independently, so a rerun resumes a partial release instead of retrying versions that are already immutable. Merges without a version bump do not publish or create a release; no manual tag is required.

   npm publishing runs in the protected npm-publish GitHub environment using a trusted publisher for the public hclang package. Its npm settings must authorize the TheSwanFactory/hclang repository, .github/workflows/deno.js.yml, the npm-publish environment, and direct npm publish before merging a release bump. The build/PR job has no OIDC token permission.

Links

• JSR Package: @swanfactory/hclang
• Documentation: JSR Docs
• GitHub: TheSwanFactory/hclang
• Blog: Homoiconic C Introduction
• MAML: HTML6 Proposal

License

MIT