the event emitter
Bait is the event emitter for Hilbish. Why name it bait? Why not. +It throws hooks that you can catch. This is what you will use if +you want to listen in on hooks to know when certain things have +happened, like when you’ve changed directory, a command has failed, +etc. To find all available hooks thrown by Hilbish, see doc hooks.
Catches a hook with name. Runs the cb when it is thrown
Same as catch, but only runs the cb once and then removes the hook
Returns a table with hooks on the event with name.
Removes the catcher for the event with name
+For this to work, catcher has to be the same function used to catch
+an event, like one saved to a variable.
Throws a hook with name with the provided args
library for custom commands
Commander is a library for writing custom commands in Lua.
Deregisters any command registered with name
Register a command with name that runs cb when ran
filesystem interaction and functionality library
The fs module provides easy and simple access to filesystem functions +and other things, and acts an addition to the Lua standard library’s +I/O and filesystem functions.
Gives an absolute version of path.
Gives the basename of path. For the rules,
+see Go’s filepath.Base
Changes directory to dir
Returns the directory part of path. For the rules, see Go’s
+filepath.Dir
Glob all files and directories that match the pattern. +For the rules, see Go’s filepath.Glob
Takes paths and joins them together with the OS’s +directory separator (forward or backward slash).
Makes a directory called name. If recursive is true, it will create its parent directories.
Returns a table of files in dir
Returns info about path
command aliasing
The alias interface deals with all command aliases in Hilbish.
This is an alias (ha) for the hilbish.alias function.
Removes an alias.
Get a table of all aliases.
Tries to resolve an alias to its command.
tab completions
The completions interface deals with tab completions.
Calls a completer function. This is mainly used to call
+a command completer, which will have a name in the form
+of command.name, example: command.git
The handler function is the callback for tab completion in Hilbish. +You can check the completions doc for more info.
Returns binary/executale completion candidates based on the provided query.
Returns file completion candidates based on the provided query.
interactions for Hilbish's line reader
The hilbish.editor interface provides functions to +directly interact with the line editor in use.
Returns the current input line.
Returns the text that is at the register.
Inserts text into the line.
Sets the vim register at register to hold the passed text.
command history
The history interface deals with command history. +This includes the ability to override functions to change the main +method of saving history.
Adds a command to the history.
Deletes all commands from the history.
Retrieves a command from the history based on the idx.
Returns the amount of commands in the history.
background job management
Manage interactive jobs in Hilbish via Lua.
Jobs are the name of background tasks/commands. A job can be started via +interactive usage or with the functions defined below for use in external runners.
cmd: The user entered command string for the job.running: Whether the job is running or not.id: The ID of the job in the job tablepid: The Process IDexitCode: The last exit code of the job.stdout: The standard output of the job. This just means the normal logs of the process.stderr: The standard error stream of the process. This (usually) includes error messages of the job.Puts a job in the background. This acts the same as initially running a job.
Puts a job in the foreground. This will cause it to run like it was +executed normally and wait for it to complete.
Starts running the job.
Stops the job from running.
Adds a new job to the job table. Note that this does not immediately run it.
Returns a table of all job objects.
Disowns a job. This deletes it from the job table.
Get a job object via its ID.
Returns the last added job from the table.
OS Info
The os interface provides simple text information properties about
+the current OS on the systen. This mainly includes the name and
+version.
family: Family name of the current OSname: Pretty name of the current OSversion: Version of the current OSinteractive command runner customization
The runner interface contains functions that allow the user to change +how Hilbish interprets interactive input. +Users can add and change the default runner for interactive input to any +language or script of their choosing. A good example is using it to +write command in Fennel.
This is the same as the hilbish.runnerMode function. It takes a callback,
+which will be used to execute all interactive input.
+In normal cases, neither callbacks should be overrided by the user,
+as the higher level functions listed below this will handle it.
Evaluates cmd as Lua input. This is the same as using dofile
+or load, but is appropriated for the runner interface.
Runs a command in Hilbish’s shell script interpreter.
+This is the equivalent of using source.
timeout and interval API
The timers interface si one to easily set timeouts and intervals +to run functions after a certain time or repeatedly without using +odd tricks.
type: What type of timer it isrunning: If the timer is runningduration: The duration in milliseconds that the timer will runStarts a timer.
Stops a timer.
Creates a timer that runs based on the specified time in milliseconds.
+The type can either be interval (value of 0) or timeout (value of 1).
Retrieves a timer via its ID.
user-related directories
This interface just contains properties to know about certain user directories. +It is equivalent to XDG on Linux and gets the user’s preferred directories +for configs and data.
config: The user’s config directorydata: The user’s directory for program datathe core Hilbish API
The Hilbish module includes the core API, containing +interfaces and functions which directly relate to shell functionality.
ver: The version of Hilbishuser: Username of the userhost: Hostname of the machinedataDir: Directory for Hilbish data files, including the docs and default modulesinteractive: Is Hilbish in an interactive shell?login: Is Hilbish the login shell?vimMode: Current Vim input mode of Hilbish (will be nil if not in Vim input mode)exitCode: xit code of the last executed commandSets an alias of cmd to orig
Appends dir to $PATH
Registers a completion handler for scope.
+A scope is currently only expected to be command.<cmd>,
+replacing command.git).
+cb must be a function that returns a table of “completion groups.”
+Check doc completions for more information.
Returns the current directory of the shell
Replaces running hilbish with cmd
Puts fn in a goroutine
Line highlighter handler. This is mainly for syntax highlighting, but in +reality could set the input of the prompt to display anything. The +callback is passed the current line and is expected to return a line that +will be used as the input display.
The command line hint handler. It gets called on every key insert to +determine what text to use as an inline hint. It is passed the current +line and cursor position. It is expected to return a string which is used +as the text for the hint. This is by default a shim. To set hints, +override this function with your custom handler.
Sets the input mode for Hilbish’s line reader. Accepts either emacs or vim
Runs the cb function every time milliseconds.
+Returns a timer object (see doc timers).
Changes the continued line prompt to str
Prepends dir to $PATH
Changes the shell prompt to str
+There are a few verbs that can be used in the prompt text.
+These will be formatted and replaced with the appropriate values.
+%d - Current working directory
+%u - Name of current user
+%h - Hostname of device
Read input from the user, using Hilbish’s line editor/input reader.
+This is a separate instance from the one Hilbish actually uses.
+Returns input, will be nil if ctrl + d is pressed, or an error occurs (which shouldn’t happen)
Runs cmd in Hilbish’s sh interpreter.
+If returnOut is true, the outputs of cmd will be returned as the 2nd and
+3rd values instead of being outputted to the terminal.
Sets the execution/runner mode for interactive Hilbish. This determines whether +Hilbish wll try to run input as Lua and/or sh or only do one of either. +Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), +sh, and lua. It also accepts a function, to which if it is passed one +will call it to execute user input instead.
Runs the cb function after time in milliseconds
+Returns a timer object (see doc timers).
Checks if name is a valid command
low level terminal library
The terminal library is a simple and lower level library for certain terminal interactions.
Restores the last saved state of the terminal
Saves the current state of the terminal
Puts the terminal in raw mode
Gets the dimensions of the terminal. Returns a table with width and height
+Note: this is not the size in relation to the dimensions of the display
Last updated Dec 13, 2022
No, it is not. POSIX compliance is a non-goal. Perhaps in the future, +
Last updated Dec 13, 2022
No, it is not. POSIX compliance is a non-goal. Perhaps in the future, someone would be able to write a native plugin to support shell scripting (which would be against it’s main goal, but ….)
It compiles for Windows (CI ensures it does), but otherwise it is not directly supported. If you’d like to improve this situation, diff --git a/docs/features/index.html b/docs/features/index.html index a5bb5e7..31d3111 100644 --- a/docs/features/index.html +++ b/docs/features/index.html @@ -2,7 +2,7 @@
Last updated Dec 13, 2022
Hilbish has a wide range of features to enhance the user’s experience and +
Last updated Dec 13, 2022
Hilbish has a wide range of features to enhance the user’s experience and is always adding new ones. If there is something missing here or something you would like to see, please start a discussion or comment on any existing ones which match your request.