From 16721713db31ff5cb2907b2087645502381819d7 Mon Sep 17 00:00:00 2001 From: sammyette Date: Tue, 13 Dec 2022 15:14:30 -0400 Subject: [PATCH] website(docs/runner-mode): change up docs for runner mode --- website/content/docs/features/runner-mode.md | 64 +++----------------- 1 file changed, 7 insertions(+), 57 deletions(-) diff --git a/website/content/docs/features/runner-mode.md b/website/content/docs/features/runner-mode.md index dcefe7f..87ecc8b 100644 --- a/website/content/docs/features/runner-mode.md +++ b/website/content/docs/features/runner-mode.md @@ -7,61 +7,11 @@ menu: parent: "Features" --- -Hilbish is *unique,* when interactive it first attempts to run input as -Lua and then tries shell script. But if you're normal, you wouldn't -really be using Hilbish anyway but you'd also not want this -(or maybe want Lua only in some cases.) - -The "runner mode" of Hilbish is customizable via `hilbish.runnerMode`, -which determines how Hilbish will run user input. By default, this is -set to `hybrid` which is the previously mentioned behaviour of running Lua -first then going to shell script. If you want the reverse order, you can -set it to `hybridRev` and for isolated modes there is `sh` and `lua` -respectively. - -You can also set it to a function, which will be called everytime Hilbish -needs to run interactive input. For example, you can set this to a simple -function to compile and evaluate Fennel, and now you can run Fennel. -You can even mix it with sh to make a hybrid mode with Lua replaced by -Fennel. - -An example: -```lua -hilbish.runnerMode(function(input) - local ok = pcall(fennel.eval, input) - if ok then - return input, 0, nil - end - - return hilbish.runner.sh(input) -end) -``` - -The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode` -and also provides the sh and Lua runner functions that Hilbish itself uses. -A runner function is expected to return 3 values: the input, exit code, and an error. -The input return is there incase you need to prompt for more input. -If you don't, just return the input passed to the runner function. -The exit code has to be a number, it will be 0 otherwise and the error can be -`nil` to indicate no error. - -## Functions -These are the "low level" functions for the `hilbish.runner` interface. - -+ setMode(mode) > The same as `hilbish.runnerMode` -+ sh(input) -> input, code, err > Runs `input` in Hilbish's sh interpreter -+ lua(input) -> input, code, err > Evals `input` as Lua code - -The others here are defined in Lua and have EmmyLua documentation. -These functions should be preferred over the previous ones. -+ setCurrent(mode) > The same as `setMode`, but works with runners managed -via the functions below. -+ add(name, runner) > Adds a runner to a table of available runners. The `runner` -argument is either a function or a table with a run callback. -+ set(name, runner) > The same as `add` but requires passing a table and -overwrites if the `name`d runner already exists. -+ get(name) > runner > Gets a runner by name. It is a table with at least a -run function, to run input. -+ exec(cmd, runnerName) > Runs `cmd` with a runner. If `runnerName` isn't passed, -the current runner mode is used. +Hilbish allows you to change how interactive text can be interpreted. +This is mainly due to the fact that the default method Hilbish uses +is that it runs Lua first and then falls back to shell script. +In some cases, someone might want to switch to just shell script to avoid +it while interactive but still have a Lua config, or go full Lua to use +Hilbish as a REPL. This also allows users to add alternative languages, +instead of either like Fennel.