Skip to content

.claude.md

Latest commit

 

History

History
135 lines (109 loc) · 4.37 KB

.claude.md

File metadata and controls

135 lines (109 loc) · 4.37 KB

CLAUDE.md

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

Overview

YAMLScript (YS) is a functional programming language that uses YAML syntax and compiles to Clojure. It provides:

  • A YAML loader library for 15+ programming languages
  • A standalone ys command-line tool
  • Native shared library libys.so for language bindings

Coding style

  • Wrap lines at exactly 80 characters - This is strictly enforced
  • Use 2 spaces for indentation in most languages
  • Use styles already established in the file
  • Prefer single quotes over double quotes when possible and appropriate
  • In yaml files:
    • Don't over-indent sequences in block mappings
    • Don't quote scalar values that don't need to be quoted
  • Use ReadMe.md, not README.md
  • For markdown files:
    • Start each sentence on a new line
    • Wrap lines at exactly 80 characters - count carefully
    • Put 2 blank lines before a section heading

Common Development Commands

GNU Make is used for all dev tasks. Almost every directory has a Makefile, and they use the common/*.mk files for shared logic. They also automatically install the https://github.com/makeplus/makes project into the .cache/makes directory. The makes project has a file for each language dependency and it automatically installs them for you locally (languages are never assumed to be installed on the system). As long as a machine has bash, curl, git and make, it can build and test YS and every language binding.

Building

# Build everything (uses Docker on Linux x86_64) with ubuntu:20.04 to support
# older glibc versions.
make build

# Build specific components
make build-ys      # Build ys CLI tool
make build-libys   # Build libys shared library

# Build from source (requires: bash, curl, git, make)
make build
make install       # Installs to ~/.local/{bin,lib} by default
make install PREFIX=/custom/path

Testing

# Run all tests (takes several minutes)
make test

# Test specific components
make test-core     # Test core Clojure code
make test-ys       # Test ys CLI
make test-bindings # Test all language bindings
make test-nodejs   # Test specific binding (replace nodejs with any binding)
make -C <lang-dir> test  # Test specific binding

# Run tests with verbose output
make test v=1

Installing

# Install ys and libys binaries
make install              # To ~/.local/{bin,lib}
make install PREFIX=/usr/local  # Custom location

High-Level Architecture

Repository Structure

This is a monorepo containing:

  • core/ - Core YAMLScript compiler written in Clojure (compiles YS to Clojure AST)
  • libys/ - Native shared library built from core using GraalVM native-image
  • ys/ - Command-line tool for running/loading/compiling YS programs
  • Language bindings (clojure/, crystal/, go/, java/, nodejs/, perl/, php/, python/, raku/, ruby/, rust/, etc.)
    • Each binding wraps libys to provide native language integration

Build System

  • Uses GNU Make with custom Makefile infrastructure
  • common/*.mk files provide shared build logic
  • GraalVM native-image compiles Clojure to native binaries (ys and libys.so)
  • Docker is used for consistent Linux x86_64 builds

Compilation Pipeline

  1. YS source → Parser (YAML → data structure)
  2. Data → Composer (applies YS language rules)
  3. Composed data → Compiler (generates Clojure code)
  4. Clojure code → SCI runtime (executes without JVM)

Testing

  • Core tests use Leiningen (lein test)
  • CLI tests use Perl's prove with BPAN framework
  • Language bindings have their own test suites

Key Technical Details

  • YS files use .ys extension
  • Programs starting with !ys-0 tag have functional capabilities
  • ys-0 starts in code mode, ys-0: data mode, neither implies bare mode
  • Without the tag, YS loads standard YAML 1.2 Core Schema
  • Version format: 0.2.3 (semantic versioning)
  • API version: v0 (for backward compatibility)

Language Binding Development

Each binding requires:

  • Wrapper around libys.so FFI calls
  • load() and eval() methods minimum
  • Tests matching the core test suite
  • Package manager integration (npm, pip, gem, etc.)

Important Files

  • Makefile - Main build orchestration
  • core/src/yamlscript/*.clj - Compiler implementation
  • core/src/ys/*.clj - YS runtime libraries
  • ys/src/yamlscript/cli.clj - CLI implementation
  • sample/**/*.ys - Example YS programs