diff --git a/website/content/docs/_index.md b/website/content/docs/_index.md index 406c50e..4f30ab3 100644 --- a/website/content/docs/_index.md +++ b/website/content/docs/_index.md @@ -2,6 +2,7 @@ title: Introduction layout: doc weight: -1 +menu: docs --- Here lies the documentation for Hilbish, the hyper extensible Lua shell. diff --git a/website/content/docs/faq.md b/website/content/docs/faq.md index 2cde8ee..d5cd1a2 100644 --- a/website/content/docs/faq.md +++ b/website/content/docs/faq.md @@ -2,6 +2,7 @@ title: Frequently Asked Questions layout: doc weight: -20 +menu: docs --- # Is Hilbish POSIX compliant? diff --git a/website/content/docs/features/_index.md b/website/content/docs/features/_index.md new file mode 100644 index 0000000..8343de6 --- /dev/null +++ b/website/content/docs/features/_index.md @@ -0,0 +1,8 @@ +--- +title: Features +layout: doc +weight: -40 +menu: docs +--- + + diff --git a/website/content/docs/features/runner-mode.md b/website/content/docs/features/runner-mode.md new file mode 100644 index 0000000..dcefe7f --- /dev/null +++ b/website/content/docs/features/runner-mode.md @@ -0,0 +1,67 @@ +--- +title: Runner Mode +description: Customize the interactive script/command runner. +layout: doc +menu: + docs: + 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. + diff --git a/website/content/docs/getting-started.md b/website/content/docs/getting-started.md index f148915..f0fe56d 100644 --- a/website/content/docs/getting-started.md +++ b/website/content/docs/getting-started.md @@ -2,6 +2,7 @@ title: Getting Started layout: doc weight: -10 +menu: docs --- To start Hilbish, open a terminal. If Hilbish has been installed and is not the diff --git a/website/themes/hsh/layouts/_default/doc.html b/website/themes/hsh/layouts/_default/doc.html index 90f28f3..419e2a0 100644 --- a/website/themes/hsh/layouts/_default/doc.html +++ b/website/themes/hsh/layouts/_default/doc.html @@ -4,12 +4,23 @@
@@ -17,6 +28,9 @@

{{ .Title }}

+ {{ if .Description }} +

{{ .Description }}

+ {{ end}} {{.Content}}