# Slovo

Slovo (ⰔⰎⰑⰂⰑ) is a typed structural programming language and toolchain.

This repository is the canonical public monorepo for the language design,
standard library source, compiler, runtime, examples, benchmarks, and technical
documents.

Current release: `1.0.0-beta.7`.

## Repository Layout

```text
compiler/       Glagol, the first Slovo compiler
runtime/        C runtime used by hosted native builds
lib/std/        source-authored Slovo standard-library facades
examples/       compiler-supported Slovo examples and projects
benchmarks/     local benchmark comparison harnesses
docs/language/  language manifest, specs, roadmap, and release notes
docs/compiler/  compiler manifest, roadmap, and release notes
docs/papers/    whitepapers and generated publication PDFs
scripts/        local release and document tooling
```

## Beta Scope

`1.0.0-beta.7` keeps the `1.0.0-beta` language baseline, includes the
`1.0.0-beta.1` tooling/install hardening slice, the `1.0.0-beta.2`
runtime/resource foundation bundle, the `1.0.0-beta.3` standard-library
stabilization bundle, the `1.0.0-beta.4` language-usability diagnostics
bundle, the `1.0.0-beta.5` local package/workspace discipline bundle, and the
`1.0.0-beta.6` loopback networking foundation, plus the `1.0.0-beta.7`
serialization/data-interchange foundation. The language baseline supports
practical local command-line, file, and loopback-network programs with:

- modules, explicit imports, packages, and local workspaces
- `new`, `check`, `fmt`, `test`, `doc`, and `build`
- `i32`, `i64`, `u32`, `u64`, `f64`, `bool`, `string`, and internal `unit`
- structs, enums, fixed arrays, concrete vectors, option/result families, and
  current `match`
- explicit `std/*.slo` imports from `lib/std`, installed `share/slovo/std`, or
  `SLOVO_STD_PATH`
- beta-scoped loopback TCP handles through `std.net`
- JSON string quoting and compact JSON text construction through `std.json`
- hosted native builds through LLVM IR, Clang, and `runtime/runtime.c`

Still deferred before stable: generics, maps/sets, broad package registry
semantics, DNS/TLS/async networking, LSP/watch/debug-adapter guarantees,
stable ABI and layout, and a stable standard-library compatibility freeze.

## Build And Test

```bash
cargo test --manifest-path compiler/Cargo.toml
```

Run the full local release gate:

```bash
./scripts/release-gate.sh
```

Build the compiler binary:

```bash
cargo build --manifest-path compiler/Cargo.toml
./compiler/target/debug/glagol --version
```

Create and check a project:

```bash
./compiler/target/debug/glagol new hello
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol check hello
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol test hello
```

Build a native executable when Clang is available:

```bash
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol build hello -o hello/bin
```

## 1.0.0-beta.1 Tooling Additions

The `1.0.0-beta.1` release improves the common local development and install
loop without adding new source-language syntax.

Build and execute in one step:

```bash
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol run hello
SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol clean hello
```

Create alternate project shapes:

```bash
./compiler/target/debug/glagol new numbers --template library
./compiler/target/debug/glagol new workspace-demo --template workspace
```

Install the current checkout:

```bash
PREFIX="$HOME/.local" ./scripts/install.sh
```

The installed layout is:

```text
<prefix>/bin/glagol
<prefix>/share/slovo/std/*.slo
<prefix>/share/slovo/runtime/runtime.c
```

Installed `glagol` discovers `share/slovo/std` and
`share/slovo/runtime/runtime.c` relative to its executable. `SLOVO_STD_PATH`
can still override standard-library search, `SLOVO_RUNTIME_C` or
`GLAGOL_RUNTIME_C` can override the runtime C input, and `GLAGOL_CLANG` can
select the Clang-compatible compiler.

## 1.0.0-beta.2 Runtime Resource Foundation

The `1.0.0-beta.2` release adds beta-scoped runtime/resource foundation work:

