# chicken-sourcehut

CHICKEN Scheme client for [sr.ht](https://sr.ht/).

## Resources

 * Sources: <https://git.sr.ht/~evhan/chicken-sourcehut>
 * Issues: <https://todo.sr.ht/~evhan/chicken-sourcehut>
 * Documentation: <https://api.call-cc.org/5/doc/sourcehut>

## Installation

### Extension Library

Use your distribution's package manager to install CHICKEN 5.0 or newer,
then run:

``` shell
chicken-install -s sourcehut
```

On some platforms you may be required to install OpenSSL development
headers first.

## Examples

### Using the Extension Library

Create a new job on [builds.sr.ht](https://builds.sr.ht/) and fetch
information about it:

``` scheme
(import (sourcehut)
        (sourcehut builds))

(access-token "your-access-token-goes-here")

(create (job manifest: "xyz"))
; => ((#:service "builds" #:path "/api/jobs")
;     (id . 1234))

(retrieve (job 1234))
; => ((#:service "builds" #:path "/api/jobs/1234")
;     (id . 1234)
;     (status . "running")
;     (setup_log ...)
;     (tasks . #(...))
;     (runner ...))

(retrieve (manifest 1234))
; => "xyz"
```

### Using the Command Line Interface

As above, but using the `sourcehut` CLI program.

``` bash
$ export SOURCEHUT_CLI_ACCESS_TOKEN="your-access-token-goes-here"

$ sourcehut create job --manifest build.yaml --note "Example build"
((id . 1234))

$ sourcehut get job 1234
((id . 1234)
 (status . "running")
 (setup_log ...)
 (tasks . #(...))
 (runner ...))

$ sourcehut get job 1234 -o json | jq
{
  "id": 1234,
  "status": "running",
  "setup_log": ...,
  "tasks": [...],
  "note": "Example build",
  "runner": ...
}
```

## Documentation

Full API documentation for the Scheme library is available on
[wiki.call-cc.org][] and [api.call-cc.org][].

For CLI documentation, refer to the program's man page. This is available
online [here][man page] or via the `sourcehut help` command once the program is
installed. To view the latest version in your terminal without installing the
program first, you can run:

``` bash
wget -O- https://git.sr.ht/~evhan/chicken-sourcehut/blob/master/sourcehut.1 | man /dev/stdin
```

[wiki.call-cc.org]: https://eggs.call-cc.org/5/sourcehut
[api.call-cc.org]: https://api.call-cc.org/5/doc/sourcehut
[man page]: https://git.sr.ht/~evhan/chicken-sourcehut/blob/master/sourcehut.1.md

## License

Three-clause BSD. See LICENSE for details.