# orca.html

> A module of Orca's API.

Writing HTML: every value escaped, markup only where it's said to be.

```mojo
var h = Html()
h.raw("<td>")
h.text(step.error)        # `<script>` comes out as text
h.raw("</td>")
h.link("/runs/7", "run 7")
```

`orca ui` writes its pages through this rather than a template engine: a
page is tables of records, and writing it in Mojo keeps each value's type
until the moment it's escaped.

## Structs

### `Html`

```mojo
struct Html
```

A page being written.

Implements: `Movable`, `Writable`

Fields:

- `out: String`

#### `__init__`

```mojo
def __init__(out self)
```

#### `raw`

```mojo
def raw[*Ts: Writable](mut self, *parts: *Ts.values)
```

Markup, written as it is. Only ever literals of this module's callers, never a value from the database or a request.

#### `text`

```mojo
def text[*Ts: Writable](mut self, *values: *Ts.values)
```

Values, each written and then escaped.

#### `link`

```mojo
def link(mut self, href: StringSpan, label: StringSpan)
```

`<a href="href">label</a>`, both escaped.

#### `link_out`

```mojo
def link_out(mut self, href: StringSpan, label: StringSpan)
```

A link that opens in a new tab: to code, or another site.

#### `cell`

```mojo
def cell[*Ts: Writable](mut self, *values: *Ts.values)
```

One `<td>` holding the values, escaped.

#### `status`

```mojo
def status(mut self, s: StringSpan)
```

A status as a badge, its class named after it.

#### `finish`

```mojo
def finish(deinit self) -> String
```

The page written.

#### `write_to`

```mojo
def write_to(self, mut writer: T)
```

## Functions

### `escape`

```mojo
def escape(s: StringSpan) -> String
```

`s` with `&`, `<`, `>`, `"` and `'` as character references, safe in text and in a quoted attribute.

### `url_encode`

```mojo
def url_encode(s: StringSpan) -> String
```

`s` as one path segment or query value: unreserved bytes as they are, every other byte as `%XX`.

### `url_decode`

```mojo
def url_decode(s: StringSpan) -> String
```

`%XX` and `+` in a query value decoded; a malformed escape is kept as it is.