Skip to content

Commit

Permalink
doc(uri): add space to formatting in the README
Browse files Browse the repository at this point in the history
  • Loading branch information
nrdxp committed Oct 30, 2024
1 parent 737d5a4 commit 7d6a82c
Showing 1 changed file with 19 additions and 9 deletions.
28 changes: 19 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,31 @@ To bridge this gap, Eka's working design incorporates:

## The Atom URI

In order to provide a polished and simple UI, atom's have a convenient URI format which naturally help address them. Conceptually, an atom URI is just a URL with a configurable shortener mechanism (aliases), sane defaults to help elide the scheme in many scenarios, and a custom extension at the end to address atoms unambiguously; abstractly expressed as:
In order to provide a polished and simple UI, atom's have a convenient URI format which naturally help address them.

Conceptually, an atom URI is just a URL with a configurable shortener mechanism (aliases), sane defaults to help elide the scheme in many scenarios, and a custom extension at the end to address atoms unambiguously; abstractly expressed as:
```
[scheme://][[user[:pass]@][url-alias:][url-fragment::]atom-id[@version]
```

### Concrete Examples

Below are some examples of atom URIs, with the URL portion expanded to demonstrate the alias functionality. Aliases are user settable via the `eka.toml` file, and some convenient defaults (`gh -> github.com`) are built in. Atom's themselves, are abstracted to a flat namespace within the store, regardless of its physical location. To demonstrate this, in the following examples, say we have an atom manifest in your git repo at `foo/bar/my@.toml` which species the `atom.id` in the TOML as `my-atom`:

* `gh:owner/repo::my-atom@^1 -> https://github.com/owner/repo`: the `@^1` is a semantic version request
* `gl:owner/repo::my-atom -> https://gitlab.com/owner/repo`: no version (`@`) means fetch the latest
* `org:repo::my-atom@0.1.0 -> https://github.com/work-org/repo`: assuming the user sets `org = "gh:work-org"` in the `eka.toml`. Notice that users can refer to other aliases in the config to "compose" them.
* `git@gh:owner/repo::my-atom -> ssh://git@github.com:owner/repo`: a URL with a user specification defaults to ssh
* `git:pass@gh:owner/repo::my-atom -> https://git@github.com/owner/repo`: a user:pass combo defaults to https
* `http://gh:owner/repo::my-atom -> http://github.com/owner/repo`: it is possible to explicate the scheme where necessary, but the heuristics try to make this uncommon
Below are some examples of atom URIs, with the URL portion expanded to demonstrate the alias functionality. Aliases are user settable via the `eka.toml` file, and some convenient defaults (`gh -> github.com`) are built in.

Atom's, themselves, are abstracted to a flat namespace within the store, regardless of its physical location. To demonstrate this, in the following examples, say we have an atom manifest in the git repo at `foo/bar/my@.toml` which species the `atom.id` in the TOML as `my-atom`:

* `gh:owner/repo::my-atom@^1 -> https://github.com/owner/repo`
* the `@^1` is a semantic version request
* `gl:owner/repo::my-atom -> https://gitlab.com/owner/repo`
* no version (`@`) means fetch the latest
* `org:repo::my-atom@0.1.0 -> https://github.com/work-org/repo`
* assuming the user sets `org = "gh:work-org"` in the `eka.toml`. Notice that users can refer to other aliases in the config to "compose" them.
* `git@gh:owner/repo::my-atom -> ssh://git@github.com:owner/repo`
* a URL with a user specification defaults to ssh
* `git:pass@gh:owner/repo::my-atom -> https://git@github.com/owner/repo`
* a user:pass combo defaults to https
* `http://gh:owner/repo::my-atom -> http://github.com/owner/repo`
* it is possible to explicate the scheme where necessary, but the heuristics try to make this uncommon

## Usage

Expand Down

0 comments on commit 7d6a82c

Please sign in to comment.