Skip to content

REPL Directives

Jump to bottom
biface edited this page Oct 10, 2026 · 1 revision

REPL Directives Configuration

English | Français

Since v0.10.0 (DA-030).
Last Updated: 2026-10-10

In the REPL, a line starting with : is a directive handled by the framework itself; any other line is an application command. The set of directives is fixed by the version of dynamic-cli. The optional directives: section of the configuration can rename a directive and replace its aliases and description, for instance to translate them. It cannot add a directive, remove one or change its arguments.

Directives exist only in the REPL. In CLI mode, use --help / -h as before; they also keep working in the REPL.

Table of Contents

Default Directives

implementation Typed as Aliases Action
repl_help :help [command] :h, :? Show the application help, or the help of one command
repl_load :load <path> — Run every line of a script file in the current session
repl_quit :quit :q Save the session history, then leave the REPL
repl_exit :exit — Leave the REPL without saving the session history

Structure

directives:                      # Optional
  - implementation: string       # Required: directive to override (see table above)
    name: string                 # Required: new name, typed after ':'
    aliases: [string]            # Optional: new aliases (default: [])
    description: string          # Required: text shown by :help

Fields

Field Type Required Description
implementation string ✅ Yes Directive to override: repl_help, repl_load, repl_quit or repl_exit
name string ✅ Yes Name typed after :, written without the :
aliases array ❌ No Other names typed after :; replaces the default aliases
description string ✅ Yes Description shown in the help listing

Merge Rule

Entries are matched to directives by implementation:

  • an entry replaces the name, the aliases and the description of its directive — all three, so an entry without aliases leaves the directive with no alias at all;
  • a directive without an entry keeps its defaults;
  • the arguments of a directive ([command], <path>) are part of its action and cannot be configured.

Example

French names for :help and :quit; :load and :exit keep their defaults:

directives:
  - implementation: repl_help
    name: aide
    aliases: [a, "?"]
    description: "Afficher l'aide, ou l'aide d'une commande"
  - implementation: repl_quit
    name: quitter
    aliases: [q]
    description: "Enregistrer l'historique et quitter"

In the REPL, :aide, :a and :? now show the help, :quitter and :q leave it. :help and :h are no longer recognised: the error lists the available directives.

Validation Rules

An unknown implementation fails as soon as the file is loaded. The other rules are checked by the configuration validator, which CliBuilder::build() always runs:

  • implementation must be one of the four values above;
  • each implementation appears at most once;
  • name and every alias are non-empty, contain no whitespace and do not start with : (the REPL adds it);
  • names and aliases are unique across all directives after the merge, defaults included: an override cannot take q while :quit keeps it as its alias.

Directive names are never compared with command names, since a directive is always typed with its :. Conversely, command names and aliases may not start with : (see Command Definition).

Behaviour

  • :quit and :exit: :quit writes the session history to disk, then leaves; :exit leaves without writing it. End of input (Ctrl-D) behaves like :quit. Any other way out — a handler calling std::process::exit, a crash, the process being killed — leaves the history file as it was at the start of the session.

  • Names typed without :: quit or exit alone is looked up as an application command. When the word is a directive name or alias (as configured) and the application has no command of that name, the error suggests the directive (:quit). The Complete Example of the configuration reference declares its own exit command: there, exit runs that command and :exit the directive.

  • :load scripts: each line runs as if typed, directives included, except :quit and :exit, which are reported and skipped.

  • Help listing: :help (and --help in the REPL) shows the application help followed by a DIRECTIVES section, under the effective names:

    DIRECTIVES:
    :help [command]      Show the application help, or the help of a command [aliases: :h, :?]
    :load <path>         Run every line of a script file
    :quit                Save the session history and leave [aliases: :q]
    :exit                Leave without saving the session history

  • Completion: after a leading :, Tab completes directive names and aliases, under their configured names.

Home

English

Français

Clone this wiki locally