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 The Swan Factory HC playground to try HC directly in your browser with no installation required. For offline use, download hcweb.html from the latest release and open it in your browser.

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:

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
   

   Install pre-commit hooks explicitly with deno task setup.

4. Run tests:

   deno task test
   

   This checks formatting and lint without fixing sources, then runs the test suite. Use deno task fix to format and apply lint fixes.

   deno task bundle:check checks bundled HC sources without rewriting them; after editing hc/*.hc, regenerate them with deno task bundle:embed.

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.

   The tested web release also deploys to GitHub Pages. CI verifies the live version and evaluates HC in a browser after deployment; a daily availability workflow checks the public demo between releases. See the web publishing setup.

   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