- `std.fs.open_text_read_result`
- `std.fs.read_open_text_result`
- `std.fs.close_result`
- `std.fs.exists`
- `std.fs.is_file`
- `std.fs.is_dir`
- `std.fs.remove_file_result`
- `std.fs.create_dir_result`
- matching explicit `lib/std/fs.slo` facades

These APIs use beta-scoped opaque `i32` file handles. They do not claim stable
file descriptors, writable streams, binary IO, directory handles, sockets,
async IO, platform error codes, or stable handle ABI/layout. Directory creation
is intentionally narrow and does not imply directory enumeration or recursive
filesystem APIs.

## 1.0.0-beta.3 Standard Library Stabilization

The `1.0.0-beta.3` release starts the standard-library stabilization slice. It
adds a generated standard-library API catalog and
`examples/projects/stdlib-composition`, a checked/tested/run-capable program
that composes `std.fs`, `std.string`, `std.math`, and `std.io`.

## 1.0.0-beta.4 Language Usability Diagnostics

The `1.0.0-beta.4` release improves diagnostics without changing the source
language surface. Project/workspace build and run entry failures now use
entry-specific diagnostic codes, and non-exhaustive `match` diagnostics have
clearer wording with deterministic found-arm output.

## 1.0.0-beta.5 Package And Workspace Discipline

The `1.0.0-beta.5` release tightens local package/workspace behavior. Local
workspaces may declare `[workspace] default_package = "name"` to select the
build/run entry package when multiple packages have entry modules. Duplicate
normalized workspace members and missing default-package references are now
dedicated diagnostics. `glagol doc <workspace> -o <dir>` includes a workspace
package/dependency summary, new workspace templates declare
`default_package = "app"`, and `docs/language/PACKAGES.md` documents the beta
local-package rules. Remote registries, lockfiles, semantic-version solving,
package publishing, and stable package ABI/layout remain deferred.

## 1.0.0-beta.6 Networking Foundation

The `1.0.0-beta.6` release adds a narrow blocking loopback TCP foundation:

- compiler-known `std.net.tcp_*_result` calls for connect, listen,
  bound-port lookup, accept, read-all, write-text, and close
- `lib/std/net.slo` source facades and explicit std/local example projects
- opaque beta-scoped `i32` socket handles with concrete `result` values

This is not a general networking stack. DNS, TLS, UDP, non-loopback binding,
async IO, HTTP frameworks, rich host-error ADTs, stable socket ABI/layout, and
automatic resource ownership remain deferred.

## 1.0.0-beta.7 Serialization And Data Interchange

The `1.0.0-beta.7` release adds a narrow JSON text-construction foundation:

- compiler-known `std.json.quote_string` for deterministic compact JSON string
  quoting
- `lib/std/json.slo` source helpers for scalar values, fields, small arrays,
  and small objects
- explicit std/local JSON example projects and a `json-quote-loop` benchmark
  scaffold

This is not a complete JSON library. Full parsing, recursive JSON values,
maps/sets, streaming encoders, schema validation, Unicode normalization, and a
stable data-interchange API freeze remain deferred.

## Documentation

- [Language Manifest](docs/language/MANIFEST.md)
- [Language Specification](docs/language/SPEC-v1.md)
- [Local Package And Workspace Guide](docs/language/PACKAGES.md)
- [Standard Library API Catalog](docs/language/STDLIB_API.md)
- [Compiler Manifest](docs/compiler/GLAGOL_COMPILER_MANIFEST.md)
- [Post-Beta Roadmap](docs/POST_BETA_ROADMAP.md)
- [Slovo Whitepaper](docs/papers/SLOVO_WHITEPAPER.md)
- [Glagol Whitepaper](docs/papers/GLAGOL_WHITEPAPER.md)

Generated PDFs live beside their Markdown sources in `docs/papers/`.
Regenerate them with `./scripts/render-doc-pdfs.sh` before documentation
releases.

## License

Slovo is licensed under either the MIT License or the Apache License, Version
2.0, at your option.