# gizlang/catalog

CC0 asset catalogs and pinned asset files. A lock names each file an app uses as `PATH SHA256 SIZE SOURCE`, the line form of the test data lock, and keeps no bytes in git: fetch takes each file into the shared cache once from its SOURCE, checks its hash, and reads it offline after. A SOURCE is an https URL, or `URL#MEMBER` for one file of a zip archive.

```gizlang
import * as Catalog from "gizlang/catalog";
```

## Types

### `Pin`

```gizlang
type Pin = { path: string; sha256: string; size: i64; source: string; }
```

One locked file: where the app reads it, its sha256 in hex, its size, and where its bytes come from.

- `path`: `string`
- `sha256`: `string`
- `size`: `i64`
- `source`: `string`

### `Asset`

```gizlang
type Asset = { pins: Vec<Pin>; note: string; }
```

A catalog entry resolved to its files, and the line that credits it in the lock.

- `pins`: `Vec<gizlang_catalog.Pin>`
- `note`: `string`

### `Found`

```gizlang
type Found = { spec: string; name: string; kind: string; tags: Vec<string>; license: string; }
```

One asset a search found: the SPEC that resolve takes, its name, its kind ("model", "texture" or "hdri"), its words
(tags and categories), and its license.

- `spec`: `string`
- `name`: `string`
- `kind`: `string`
- `tags`: `Vec<string>`
- `license`: `string`

## Functions

### `parseLock`

```gizlang
function parseLock(text: string): Vec<Pin> throws string
```

The pins of the lock TEXT: one `PATH SHA256 SIZE SOURCE` line each; `#` lines are notes.

Effects: fail, alloc.

### `lockText`

```gizlang
function lockText(notes: Vec<string>, pins: Vec<Pin>): string
```

The lock of PINS, sorted by path, under the credit lines NOTES.

Effects: fail, alloc.

### `cacheFolder`

```gizlang
function cacheFolder(): string
```

The folder of fetched objects, named by their sha256: `$GIZLANG_CACHE/assets`, else `~/.cache/gizlang/assets`.

Effects: fail, io, alloc.

### `fetchPin`

```gizlang
function fetchPin(pin: Pin, folder: string = cacheFolder()): bytes throws string
```

PIN's bytes from the cache FOLDER, fetched from its source the first time; a hash or size that differs fails.

Effects: fail, read, write, console, io, alloc.

### `fetch`

```gizlang
function fetch(text: string, folder: string = cacheFolder()): Map<string, bytes> throws string
```

Every file of the lock TEXT, by its path.

Effects: fail, read, write, console, io, alloc.

### `pin`

```gizlang
function pin(path: string, source: string, folder: string = cacheFolder()): Pin throws string
```

A pin of the file at SOURCE, read once to hash it, kept at PATH.

Effects: fail, read, write, console, io, alloc.

### `polyhaven`

```gizlang
function polyhaven(id: string, resolution: string): Asset throws string
```

The Poly Haven asset ID (polyhaven.com, CC0) at RESOLUTION ("1k", "2k", ...), its files under ID/: a model's
glTF with its buffer and textures, a texture's color, normal (OpenGL), ARM and displacement maps, or an HDRI's .hdr.

Effects: fail, read, write, console, io, alloc.

### `ambientcg`

```gizlang
function ambientcg(id: string, resolution: string): Asset throws string
```

The ambientCG material ID (ambientcg.com, CC0) at RESOLUTION ("1K-JPG", "2K-JPG", ...): its color, normal (OpenGL),
roughness and ambient occlusion maps under ID/, each a member of the material's zip archive.

Effects: fail, read, write, console, io, alloc.

### `khronos`

```gizlang
function khronos(name: string): Asset throws string
```

The Khronos glTF sample model NAME (github.com/KhronosGroup/glTF-Sample-Assets) under NAME/: its .glb, else its
.gltf with the buffers and images it names. Each model has its own license: the note quotes its README's.

Effects: fail, read, write, console, io, alloc.

### `resolve`

```gizlang
function resolve(spec: string, note: string = ""): Asset throws string
```

The asset that SPEC names, its files under its ID: `polyhaven:ID[@RES]`, `ambientcg:ID[@RES]`, `khronos:NAME`, or
`PATH=URL[#MEMBER]` for any one file (a member of a zip archive with #), whose license the caller states in NOTE.

Effects: fail, read, write, console, io, alloc.

### `notes`

```gizlang
function notes(text: string): Vec<string>
```

The credit lines of the lock TEXT.

Effects: fail, alloc.

### `added`

```gizlang
function added(text: string, asset: Asset): string throws string
```

The lock TEXT with ASSET added: its files replace pins of the same path, and its note one of the same catalog spec
(`SOURCE:ID`) or the same text, so the files of one archive share one credit.

Effects: fail, alloc.

### `polyhavenFound`

```gizlang
function polyhavenFound(index: Json, words: Vec<string>, kind: string): Vec<Found>
```

The assets of Poly Haven's index INDEX (GET /assets: each id to its name, type, tags and categories) that match
WORDS, of KIND ("" for any), best first.

Effects: fail, alloc.

### `ambientcgFound`

```gizlang
function ambientcgFound(found: Json, words: Vec<string>): Vec<Found>
```

The materials of an ambientCG answer FOUND (GET /api/v2/full_json) that match WORDS, best first.

Effects: fail, alloc.

### `search`

```gizlang
function search(query: string, kind: string = "", most: i64 = 20): Vec<Found> throws string
```

The public assets that match QUERY (words), of KIND ("model", "texture", "hdri" or "" for any), at most MOST, best
first: Poly Haven's models, textures and HDRIs and ambientCG's materials (both CC0), and Khronos's glTF samples by name
(each its own license, which resolve's note quotes). Each SPEC goes to resolve, then to a lock (added).

Effects: fail, read, write, console, io, alloc.

