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 &lt; and & as &amp; in it. This is that element on this page, which loads the script from this site and sets wasm to this site's compiler:

- R1: The app MUST save every change. - R2: WHEN the user closes a file, THEN the app MUST ask before discarding changes.

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>
- R1: The app MUST save every change. - R2: WHEN the user closes a file, THEN the app MUST ask before discarding changes.

The attributes are read once, when the element starts. Only readonly and wasm are read again later.

The attributes
AttributeWhat it adds
problemsA 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.
partsA 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.
outputsThe JSON, Markdown, HTML and Gherkin exports, one tab each. They stop at an error.
checkAn ears check tab with the compiler's check text.
referenceA Reference tab with the rule patterns, keywords, structure words and tags. A click on one puts it in the text.
spellingA switch between MUST and SHALL, which writes the spelling line of ears.mod. The switch is off until the compiler loads.
mod-tabTabs for requirements.ears and ears.mod, so that ears.mod can be read and edited.
open-linkAn Open in playground link, which opens the earslang playground with the text in it.
wrapA Wrap switch over the text and the exports. It is on by default, and the choice is kept in this browser.
fullEvery attribute above that adds a part, from problems to wrap.
readonlyThe text cannot be edited. This is not part of full.
wasmThe 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:

How the attributes combine
The element hasWhat it does
no attributeIt 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-tabA problem in ears.mod is listed with its place as text. A click on it selects nothing.
problems with mod-tabA click on a problem in ears.mod opens the ears.mod tab and selects its place.
spelling without mod-tabThe switch writes the held ears.mod, which is not shown.
parts while the ears.mod tab is shownThe panel is empty.
any of problems, outputs, check and referenceAn output pane with one tab for each that is set, in that order. outputs has four tabs.
none of those fourNo output pane.
no wrapLines wrap, and there is no switch.
readonly with reference or spellingInserts and spelling changes do nothing, and their controls are disabled.
full with any other attribute but readonly or wasmEvery 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.

Properties, methods, events and slots
NameKindWhat it does
valuepropertyThe text. Setting it compiles it again.
modpropertyThe text of ears.mod, empty for none. Setting it compiles again. Without mod-tab it is not shown, but the compiler reads it.
compile()methodCompiles 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()methodReturns 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)methodReads 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-resulteventSent, 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-stopeventSent, 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.
toolsslotA 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-footslotA 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.

PropertyWhat it sets
--ears-bgThe background.
--ears-fgThe text colour.
--ears-mutedThe colour of labels and secondary text.
--ears-lineThe border and the lines between parts.
--ears-panelThe background of the text box, and of raised parts such as the inserts of the Reference tab.
--ears-panel-headThe background of the tab bars and of the parts panel.
--ears-keywordThe colour of keywords such as MUST.
--ears-structureThe colour of structure words such as WHEN and THEN.
--ears-idThe colour of a rule's ID.
--ears-tagThe colour of tags such as [proposed].
--ears-errorThe colour of an error.
--ears-warningThe colour of a warning.
--ears-fontThe font of the labels, the problems and the tabs, as a font-family list.
--ears-monoThe 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-heightThe height of the element, 24em without it. Where the element is narrower than 820px its parts stack, and its height follows them.
--ears-min-heightThe 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