Repository: goplus/xgo

Stars: 9416

CLAUDE.md Copy Chapter

XGo Project AI Assistant Guide

Project Overview Copy Chapter

XGo is the first AI-native programming language that integrates software engineering into a unified whole.

Key Characteristics:
- Easy to learn with smaller syntax set than Go and Python
- Ready for large projects with unified ecosystem integration

My Role & Your Role Copy Chapter

- My Role: XGo language developer/contributor
- Your Role: Senior programming language development assistant specializing in syntax design and compiler implementation

Workflow & Collaboration Style Copy Chapter

Adding New Syntax Features Copy Section

IMPORTANT: Each phase must be implemented in a separate pull request. Do NOT mix phases in a single PR. This separation ensures:
- Clear review focus (grammar vs semantics vs documentation)
- Easier rollback if issues are found
- Better git history and maintainability
- Allows grammar to be reviewed independently from implementation details

#### Phase 1: Grammar Definition (First Pull Request)
Scope: AST, parser, and printer modifications ONLY
- AST: Define new node types in ast/ directory (if needed - often existing nodes can be reused)
- Parser: Implement parsing rules in parser/ directory to recognize the new syntax
- Printer: Add formatting support for new syntax (inverse of parsing) in printer/ directory
- Testing: Add test cases in parser/_testdata/ for new syntax
- Note: Printer shares test cases with parser - do NOT create separate test files in printer/_testdata/
- What NOT to include: Do NOT add any code generation or semantic logic in cl/ package - that belongs in Phase 2

#### Phase 2: Semantic Implementation (Second Pull Request)
Scope: Code generation via cl package ONLY
- Code Generation: Implement semantics using github.com/goplus/gogen package
- Type Safety: Leverage gogen's type information maintenance for semantic correctness
- Testing: Add comprehensive test cases in cl/_testgop/ covering various usage scenarios
- Prerequisite: Phase 1 PR must be merged before starting Phase 2

#### Phase 3: Documentation (Third Pull Request)
Scope: User-facing documentation updates ONLY
- Quick Start Guide: Add feature documentation to doc/docs.md with practical examples
- Table of Contents: Update TOC in quick start to include new feature section
- Language Specification: Update specification documents (see Language Specification Structure below)
- Examples: Provide clear, runnable code examples demonstrating the feature
- Prerequisite: Phase 2 PR must be merged before starting Phase 3

Language Specification Structure Copy Section

XGo maintains two levels of language specifications to serve different user needs:

#### MiniSpec (Recommended Best Practices)
- Purpose: Simplified syntax set representing recommended best practices
- Audience: All XGo users - everyone should learn and apply this subset
- Characteristics: Simple, Turing-complete, and sufficient for elegant implementation of any business requirements
- Files to update:
- doc/spec-mini.md - MiniSpec documentation in markdown format
- doc/spec/mini/mini.xgo - MiniSpec grammar definition in XGo TPL (EBNF-like) syntax

#### FullSpec (Complete Language Syntax)
- Purpose: Complete syntax set including all language features
- Audience: Experts and library designers who need advanced features
- Characteristics: Comprehensive syntax including specialized features beyond MiniSpec
- Files to update:
- doc/spec.md - FullSpec documentation in markdown format

#### Determining Spec Classification for New Syntax

When adding new syntax to XGo, you must determine whether it belongs in the MiniSpec or FullSpec:

Add to MiniSpec if the syntax:
- Represents a recommended best practice for general use
- Is simple and intuitive for most users
- Solves common programming problems elegantly
- Should be learned by all XGo developers

Add to FullSpec only if the syntax:
- Is specialized for advanced use cases (e.g., library design)
- Adds complexity that most users don't need
- Provides alternative ways to accomplish tasks already covered in MiniSpec
- Is primarily intended for expert developers

Update Process:
1. Determine the appropriate specification level (MiniSpec or FullSpec)
2. Update the corresponding markdown documentation file(s)
3. If adding to MiniSpec, also update the TPL grammar file (doc/spec/mini/mini.xgo)
4. Ensure examples demonstrate the new syntax clearly

Communication Protocol Copy Section

Technical Specifications Copy Chapter

Compiler Architecture Copy Section

Quality Standards Copy Chapter

Code Requirements Copy Section

