ela
Contents

ManualShell

Startup config and prompt

In the terminalela --spec startup-config-and-prompt

All files follow the XDG Base Directory spec; nothing is written directly into the home directory.

FileLocation (default)
Startup config$XDG_CONFIG_HOME/ela/init.ela (~/.config/ela/init.ela)
Login config$XDG_CONFIG_HOME/ela/login.ela (~/.config/ela/login.ela)
History$XDG_STATE_HOME/ela/history (~/.local/state/ela/history)
  • Startup file: ~/.config/ela/init.ela, written in ela.
  • The directory is named ela after the binary.
  • The prompt is a proc named prompt that returns a string. No PS1-style escape codes: the string is isocline's markup, and isocline writes the escapes and counts the prompt's width.
  • ela puts one space after the prompt, so a prompt ends at its mark: "> " would show two. Ctrl-R's history search label is followed by the same space.
  • A prompt proc that fails, or returns anything but a string, gives the plain prompt ela> .
proc prompt()    folder = markup_text(path.base(path.abs(".")))    return "[ansi-teal]${folder}[/] >"end proc

Markup is a tag in square brackets, closed by [/name] or by [/] for the last one opened:

MarkupShows
[b]…[/b], [i]…[/i], [u]…[/u], [r]…[/r]bold, italic, underlined, reversed
[ansi-maroon]…[/]one of the terminal's own colours, which follow its theme: ansi-black, ansi-maroon, ansi-green, ansi-olive, ansi-navy, ansi-purple, ansi-teal, ansi-silver, and the bright ansi-gray, ansi-red, ansi-lime, ansi-yellow, ansi-blue, ansi-magenta, ansi-cyan, ansi-white
[#ff8800]…[/]a colour of its own, #rrggbb
[on #203040]…[/], [on ansi-navy]…[/]a background
[b ansi-teal]…[/]several at once

There is no dim or faint. \[ is a [ shown as it is, and \\ a backslash.

  • A value put into the prompt, such as a folder or a branch name, goes through markup_text(s), which escapes its [ and \, so a folder named [b]x shows as written and never as markup.
  • A prompt of several lines is split at its last newline: the lines above are printed once, and the last is the line isocline edits after. A tag opened on one line closes at its end.
  • last_status() is the exit status of the last line run at the prompt: 0 when it went well, a failed command's code, 1 for an error, and 130 when Ctrl-C stopped it or dropped the line being typed. last_duration() is how long that line took, from Enter to its end, in seconds, such as 12.4; 0 after Ctrl-C at the prompt. Both are 0 before the first line, and a blank line leaves the status as it was and makes the duration 0, so a time shown in the prompt shows once.
  • Both work in the interactive shell only. A script has no prompt and no hidden status (LANGUAGE.md, Error handling): there each is an error that says what to write instead, err = try cmd for the command's failure, its exit code $err.code.
proc prompt()    code = last_status()    if $code != 0        return "[ansi-maroon]${code}[/] >"    end if    return ">"end proc

examples/init.ela is a whole prompt in the style of kat800's: user@host, the folder, the git branch with its changed files and the commits ahead and behind, kat800's sandbox, how long the last line took once it reached KAT800_REPORTTIME seconds, and a failed line's code, with Nerd Font glyphs. The line typed on is marked €, which no one reads as code, since $ is ela's variable sigil; $ where the locale is not UTF-8 (LC_ALL, else LC_CTYPE, else LANG), and a bold red # as root. The package installs it as /usr/share/ela/examples/init.ela; copy it to ~/.config/ela/init.ela. It works out once what stays the same while the shell runs, reads the folder without starting a program, and runs git only inside a repository.

Login shell #

A login shell reads login.ela once, before anything else, and every interactive shell reads init.ela, as bash reads .profile and .bashrc. ela is a login shell when it is started as -ela, the - before its name that login, sshd and a terminal's login option put there, or with ela --login.

What an ela reads before its prompt or its script: login.ela, init.ela or neither

FileRead byHolds
login.elaa login shell, once, before its prompt, script, -c code or script on stdin: a console login, ssh host, ela --loginthe environment that everything started after it inherits, env.PATH, env.EDITOR, env.ELA_LIB, umask, ulimit, and commands run once at login, ssh-add
init.elaevery interactive shell, after login.ela in a login onethe prompt, aliases, usage.bar: nothing a script needs
  • login.ela holds what init.ela may, settings, env. lines, if blocks and procs, and commands too.
  • At the prompt it runs in the shell itself, so what it declares stays. Before a script, -c code or a script on stdin it runs on its own, and the script starts with the environment it left. Its folder, umask and limits hold either way.
  • An error in it is said with its place, and the shell or the script goes on with what the lines before it set.
  • Aliases and the prompt go in init.ela: a login shell that runs a script has no prompt, and an alias there is an error.
  • A line of bash that an installer adds to .profile goes in as it is written, through env.from_bash (LANGUAGE.md, The environment): bash runs it, and the variables it set come into ela's environment.

Each line a .profile holds, in login.ela:

.profilelogin.ela
export PATH="$HOME/.local/bin:$PATH"env.PATH = "$env.HOME/.local/bin:$env.PATH"
export EDITOR=nanoenv.EDITOR = "nano"
umask 077umask 077
ulimit -c 0ulimit -c 0
eval "$(ssh-agent -s)"env.from_bash('eval "$(ssh-agent -s)"')
. "$HOME/.cargo/env"env.from_bash('. "$HOME/.cargo/env"')
[ -z "$DISPLAY" ] && [ "$XDG_VTNR" = 1 ] && exec startxif env.get("DISPLAY") == "" and env.get("XDG_VTNR") == "1", then exec startx in the block

examples/login.ela holds these lines. A line that sets up a tool sits in an if that runs it only where the tool is there, so the file works as it is on a machine without cargo, ssh-agent or X, and EDITOR is set only when it is unset. The package installs it as /usr/share/ela/examples/login.ela; copy it to ~/.config/ela/login.ela. Two of its lines:

if file.exists("$env.HOME/.cargo/env")    env.from_bash('. "$HOME/.cargo/env"')end if if env.get("SSH_AUTH_SOCK") == "" and path.program("ssh-agent") != ""    env.from_bash('eval "$(ssh-agent -s)" >/dev/null')end if

Where a script's environment comes from depends on what started it:

Started fromIts environmentA variable it needs goes
the prompt of a login shell, or a program started from itlogin.ela'sin login.ela
ssh host, a console loginlogin.ela's: sshd and login start -elain login.ela
ssh host cmdsshd's: sshd runs ela -c 'cmd', which is no login shellin login.ela, with the command run as ssh host ela --login -c 'cmd'
cronthe crontab's: cron reads no shell fileon a line of the crontab: EDITOR=nano
the desktop session: a menu, a launcher, a terminal it opensthe session's: it runs .profile through /bin/sh, which can't read elain a file in ~/.config/environment.d/: EDITOR=nano

environment.d holds what the desktop needs; login.ela holds ela's own setup, the search path, ELA_LIB and the rest.