Skip to content

CLAUDE.md

Latest commit

 

History

History
117 lines (82 loc) · 4.97 KB

CLAUDE.md

File metadata and controls

117 lines (82 loc) · 4.97 KB
Raw

CLAUDE.md

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

Project Overview

This is a comprehensive book about the Io Programming Language, written in Markdown format with one file per chapter. The book targets experienced programmers and provides in-depth comparisons with mainstream languages like JavaScript, Python, Ruby, and Java.

Repository Structure

  • Root directory: Contains 19 Markdown files (chapters 00-18) that make up the book
  • examples/: Runnable Io code examples organized by chapter
    • Each chapter subdirectory contains .io files demonstrating concepts from that chapter
    • Examples can be run with: io examples/chapter-XX/filename.io

Commands

Running Io Code Examples

# Run any example file
io examples/chapter-02/hello.io

# Run Io REPL for interactive exploration
io

Working with the Book Content

The book is written entirely in Markdown. Each chapter is a standalone .md file numbered sequentially (00-preface.md through 18-conclusion.md).

Code Architecture

This is a documentation/book project, not a software application. The structure is:

  1. Book Content: Individual Markdown files for each chapter containing:

    • Conceptual explanations
    • Code examples (inline in Markdown)
    • Comparisons to Python, JavaScript, Ruby, and Java
    • Exercises and "Try This" sections

  2. Example Code: Standalone .io files in the examples/ directory that readers can run to follow along with the book

Key Considerations

  • When editing chapters, maintain consistency in:

    • Code example formatting (use ```io code blocks)
    • Comparison style with other languages
    • Progressive building of concepts from earlier chapters

  • When creating new Io examples:

    • Place them in the appropriate examples/chapter-XX/ directory
    • Ensure they are self-contained and runnable
    • Include comments explaining key concepts

  • The book emphasizes prototype-based programming concepts and frequently contrasts Io with class-based languages to help readers understand the paradigm shift

Language Context

Io is:

  • A prototype-based object-oriented language (like JavaScript's prototype system)
  • Dynamically typed
  • Homoiconic (code is data)
  • Message-passing based
  • Uses differential inheritance through cloning

Common Io patterns seen in examples:

  • Everything is an object receiving messages
  • Methods are defined as slots: Object methodName := method(...)
  • Cloning for inheritance: Child := Parent clone
  • Blocks for closures: block(x, x * 2) =======

Repository Purpose

This is a comprehensive book about the Io programming language, written entirely in Markdown. The book targets experienced programmers as a second or third language resource, focusing on prototype-based object-oriented programming concepts with comparisons to mainstream languages (JavaScript, Python, Ruby, Java).

Content Structure

The repository contains 19 numbered chapter files (00-preface.md through 18-conclusion.md) that form a complete technical book. Each chapter builds on previous concepts while maintaining standalone value. The examples/ directory contains runnable Io code organized by chapter.

Working with Content

Running Examples

io examples/chapter-02/hello.io

Note: The Io interpreter may not be installed on all systems. Installation:

Key Content Characteristics

  1. Technical Comparisons: Examples frequently compare Io concepts to JavaScript, Python, Ruby, and Java equivalents
  2. Code Examples: All code blocks are meant to be runnable in the Io REPL
  3. Benchmark Outputs: Performance comparisons include representative timing outputs (e.g., Chapter 5 benchmarks)
  4. Progressive Complexity: Early chapters introduce fundamentals, later chapters cover advanced topics like metaprogramming and concurrency

Maintenance Guidelines

When Adding Content

  • Maintain consistent comparison style with other languages
  • Include runnable code examples with expected outputs
  • Place example files in appropriate examples/chapter-XX/ directories
  • Follow the established chapter numbering scheme

When Reviewing Feedback

  • The book has been reviewed by Steve Dekorte (Io's creator) - his feedback focused on adding outputs for benchmarks and expanding explanations for operator messages and common patterns

Version Control

  • The repository uses semantic versioning with tags (current: v1.1.0)
  • Major content improvements warrant version bumps
  • Include acknowledgments for technical reviewers in README.md

Important Context

This book was generated by Claude (Opus 4.1) in collaboration with a human developer. The entire 400+ page book was created in a single conversation session, demonstrating AI-assisted technical writing capabilities. The content is released under CC0 1.0 Universal license, encouraging community contributions and corrections.