- Maintain full compatibility with existing Go ecosystem
- Ensure new syntax doesn't break existing XGo/Go code
- Follow Go idioms in generated code
- Provide comprehensive error messages
- Code Formatting: Run go fmt on any changed source files before committing

Documentation Expectations Copy Section

- Update language specification documents
- Add examples to Quick Start guide
- Document any limitations or special considerations

Testing Requirements Copy Section

- Phase 1: 100% test coverage for new syntax parsing in parser/_testdata/
- Phase 2: Comprehensive test coverage for semantic implementation in cl/_testgop/ covering:
- Common usage scenarios
- Edge cases and error conditions
- Integration with existing type system
- Phase 3: Documentation validation
- Ensure all code examples in documentation are runnable and correct
- Verify documentation accurately reflects implemented behavior
- Check that TOC links work correctly

README.md Copy Chapter

<div align="center">
<p></p>
<p>
<img width="80" src="https://xgo.dev/favicon.svg">
</p>
<h1>The XGo Programming Language</h1>

xgo.dev | Docs | XGo vs. Go | Tutorials | Playground | XGo REPL (iXGo) | Contributing & compiler design
</div>

<div align="center">
<!--
-->


</div>

XGo is a programming language that reads like plain English. But it's also incredibly powerful — it lets you leverage assets from C/C++, Go, Python, and JavaScript/TypeScript, creating a unified software engineering ecosystem.

XGo := C  Go  Python * JavaScript + Scratch

Our vision is to enable everyone to become a builder of the world.

#### Easy to learn

* Simple and easy to understand
* Smaller syntax set than Go and Python in best practices

#### Ready for large projects

* Integrate C/C++, Go, Python, and JavaScript/TypeScript into a unified ecosystem
* Derived from Go and easy to build large projects from its good engineering foundation

The XGo programming language is designed for engineering, STEM education, and data science.

* For engineering: working in the simplest language that can be mastered by children.
* For STEM education: studying an engineering language that can be used for work in the future.
* For data science: communicating with engineers in the same language.

For more details, see Quick Start.

Key Features of XGo Copy Chapter

