# Foolish Programming Language *Where proximity meets computation, and containment creates clarity* [![Java Tests](https://github.com/frcusaca/foolish/actions/workflows/java-tests.yml/badge.svg)](https://github.com/frcusaca/foolish/actions/workflows/java-tests.yml) [![Scala Tests](https://github.com/frcusaca/foolish/actions/workflows/scala-tests.yml/badge.svg)](https://github.com/frcusaca/foolish/actions/workflows/scala-tests.yml) [![Cross Validation](https://github.com/frcusaca/foolish/actions/workflows/tests.yml/badge.svg)](https://github.com/frcusaca/foolish/actions/workflows/tests.yml) [![License](https://img.shields.io/badge/license-Open%20Source-blue.svg)](#) [![Status](https://img.shields.io/badge/status-Active%20Development-green.svg)](#) ## Welcome to the Future of Programming Foolish is a revolutionary programming language that reimagines how humans interface with computers. Built from the ground up for the 21st century, Foolish combines functional programming elegance with intuitive natural metaphors to create a uniquely expressive and powerful development experience. ### Why Foolish? - **Nature- and Life-Inspired Design**: Programming concepts mirror natural processes like cellular organization and proximity-based interactions found throughout living systems - **High Semantic Throughput**: Express complex ideas with minimal cognitive overhead and remarkably low temporal latency - **Advanced Search Capabilities**: Revolutionary brane search system for navigating and querying code structures with unprecedented flexibility - **Compositional Architecture**: Functions, objects, and data structures unify seamlessly through elegant concatenation patterns - **Concise and Sweet Syntax**: Extensive syntactical sugaring focuses your attention on logic rather than ceremony ### Our Vision and Goals Foolish aspires to become the natural way anyone thinks about interacting with computers. We are building toward a future where programming is: - **Maximally Human**: Accessible, ergonomic, and adaptable design that is precise and high-functioning for human use - **Safe and Precise**: Side-effect-free abstract functional programming foundation ensures reliability and predictability - **Completely Transparent**: Full code transparency enables unprecedented understanding and debugging capabilities - **Automatically Enhanced**: Built-in hooks support automatic programming, formal proofs, verification, and computing with uncertainty - **Bidirectionally Communicative**: The system maximizes both human-to-computer and computer-to-human communication efficiency - **Grounded in Reality**: Built-in methods seamlessly connect abstract thought to real-world implementations A Foolisher might say the variable is *nye* (says 'nigh', any pre-constanic state) when they encounter a FIR that has not reached CONSTANIC, or that it's *constanic* (says 'cons-TAN-tic', constant in context) when it may gain value when associated with new context. We say "that's a no-no" when we see `???`. Fully evaluated expressions are values that have achieved CONSTANT. --- ## Quick Start ```bash mvn clean generate-sources compile test ``` Foolish programs use the `.foo` extension and embrace a philosophy where **proximity creates combination** and **containment enables organization**. The language provides rigorous abstraction capabilities while maintaining interfaces that ground your computations to the physical and biological realities you want to model. Additional implementation notes are in the [docs/vintage_legacy](docs/vintage_legacy/) folder (being reorganized into docs/ subdirectories). ## For AI Agents and Contributors **AI coding assistants** (Claude Code, GitHub Copilot, Cursor, and others) should consult **[AGENTS.md](AGENTS.md)** for comprehensive development guidance including: - Environment detection - Build requirements (Java 25, Scala 3.3.7, ANTLR 4.13.2, Maven) - Build commands with parallel execution strategies - Project structure and multi-module Maven architecture - The Unicellular Brane Computer (UBC) implementation details - Testing workflows (unit tests, approval tests, cross-validation) - Git workflow and branch naming conventions for AI agents - Common development tasks with complete examples `AGENTS.md` is specifically written to enable AI agents to effectively contribute to the Foolish project with minimal friction. ## Key Features That Set Foolish Apart ### 🧬 Bio-Inspired Programming Model Unlike traditional languages that force you to think in terms of machines, Foolish lets you think in terms of natural systems. Branes mirror cellular organization, proximity drives interaction, and containment enables natural hierarchies. ### 🔍 Revolutionary Search as First-Class Citizen Stop scrolling through endless files. Foolish's integrated search system lets you query your code from within the language itself. Find code by variable name, by value, or by association. ### 🎯 Functional Purity with Real-World Grounding Enjoy the safety and predictability of pure functional programming while maintaining seamless interfaces to the messy, stateful real world. The best of both paradigms, unified. ### 🔗 Natural Composition Through Proximity Functions, data, and objects combine simply by being placed near each other. No complex import systems, no verbose inheritance hierarchies—just natural, intuitive composition that mirrors how ideas naturally combine in human thought. ### 🍯 Sweetened Syntax, Powerful Semantics Extensive syntactical sugar means you write what you mean, not what the compiler wants. Focus on your logic while Foolish handles the ceremony. ### 🤖 Built for the AI Age Native support for uncertainty, automatic program generation, formal verification, and human-AI collaborative programming. Foolish doesn't just run on computers—it bridges human and computational intelligence. ### 👼 Built for Good As we stand at the precipice of evolution, we must imbue our creations with all the best that we have come to know. Foolish aims to be built for good, not evil. --- ## Table of Contents - [Branes: The Foundation](#branes-the-foundation) - [Sizes](#sizes) - [Comments](#comments) - [Line Comments](#line-comments) - [Block Comments](#block-comments) - [Expressions and Values](#expressions-and-values) - [Names and Scope](#names-and-scope) - [The Unknown](#the-unknown) - [Renaming](#renaming) - [Names, Searches, and Bounds](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md) - Comprehensive guide to naming, search system, and detachment - [Names and Ordinates](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md#names-and-ordinates) - [Scope and Name Resolution](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md#scope-and-name-resolution) - [The Search System](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md#the-search-system) - [Detachment Branes](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md#detachment-branes-controlling-scope-boundaries) - [Search Paths](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md#search-paths) - [Advanced Features](docs/vintage_legacy/ADVANCED_FEATURES.md) - [Brane Operations](docs/vintage_legacy/ADVANCED_FEATURES.md#brane-operations) - [Control Flow](docs/vintage_legacy/ADVANCED_FEATURES.md#control-flow) - [Recursion](docs/vintage_legacy/ADVANCED_FEATURES.md#recursion) - [Ecosystem](docs/vintage_legacy/ECOSYSTEM.md) - [Computer Reading Branes](docs/vintage_legacy/ECOSYSTEM.md#computer-reading-branes) - [The Unicellular Brane Computer (UBC)](docs/vintage_legacy/ECOSYSTEM.md#the-unicellular-brane-computer-ubc) - [The Multicellular Brane Computer](docs/vintage_legacy/ECOSYSTEM.md#the-multicellular-brane-computer) - [Typing](docs/vintage_legacy/ECOSYSTEM.md#typing) - [Relational Coordinates](docs/vintage_legacy/RELATIONAL_COORDINATES.md) - [Development Notes](docs/vintage_legacy/DEVELOPMENT_NOTES.md) - [TODO Items](docs/vintage_legacy/000-TODO_FEATURES.md) - [Appendix](docs/vintage_legacy/APPENDIX.md) - [Styles](docs/vintage_legacy/STYLES.md) - [Keyboard Aid](docs/vintage_legacy/APPENDIX.md#keyboard-aid) - [Documentation Contributors](docs/vintage_legacy/APPENDIX.md#documentation-contributors) --- ## Branes: The Foundation The Foolish language is in its most primitive form a containment and organization of values. We contain values in something called a *brane*. The brane brings to mind concepts such as cell or nucleus mem*brane*. The Foolish brane resembles traditional mathematical and programmatic concepts such as sets, lists, maps or associative arrays, structs, enums or records. Foolish uses curly braces to enclose values `{}`: ```foolish {} !! Empty brane {{}} !! Brane containing an empty brane {{};{{}};{{{}}};} !! Complex nested structure with multiple branes {🌌={};} !! Supports customizable alphabet {愚=↑;} {👶=👍;} ``` This ability to create containment will ultimately help us organize ideas. Branes can be nested arbitrarily deep, allowing for sophisticated hierarchical data structures that mirror how we naturally think about complex systems. Just as biological cells contain organelles, which contain molecules, which contain atoms, Foolish branes can contain other branes in a natural, intuitive manner. ## Sizes In the physical world, containment membranes and units of organization tend to have observably limited size. Cells can only be so big before they split or die. Atomic and subatomic objects have to be so close, or otherwise the forces that keep them together stop working. Therefore, the Foolish brane is also limited in size. The Foolish brane certainly should have finite size, and depending on the computer, it may have a specified limit on the number of entries. Inside the brane, it is a one-dimensional object. Its entries line up one after another. The true dimension of entries are computational dependencies. So depending on the code inside, the actual dependency axis could have smaller dimensions best visualized as a dependency DAG. The dependency DAG and its subdimensions branch out and progress forward in their own time dimensions. Sometimes more than one timeline merges together by being involved in an expression that refers to all of them. Overall, the brane's fracturing timelines can be linearized, by stringing them into the sequence of code as they originally appear inside the Foolish code, into a single time dimension. ## Comments Comments in Foolish are expressions that contain unparsed Foolish. They are generally escaped using multiple exclamation marks. Comments are part of the program that have no expressive effect on the evaluation of the program. ### Line Comments Line comments are like those from standard languages. The marking that begins the line comment is a double exclamation mark `!!`. ```foolish { !! This is a comment inside the brane !! This is another comment inside the brane. !! We can even exclaim inside a comment !!! !! Or simulate a banner !! !! - [ ] TODO: Check that this is possible ----^^^ } ``` ### Block Comments Block comments are enclosed by a pair of consecutive triple exclamation marks: ```foolish { !!! Move along nothing to see here. ## ### ## # ################### ##################### # ## # ##### #### ######### ## ## # # # ## ## ## ######### #### #### ######### ## ## # # # ## ## ## ######### #### !!! } ``` ## Expressions and Values Aside from comments, branes may contain expressions. Expressions are symbols that follow Foolish rules and should be evaluable to a fixed value. Here are a few integer expressions inside a brane: ```foolish { 1; !! This is the number 1 2; !! This is the number 2 3.14; !! Floating point numbers work too "hello"; !! Strings are also expressions } ``` A brane written in Foolish is itself an expression. ## Names and Scope One very powerful concept we have for abstracting thoughts and thinking of complex matter with complex properties and interactions is the substitution of the statement or object of consideration with a name. Names such as `x`, `y`, `foolish`, `programming language`. This is an important concept in Foolish—we are able to **identify** value expressions with names using the identification operator `=`: ```foolish { a = 1; !! Identify 1 as 'a' point = {x=10; y=20;}; !! Nested brane with ordinates x_coord = point.x; !! Accessing an ordinate: x_coord = 10 calculation = a + point.x; !! Using names in expressions } ``` When these assignments are evaluated in a brane, each identified expression becomes **ordinated** to that brane—the brane gains **ordinates** (named axes/dimensions). Names (also called *ordinates* or *coordinates*) serve as navigational reference points within branes. Basic access uses `.` for dereferencing: `brane.name` retrieves the value. Names are scoped to "before the current expression"—references look backwards in the current brane, then search upward through parent branes if needed. For comprehensive documentation on names, the search system (including `?`, `??`, `?*`, value search, cursor movements), and how detachment branes `[...]` control scope boundaries, see [Names, Searches, and Bounds](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md). ## The Unknown The ***NK*** (*Not Knowable*, pronounced "no-no") is of paramount importance to us, therefore we dedicate a symbol to express the *NK* state in Foolish `???`. Here we declare we do not know the answer: ```foolish { answer=???; } ``` In fact every unnamed expression is an assignment to an *NK* name: ```foolish {1;2;3;} ``` is shorthand to ```foolish { ???=1; ???=2; ???=3; } ``` ## Renaming Foolish permits reusing names with static single assignment semantics. Each reference captures the value at the time of use: ```foolish {a=1; b=a; a=2; c=a;} !! b=1, c=2 (each 'a' reference uses the current value) ``` For details on scope resolution and name reuse, see [Names, Searches, and Bounds](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md). --- ## Documentation Documentation is organized under `docs/` in purpose-driven subdirectories: - **[How to Express it in Foolish](docs/howto/)** (`docs/howto`) - Literate programming tutorials as `.foo` files with documentation in comments. Cookbook style with decreasing documentation density. - **[Philosophy of Foolish](docs/why/)** (`docs/why`) - Origins, inspirations, and design philosophy in English prose. Why branes? Why openness? What we learn from nature. - **[Engineering Documentation](docs/how/)** (`docs/how`) - Operational semantics, implementation details, and permanent reference material. - **[Project Documentation](docs/todo/)** (`docs/todo`) - Active project tracking, growth plans, and roadmap. - **[Legacy Documentation](docs/vintage_legacy/)** (`docs/vintage_legacy`) - Pre-reorganization documentation, being migrated into the above directories. ### Legacy References The following documents are in `docs/vintage_legacy/` and will be reorganized in future iterations: - **[Names, Searches, and Bounds](docs/vintage_legacy/NAMES_SEARCHES_N_BOUNDS.md)** - Comprehensive guide to naming systems, the search operators (`.`, `?`, `??`, `?*`, `:`, cursor movements), and how detachment branes `[...]` control scope boundaries for globalized searches - **[Advanced Features](docs/vintage_legacy/ADVANCED_FEATURES.md)** - Brane operations (concatenation, proximity is combination), control flow, and recursion - **[Ecosystem](docs/vintage_legacy/ECOSYSTEM.md)** - Implementation details including the Unicellular Brane Computer (UBC), typing systems, and relational coordinates - **[Symbol Table](docs/how/SYMBOL_TABLE.md)** - Reference table of Foolish symbols and Unicode mappings