# Mica

Mica is a small, statically checked language for new web applications. It pairs
immutable bindings and explicit nullable types with a Go interpreter and a
development HTTP server. This release is the first runnable prototype.

## Build and try it

Install a supported Go compiler, version 1.22 or later. Mica uses only the Go
standard library; it needs no package downloads or PHP installation.

```sh
go build -o dist/mica ./cmd/mica
./dist/mica check examples/greeting.mica
./dist/mica run examples/greeting.mica
```

Output:

```text
Hello, Ada
```

`check` is silent on success. Both commands parse and type-check the entire file
before executing any statements. You can also use the packaged Linux x86-64
executable, `dist/mica-linux-amd64`, in place of `dist/mica`.

## Run a web application

```sh
./dist/mica serve examples/web.mica --addr 127.0.0.1:8080
```

From a second terminal:

```sh
curl 'http://127.0.0.1:8080/?name=Ada'
```

The response is `Hello, Ada`, with content type `text/plain; charset=utf-8`.
Ctrl-C stops the server cleanly. The default address is `127.0.0.1:8080`; pass
`--addr 127.0.0.1:0` to select an available port, reported on standard error.
Flags follow the source filename.

A web file declares functions and provides this handler:

```text
fn handle(request: Request) -> Response {
    let name = query(request, "name") ?? "world";
    return text("Hello, " + name);
}
```

Use `method(request)` and `path(request)` to dispatch with ordinary `if`
statements. Every request gets fresh evaluator state. Bad query encoding or
invalid UTF-8 input returns HTTP 400. Runtime failures return a fixed HTTP 500
message, with source diagnostics kept on the server. Text and JSON responses
set `X-Content-Type-Options: nosniff`.

## Language essentials

```text
fn greet(name: String) -> String {
    return "Hello, " + name;
}

let name = "Ada";
print(greet(name));
```

- `let` creates an immutable binding. Local types are inferred or annotated:
  `let count: Int = 3;`. Inner blocks can shadow outer local bindings.
- Functions require parameter and return annotations. Functions can recurse
  and call functions declared later. They do not capture top-level variables.
- Types are `Int` (signed 64-bit), `Bool`, `String`, opaque `Request`/`Response`,
  and their nullable forms. `Void` is a function return type only.
- There are no implicit conversions or truthiness rules. `1 + "2"` and
  `if "yes" { ... }` are errors. Use `to_string` to convert a non-null primitive.
- `+` adds integers or concatenates strings. Other arithmetic and ordering
  operators take integers. `&&`, `||`, and `??` evaluate lazily.
- Equality supports the same primitive base type, nullable values of that base
  type, and null comparisons with nullable values. Opaque values can only be
  compared with null when nullable.
- Simple statements end in semicolons. Functions, blocks, `if`, `else`, and
  `else if` use braces. Comments start with `//`.
- Double-quoted strings support `\n`, `\r`, `\t`, `\"`, and `\\`. Source and
  strings are UTF-8; identifiers use ASCII letters, digits, and underscores.

Integer overflow, division by zero, and more than 256 active function calls are
controlled runtime errors. Division truncates toward zero.

### Handle absent or invalid values explicitly

```text
let age = parse_int("42");
if age != null {
    print(age + 1);
}

let fallback = parse_int("unknown") ?? 18;
print(fallback);
```

Run `./dist/mica run examples/nullable.mica` to print `43` and `18` on separate
lines. `parse_int` returns `Int?`; it rejects whitespace, non-decimal digits, and
overflow. A direct `if value != null` narrows the immutable variable inside the
then block; `if value == null` narrows it inside the else block. Narrowing does
not continue after the conditional or through compound conditions. A binding
initialized with bare null needs an annotation: `let name: String? = null;`.

### Built-ins

| Function | Result |
| --- | --- |
| `print(value)` | Print one primitive or null, followed by a newline; returns `Void`. |
| `parse_int(string)` | `Int?`; optional leading sign and decimal digits only. |
| `to_string(value)` | `String`; accepts a non-null `Int`, `Bool`, or `String`. |
| `query(request, key)` | `String?`; first decoded value, null when absent, empty string when explicitly empty. |
| `method(request)` / `path(request)` | Request method / decoded path without query. |
| `text(string)` | HTTP 200 text response. |
| `json(value)` | HTTP 200 JSON response for a primitive or null. |

For example, `json("hello")` returns the JSON string `"hello"`, including the
quotes. JSON currently supports scalar values; it does not accept raw JSON
documents, objects, or arrays. There is no raw HTML response API in this release.

## Diagnostics and exit status

```sh
./dist/mica run examples/invalid.mica
```

This reports a diagnostic such as:

```text
examples/invalid.mica:3:17: type: expected Int, received String
```

The earlier `print` does not execute. Locations use one-based lines and Unicode
code-point columns. Syntax, type, and runtime diagnostics go to standard error;
program output goes to standard output. Runtime errors may follow earlier
successful prints.

Exit status is 0 for success, 1 for source/runtime/file/listener errors, and 2
for invalid command usage. There is no implicit `main` call: `run` executes the
file's top-level statements. `serve` permits only function declarations at the
top level and requires the typed `handle` function.

## Test and package

```sh
go test ./...
go vet ./...
go test -race ./...
./scripts/package.sh
```

Tests bind loopback ports; the race detector also requires a working C compiler.
Packaging requires a clean Git checkout and produces:

- `dist/mica-linux-amd64`: a standalone Linux x86-64 executable.
- `dist/mica-source.tar.gz`: the committed source, tests, examples, and docs.
- `dist/SHA256SUMS`: checksums, verified with `cd dist && sha256sum -c SHA256SUMS`.

The source archive extracts into `mica/`. No service is published or deployed by
the packaging script.

## Scope of this release

This is a language and development runtime for experimenting with new web apps.
It does not run existing PHP programs or provide PHP's ecosystem. The HTTP
listener is for development, and programs are not sandboxed.

Arrays, maps, records, classes, loops, imports, mutable variables, closures,
first-class functions, interpolation, generics, package management, databases,
sessions, cookies, request bodies, custom response headers/status codes, and
production deployment are deferred. Recursion and conditionals provide the
initial computational core.

The detailed [language specification](docs/superpowers/specs/2026-10-22-php-replacement-design.md)
and [implementation plan](docs/superpowers/plans/2026-10-22-mica-implementation.md)
describe this milestone.