Metadata-Version: 2.4
Name: gofra
Version: 0.1.2
Summary: A Stack-based compiled programming language
License-Expression: MIT
License-File: LICENSE
Keywords: compiler,language
Author: Kirill Zhosul
Author-email: kirillzhosul@yandex.com
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Project-URL: Documentation, https://gofralang.github.io/docs
Project-URL: Repository, https://github.com/gofralang/gofra
Project-URL: issues, https://github.com/gofralang/gofra/issues
Description-Content-Type: text/markdown

# Gofra [beta]

**A Stack-based compiled programming language.**

**The project is made not for competing with other languages, rather it is another incomplete language almost same like others.**

[![Compiler Testkit](https://github.com/kirillzhosul/gofra/actions/workflows/testkit.yml/badge.svg)](https://github.com/kirillzhosul/gofra/actions/workflows/testkit.yml)

---

#### [Documentation and information is available here](https://kirillzhosul.github.io/gofra)

---

## Overview

Gofra is a **concatenative** (stack-based) programming language that compiles to native code.
Programs are written using [Reverse Polish notation](https://en.wikipedia.org/wiki/Reverse_Polish_notation), where operations follow their operands (e.g `2 + 2` is `2 2 +`).

![Pong Example Screenshot](https://raw.githubusercontent.com/gofralang/docs/refs/heads/main/docs/pong_preview.png)

## Quick start

Here's a simple **"Hello, World!"** example:

```gofra
include "std"

func void main
    "Hello, World!" println
end
```

## Features

- _Native_ - Compiles to native machine code
- _C_-like - Close to C, but has a few more high-level abstraction (`for in`, `type generics`)
- _C FFI_ - Seamless integration with **C**-FFI libraries
- _Low-level_ - Write unsafe, low-level code with direct memory access
- _Type System_ - Validate types at compile time, has compile-time warnings (Generics supports, typechecker)
- _Library_ - By default has support for `math`, `random`, `network` and other libraries
- _First class functions_ - Has support, and lambda definitions (no closures/capturing yet)

## More complex examples

```gofra
#include "std"

// Print each array element
var xs = ["Hello", " ", "world!", "\n"]

func void main[]
    for x in xs do
        x ?> print
    end
end
```

## Showcase

- Pong Game ([`examples/pong_game`](./examples/pong_game))
- Simple HTTP server ([`examples/http_server`](./examples/http_server))

## Platform Support

| ARCH    | OS     | Support                    | Tested hardware      |
| ------- | ------ | -------------------------- | -------------------- |
| Aarch64 | Darwin | :white_check_mark:*        | M1, MacOS Tahoe 26.1 |
| WASM    | **-**  | :heavy_exclamation_mark:** | Node.js v22, Safari  |
| x86_64  | Linux  | :heavy_exclamation_mark:** |                      |

| ARCH    | OS      | Support       | Tested hardware |
| ------- | ------- | ------------- | --------------- |
| Aarch64 | Windows | :x:           |
| Aarch64 | Linux   | :x:           |
| x86_64  | Darwin  | :x:           |
| x86_64  | Windows | :bangbang:*** |

\* Main workflow of development, has _all_ features \
** Incomplete, has bugs and not all features \
*** Windows x86_64 is not implemented, but has general wrappers for system calls and possibly can be compiled with some headache

## Pre requirements

Before installing Gofra, ensure you have the following tools available system-wide:

- [Python >3.12.x](https://www.python.org)
- GNU/Mach-O Linker (ld) - For linking compiled objects
- Assembler (as) - Typically included with Clang LLVM compiler

## Installation

**For full installation steps, please visit [Installation](./installation.md) page.**

[Gofra](https://github.com/kirillzhosul/gofra) is distributed as single Python-based toolchain. To install:

(Step 1): Install toolchain

```bash
pip install gofra
```

(Step 2): Verify Installation

```bash
gofra --help
```

## More information and next steps

Please refer to actual [documentation](https://gofralang.github.io/docs)!

