Embed
You can put earslang rules, and the compiler that checks them, in your own page or app. The compiler runs in the visitor's browser, and the text is sent nowhere.
A link to the playground
The address /playground/#code= followed by the rules as base64url (UTF-8, no padding) opens the playground with those rules in it. This makes one in a browser's console or your own script:
const text = "- R1: The app MUST save every change.";
let binary = "";
for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
"https://earslang.com/playground/#code=" + btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
An iframe of that address shows the whole playground page:
<iframe src="https://earslang.com/playground/#code=LSBSMTogVGhlIGFwcCBNVVNUIHNhdmUgZXZlcnkgY2hhbmdlLg" width="100%" height="600"></iframe>
The component
An <ears-playground> element is an editor that highlights the rules as the compiler reads them. With no attribute that is all it is. Each attribute below adds a part. Add this to a page:
<script src="https://earslang.com/embed/ui.v0.1.0/ears-playground.js"></script>
<ears-playground>
- R1: The app MUST save every change.
- R2: WHEN the user closes a file, THEN the app MUST ask before discarding changes.
</ears-playground>
The text inside the element is the starting text, with one newline at its start dropped. It is read once, when the element starts: after that the visitor's typing, value and openLink() change it. Write < as < and & as & in it. This is that element on this page, which loads the script from this site and sets wasm to this site's compiler:
With full it has every part:
<ears-playground full>
- R1: The app MUST save every change.
- R2: WHEN the user closes a file, THEN the app MUST ask before discarding changes.
</ears-playground>
The attributes are read once, when the element starts. Only readonly and wasm are read again later.
| Attribute | What it adds |
|---|---|
problems | A Problems tab that lists each problem the compiler found, with its code, its message and its place. A click on a problem selects its place in the text. Explain on a problem shows what its code means, from the errors page of the site the script came from, or of the page's own site when the script is a module or inlined. The panel says "No problems." when there are none. |
parts | A panel under the text that shows the parts of the rule the cursor is in: its ID, conditions, subject, keyword, response and tags, and the rule in the standard form. |
outputs | The JSON, Markdown, HTML and Gherkin exports, one tab each. They stop at an error. |
check | An ears check tab with the compiler's check text. |
reference | A Reference tab with the rule patterns, keywords, structure words and tags. A click on one puts it in the text. |
spelling | A switch between MUST and SHALL, which writes the spelling line of ears.mod. The switch is off until the compiler loads. |
mod-tab | Tabs for requirements.ears and ears.mod, so that ears.mod can be read and edited. |
open-link | An Open in playground link, which opens the earslang playground with the text in it. |
wrap | A Wrap switch over the text and the exports. It is on by default, and the choice is kept in this browser. |
full | Every attribute above that adds a part, from problems to wrap. |
readonly | The text cannot be edited. This is not part of full. |
wasm | The address of ears.wasm. The compiler is loaded once per page, so the first element's wasm attribute, or the first earslangLoad call, decides. Without it, the address is ../ears.v<compiler>/ears.wasm from the script's address, where <compiler> is the version the script was released with: this site's folder when the script comes from here, and a folder beside the script's own on your host when you serve both yourself. A script loaded as a module or inlined has no address of its own, and the same path is taken from the page's address. |
Each attribute can be set alone. Where one touches another, this is what happens:
| The element has | What it does |
|---|---|
| no attribute | It shows the editor and the highlighting. It holds ears.mod, which you can set with mod, but does not show it. One line under the editor says when the compiler is loading, did not load or stopped. |
problems without mod-tab | A problem in ears.mod is listed with its place as text. A click on it selects nothing. |
problems with mod-tab | A click on a problem in ears.mod opens the ears.mod tab and selects its place. |
spelling without mod-tab | The switch writes the held ears.mod, which is not shown. |
parts while the ears.mod tab is shown | The panel is empty. |
any of problems, outputs, check and reference | An output pane with one tab for each that is set, in that order. outputs has four tabs. |
| none of those four | No output pane. |
no wrap | Lines wrap, and there is no switch. |
readonly with reference or spelling | Inserts and spelling changes do nothing, and their controls are disabled. |
full with any other attribute but readonly or wasm | Every part is on, and the others change nothing. |
The Explain button of problems fetches the explanations from /errors/ on the script's own site, or on the page's site when the script is a module or inlined. A host that serves the script itself needs that page too, or Explain says the explanation did not load. The links in an explanation, to /playground/ and /spec/, are made from the same site as /errors/, so a host that serves its own /errors/ needs those pages too for the links to work. Otherwise leave out the problems attribute, or load the script from earslang.com. Where /errors/ is on another origin than the page, it needs to send Access-Control-Allow-Origin, since it is fetched.
| Name | Kind | What it does |
|---|---|---|
value | property | The text. Setting it compiles it again. |
mod | property | The text of ears.mod, empty for none. Setting it compiles again. Without mod-tab it is not shown, but the compiler reads it. |
compile() | method | Compiles the text now and returns a promise of the reply. The promise rejects when the compiler does not load or stops, or gives a reply that cannot be read. |
link() | method | Returns the address part that holds the text, and ears.mod when it is not blank, as the playground reads it, with its #: #code= and the text as base64url, then &mod= and ears.mod as base64url. |
openLink(hash) | method | Reads such an address part into the text and ears.mod, and shows the requirements.ears tab. It returns true when it read one, false when the link cannot be read (the text stays as it was), and null when hash holds no link. |
ears-result | event | Sent, and bubbling, after each compile that the compiler answered. Its detail is the reply, as the compiler interface below describes it. A reply with error set has ok false and an empty text, and no diagnostics. When the compiler does not load, stops or gives a reply that cannot be read, no ears-result is sent and compile() rejects. |
ears-stop | event | Sent, and bubbling, when the compiler stops. Its detail.error is the error as text. The compiler cannot run again in that page, so the element says to copy the text and reload the page, and compiles nothing more. |
tools | slot | A child of the element with slot="tools", there when the element starts, is put at the end of the bar over the text, such as a button of your own. It is styled like the bar's other buttons. |
reference-foot | slot | A child with slot="reference-foot" is put at the foot of the Reference tab. It shows only with reference. |
Set these custom properties on the element or on a rule that selects it. The defaults follow the visitor's light or dark setting, so set --ears-bg, --ears-fg, --ears-muted, --ears-line, --ears-panel and --ears-panel-head together, or the text can be hard to read, and check the highlighting colours against them.
| Property | What it sets |
|---|---|
--ears-bg | The background. |
--ears-fg | The text colour. |
--ears-muted | The colour of labels and secondary text. |
--ears-line | The border and the lines between parts. |
--ears-panel | The background of the text box, and of raised parts such as the inserts of the Reference tab. |
--ears-panel-head | The background of the tab bars and of the parts panel. |
--ears-keyword | The colour of keywords such as MUST. |
--ears-structure | The colour of structure words such as WHEN and THEN. |
--ears-id | The colour of a rule's ID. |
--ears-tag | The colour of tags such as [proposed]. |
--ears-error | The colour of an error. |
--ears-warning | The colour of a warning. |
--ears-font | The font of the labels, the problems and the tabs, as a font-family list. |
--ears-mono | The font of the text box, the inserts of the Reference tab, the chips of the parts panel, and code in the text exports, the ears check tab and the explanations (not the HTML export, which is its own page), as a font-family list. It is monospace without it. |
--ears-height | The height of the element, 24em without it. Where the element is narrower than 820px its parts stack, and its height follows them. |
--ears-min-height | The least height, 12em without it. |
The compiler interface
To make your own interface, load the compiler and call it. earslangLoad is in the same script as the component. It takes the address of ears.wasm, loads Go's wasm_exec.js from beside it if the page has not, and returns a promise that resolves when globalThis.earslang.compile can be called. The compiler loads once per page: a second call returns the first call's promise. Called with no address, earslangLoad() loads the compiler its UI version was released with. A page that already defines a different Go, for another Go wasm program, must load the wasm_exec.js that matches ears.wasm itself.
earslangLoad("https://earslang.com/embed/ears.v0.1.1/ears.wasm").then(() => {
const reply = JSON.parse(earslang.compile(JSON.stringify({
mod: null,
files: [{ path: "requirements.ears", text: "- R1: The app MUST save." }]
})));
console.log(reply.ok);
});
earslang.compile takes the request as JSON text and returns the reply as JSON text. The reply's fields are described in the package comment of cmd/ears-wasm/handle.go, at the version this site is built from.
Hosting it yourself
Build the compiler from its source, at the version the script loads by default, which is the DEFAULT_COMPILER line of its script, and take Go's loader from the Go that builds it:
git clone --branch v0.1.1 https://gitlab.com/earslang/ears
cd ears
GOOS=js GOARCH=wasm go build -o ears.wasm ./cmd/ears-wasm
cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" .
wasm_exec.js must come from the same Go release as ears.wasm. Run in the checkout, go env GOROOT names the Go that go build used there. Save https://earslang.com/embed/ui.v0.1.0/ears-playground.js too.
This site has two kinds of folder. A UI folder, /embed/ui.v<UI>/, holds the script. A compiler folder, /embed/ears.v<compiler>/, holds ears.wasm and wasm_exec.js. This site's are /embed/ui.v0.1.0/ and /embed/ears.v0.1.1/. A UI folder never changes after its release. It loads, without a wasm attribute, the compiler named on the DEFAULT_COMPILER line of its script, which is the compiler it was released with.
To host the files yourself, keep the two folders side by side under one parent, with the same names, since the default address is ../ears.v<compiler>/ from the script's address:
ui.v<UI>/ears-playground.js
ears.v<compiler>/ears.wasm
ears.v<compiler>/wasm_exec.js
Or put the files where you like and set the wasm attribute on each <ears-playground> to the address of your ears.wasm, or pass it to earslangLoad. ears.wasm finds wasm_exec.js beside it. wasm_exec.js is loaded with a script tag, which needs no Access-Control-Allow-Origin. ears.wasm is fetched, and needs it when it is on another origin than the page that loads it.
A page that loads the files from earslang.com does not redistribute them. A copy you serve does, and carries the licences listed in the Reference tab of the playground page: the Apache License 2.0 for ears.wasm, Go's licence for the Go runtime in it and for wasm_exec.js, and each module's own. ears-playground.js is under the Apache License 2.0, like the site's other scripts (LICENSE.txt).
Stability
- Each
/embed/ears.v<version>/folder of compiler files and each/embed/ui.v<version>/folder of the script is meant to stay at its address. This site's are/embed/ears.v0.1.1/and/embed/ui.v0.1.0/. - The element,
earslangLoad, and the request and the reply can differ between versions. A new version of the script is a new UI folder, and a released one does not change: the build fails when a file of it changes. - The folder of an older compiler stays served for as long as a UI folder defaults to it.
- A page picks a version by its address, and moves to another by changing it.
- The reply's
versionfield names the version of the language the compiler reads, such as 0.1. It is not the compiler's version in the folder name.