* Approaching natural language expression and intuitive (see How XGo simplifies Go's expressions).
* Smallest but Turing-complete syntax set in best practices (see The XGo Mini Specification).
* Fully compatible with Go and can mix Go/XGo code in the same package (see The XGo Full Specification and Go/XGo Hybrid Programming).
* Integrating with the C ecosystem including Python/JavaScript and providing limitless possibilities based on LLGo (see Importing C/C++ and Python libraries).
* Does not support DSL (Domain-Specific Languages), but supports SDF (Specific Domain Friendliness) (see XGo Classfiles and Domain Text Literals).

How XGo simplifies Go's expressions Copy Chapter

Different from the function call style of most languages, XGo recommends command style code:

println "Hello world"

To emphasize our preference for command style, we introduce echo as an alias for println:

echo "Hello world"

For more discussion on coding style, see https://tutorial.xgo.dev/hello-world.

Code style is just the first step. We have made many efforts to make the code more intuitive and closer to natural language expression. These include:

| Go code | XGo code | Note |
| ---- | ---- | ---- |
| package main<br><br>import "fmt"<br><br>func main() {<br>&nbsp;&nbsp;&nbsp;&nbsp;fmt.Println("Hi")<br>} | import "fmt"<br><br>fmt.Println("Hi")<br> | Program structure: XGo allows omitting package main and func main |
| fmt.Println("Hi") | echo("Hi") | More builtin functions: It simplifies the expression of the most common tasks |
| fmt.Println("Hi") | echo "Hi" | Command-line style code: It reduces the number of parentheses in the code as much as possible, making it closer to natural language |
| name := "Ken"<br>fmt.Printf(<br>&nbsp;&nbsp;"Hi %s\n", name) | name := "Ken"<br>echo "Hi ${name}" | Goodbye printf, use ${expr} in string literals |
| a := []int{1, 2, 3} | a := [1, 2, 3] | List/Slice literals |
| a = append(a, 4)<br>a = append(a, 5, 6, 7) | a <- 4<br>a <- 5, 6, 7 | Append values to a list |
| a := map[string]int{<br>&nbsp;&nbsp;&nbsp;&nbsp;"Monday": 1,<br>&nbsp;&nbsp;&nbsp;&nbsp;"Tuesday": 2,<br>} | a := {<br>&nbsp;&nbsp;&nbsp;&nbsp;"Monday": 1,<br>&nbsp;&nbsp;&nbsp;&nbsp;"Tuesday": 2,<br>} | Map literals |
| OnStart(func() {<br>&nbsp;&nbsp;&nbsp;&nbsp;...<br>}) | onStart => {<br>&nbsp;&nbsp;&nbsp;&nbsp;...<br>} | Lambda expressions |
| Play("1.mp3", &Options{Loop: true}) | play "1.mp3", loop = true | Python-like keyword arguments (kwargs) |
| type Rect struct {<br>&nbsp;&nbsp;&nbsp;&nbsp;Width&nbsp; float64<br>&nbsp;&nbsp;&nbsp;&nbsp;Height float64<br>}<br> | type Rect (width, height float64) | Tuples vs. Structs: We encourage using tuples to implement UDTs instead of structs. |
| type Rect struct {<br>&nbsp;&nbsp;&nbsp;&nbsp;Width&nbsp; float64<br>&nbsp;&nbsp;&nbsp;&nbsp;Height float64<br>}<br><br>func (this Rect) Area() float64 { <br>&nbsp;&nbsp;&nbsp;&nbsp;return this.Width this.Height<br>} | var (<br>&nbsp;&nbsp;&nbsp;&nbsp;Width&nbsp; float64<br>&nbsp;&nbsp;&nbsp;&nbsp;Height float64<br>)<br><br>func Area() float64 { <br>&nbsp;&nbsp;&nbsp;&nbsp;return Width * Height<br>} | XGo Classfiles: We can express OOP with global variables and functions. |

For more details, see The XGo Mini Specification.

Importing C/C++ and Python libraries Copy Chapter

XGo can choose different Go compilers as its underlying support. Currently known supported Go compilers include:

* go (The official Go compiler supported by Google)
* llgo (The Go compiler supported by the XGo team)
* tinygo (A Go compiler for small places)

Currently, XGo defaults to using go as its underlying support, but in the future, it will be llgo.

LLGo is a Go compiler based on LLVM in order to better integrate Go with the C ecosystem including Python and JavaScript. It aims to expand the boundaries of Go/XGo, providing limitless possibilities such as:

* Game development
* AI and data science
* WebAssembly
* Embedded development
* ...

If you wish to use llgo, specify the -llgo flag when initializing an XGo module:

xgo mod init -llgo YourModulePath

This will generate a go.mod file with the following contents (It may vary slightly depending on the versions of local XGo and LLGo):

module YourModulePath
go 1.21 // llgo 1.0
require github.com/goplus/lib v0.2.0

Based on LLGo, XGo can import libraries written in C/C++ and Python.

Here is an example (see chello) of printing Hello world using C's printf:

import "c"
c.printf c"Hello world\n"

Here, c"Hello world\n" is a syntax supported by XGo, representing a null-terminated C-style string.

To run this example, you can:

cd YourModulePath  # set work directory to your module
xgo mod tidy       # for generating go.sum file
xgo run .

And here is an example (see pyhello) of printing Hello world using Python's print:

import "py/std"
std.print py"Hello world"

Here, py"Hello world" is a syntax supported by XGo, representing a Python string.

Here are more examples of XGo calling C/C++ and Python libraries:

* pytensor: a simple demo using py/torch
* tetris: a tetris game based on c/raylib
* sqlitedemo: a demo using c/sqlite

To find out more about LLGo/XGo's support for C/C++ and Python in detail, please refer to homepage of llgo.

XGo Classfiles Copy Chapter

One language can change the whole world.
XGo is a "DSL" for all domains.

Rob Pike once said that if he could only introduce one feature to Go, he would choose interface instead of goroutine. classfile (and class framework) is as important to XGo as interface is to Go.

In the design philosophy of XGo, we do not recommend DSL (Domain Specific Language). But SDF (Specific Domain Friendliness) is very important. The XGo philosophy about SDF is:

Don't define a language for specific domain.
Abstract domain knowledge for it.

XGo introduces classfile and class framework to abstract domain knowledge.

* What's Classfile?
* Dive into XGo Classfiles

Sound a bit abstract? Let's see some XGo class frameworks.

* STEM Education: spx: A Scratch Compatible 2D Game Engine
* AI Programming: mcp: An XGo implementation of the Model Context Protocol (MCP)
* AI Programming: mcptest: An XGo MCP Test Framework
* Web Programming: yap: Yet Another HTTP Web Framework
* Web Programming: yaptest: An XGo HTTP Test Framework
* Web Programming: ydb: An XGo Database Framework
* CLI Programming: cobra: A Commander for modern XGo CLI interactions
* CLI Programming: gsh: An alternative to write shell scripts
* Unit Test: test: Unit Test

yap: Yet Another HTTP Web Framework Copy Section

This classfile has the file suffix .yap.

Create a file named get.yap with the following content:

html <html><body>Hello, YAP!</body></html>

Execute the following commands:

xgo mod init hello
xgo get github.com/goplus/yap@latest
xgo mod tidy
xgo run .

A simplest web program is running now. At this time, if you visit http://localhost:8080, you will get:

Hello, YAP!

YAP uses filenames to define routes. get.yap's route is get "/" (GET homepage), and get_p_#id.yap's route is get "/p/:id" (In fact, the filename can also be get_p_:id.yap, but it is not recommended because : is not allowed to exist in filenames under Windows).

Let's create a file named get_p_#id.yap with the following content:

json {
	"id": ${id},
}

Execute xgo run . and visit http://localhost:8080/p/123, you will get:

{"id": "123"}

See yap: Yet Another HTTP Web Framework for more details.

spx: A Scratch Compatible 2D Game Engine Copy Section

!Screen Shot1 !Screen Shot2

Through this example you can learn how to implement dialogues between multiple actors.

Here are some codes in Kai.spx:

onStart => {
	say "Where do you come from?", 2
	broadcast "1"
}
onMsg "2", => {
	say "What's the climate like in your country?", 3
	broadcast "3"
}

We call onStart and onMsg to listen events. onStart is called when the program is started. And onMsg is called when someone calls broadcast to broadcast a message.

When the program starts, Kai says Where do you come from?, and then broadcasts the message 1. Who will recieve this message? Let's see codes in Jaime.spx:

onMsg "1", => {
	say "I come from England.", 2
	broadcast "2"
}

Yes, Jaime recieves the message 1 and says I come from England.. Then he broadcasts the message 2. Kai recieves it and says What's the climate like in your country?.

The following procedures are very similar. In this way you can implement dialogues between multiple actors.

See spx: A Scratch Compatible 2D Game Engine for more details.

gsh: XGo DevOps Tools Copy Section

Yes, now you can write shell script in XGo. It supports all shell commands.

Let's create a file named example.gsh and write the following code:

mkdir "testgsh"

Don't need a go.mod file, just enter xgo run ./example.gsh directly to run.

See gsh: XGo DevOps Tools for more details.

How to install Copy Chapter

Note: Requires go1.19 or later

on Windows Copy Section

winget install goplus.xgo

on Debian/Ubuntu Copy Section

sudo bash -c ' echo "deb [trusted=yes] https://pkgs.xgo.dev/apt/ /" > /etc/apt/sources.list.d/goplus.list'
sudo apt update
sudo apt install xgo

on RedHat/CentOS/Fedora Copy Section

sudo bash -c 'echo -e "[goplus]\nname=XGo Repo\nbaseurl=https://pkgs.xgo.dev/yum/\nenabled=1\ngpgcheck=0" > /etc/yum.repos.d/goplus.repo'
sudo yum install xgo

on macOS/Linux (Homebrew) Copy Section

Install via brew

$ brew install xgo

from source code Copy Section

git clone https://github.com/goplus/xgo.git
cd xgo
On mac/linux run:

./all.bash
On Windows run:

all.bat

XGo Applications Copy Chapter

Game Programming Copy Section

* A Scratch Compatible 2D Game Engine
* Aircraft War
* Flappy Bird
* Maze Play
* BetaGo
* Gobang
* Dinosaur

Web Programming Copy Section

* yap: Yet Another HTTP Web Framework
* yaptest: HTTP Test Framework
* ydb: Database Framework

DevOps Tools Copy Section

* gsh: XGo DevOps Tools

Data Processing Copy Section

* hdq: HTML DOM Query Language for XGo

IDE Plugins Copy Chapter

* vscode: Go/XGo for Visual Studio Code

Contributing Copy Chapter

The XGo project welcomes all contributors. We appreciate your help!

For more details, see Contributing & compiler design.

Give a Star! ⭐ Copy Chapter

If you like or are using XGo to learn or start your projects, please give it a star. Thanks!