Module

October 3, 2024 ยท View on GitHub

one.bash uses modules to manage shell scripts.

User can use one commands to manage modules. Enable/Disable modules on your demand.

The modules types: alias, completion, plugin, bin, sub.

  • All plugins are put in plugin/ of each repo.
  • All completions are put in completion/ of each repo.
  • All aliases are put in alias/ of each repo.
  • All enabled modules are symbol linked in $ONE_DIR/enabled/ directory.
    • one enabled to view enabled modules.
    • one backup to backup enabled modules to a file.
  • Read one help <mod_type> for usages.
  • one <mod_type> enable to enable modules.
  • one <mod_type> disable to disable modules.
  • one <mod_type> list to list modules.

one.share has provided many modules, configs, ONE_SUB commands, and bin commands.

It's suggested to move your shell codes to modules.

PRIORITY

The modules are loaded by one.bash in order (from lower to higher based on PRIORITY).

This property is optional, each module has default priority.

The value of priority range of each module type:

  • plugin: 300~499, defaults to 400.
  • completion: 500~699, defaults to 600.
  • alias: 700~799, defaults to 750.

Enable module with variables

Some module may use environment variables as options. Such as one.share - zoxide:

ABOUT='https://github.com/ajeetdsouza/zoxide'
DEPS=zoxide
RUN_AND_APPEND() {
	zoxide init bash --cmd "${ZOXIDE_CMD:-z}" --hook pwd
}

User can change the default value by passing ZOXIDE_CMD=j. Like ZOXIDE_CMD=j one plugin enable zoxide

Write a module

All modules must be put in one of alias/completion/plugin/bin/sub folders.

Specifications of module.bash

The file content of module.bash:

about-plugin 'Module Description'
# ONE_LOAD_PRIORITY: 400

# Write your shellscript here
  • about-plugin 'Description': Description of module. It is optional
  • one-bash:mod:deps DEPS: To check commands in system when one <mod> enable and loading one.bash.
    • The DEPS is a string or an array which includes more command names. Such as DEPS=(awk sed)
  • # ONE_LOAD_PRIORITY: <PRIORITY>: Setting the loading priority. Put this line at the head of script.

See the examples in https://github.com/one-bash/one.share

Specifications of module.opt.bash

If a module need download files from remote. It's recommended to use module.opt.bash.

When one <mod> enable find the module.opt.bash, it will create a mod.bash file. And create a symbol-link pointed to mod.bash.

The final module will be: $ONE_DIR/enabled/priority---name@repo@type.bash -> $ONE_DIR/data/type/name/mod.bash

  • ABOUT='': Description of module. It is optional

  • PRIORITY=400: Priority of module. It is optional

  • GIT_REPO='https://github.com/user/repo.git': Git clone this repo. It is optional

  • SCRIPT='https://raw.githubusercontent.com/...': curl this file. It is optional

  • DEPS=(awk sed): To check commands in system when one <mod> enable. The DEPS is a string which includes one or more command names separated with spaces.

  • Hooks used in one <mod> enable are all optional.

    • BEFORE_ENABLE() {} This function is executed before AFTER_DOWNLOAD. Users can implement custom operations here.
    • AFTER_DOWNLOAD() {}: This function will be executed after files downloaded. User may use it to download the other requirements, compile and other things.
    • INSERT() {}: The function content will be inserted before module sciprt (source $SCRIPT).
    • RUN_AND_INSERT() {}: The function will be executed. And its stdout will be inserted before module sciprt (source $SCRIPT).
    • APPEND() {}: The function content will be inserted after module sciprt (source $SCRIPT).
    • RUN_AND_APPEND() {}: The function will be executed. And its stdout will be inserted after module sciprt (source $SCRIPT).

  • Hooks used in one <mod> disable are all optional.

    • BEFORE_DISABLE() {} User can implement custom actions here.

See the examples in https://github.com/one-bash/one.share

The content of generated mod.bash

# This file is generated by one.bash. Do not modify the file content.
# ABOUT: $ABOUT
one-bash:mod:deps $DEPS
$INSERT
$RUN_AND_INSERT()
source $SCRIPT
$APPEND
$RUN_AND_APPEND()

The steps when generating mod.bash

one.bash will auto execute below steps.

  1. check dependencies if DEPS or one-bash:mod:deps defined
  2. download files
  3. run AFTER_DOWNLOAD if defined
  4. copy INSERT if defined
  5. run and copy the stdout of RUN_AND_INSERT if defined
  6. copy APPEND if defined
  7. run and copy the stdout of RUN_AND_APPEND if defined

Download file via curl

SCRIPT=https://raw.githubusercontent.com/cheat/cheat/master/scripts/cheat.bash

The script will be downloaded to $ONE_DIR/data/type/name/script.bash.

Download GIT repo codes

GIT_REPO=https://github.com/lincheney/fzf-tab-completion
SCRIPT=bash/fzf-bash-completion.sh

GIT_REPO=https://gitlab.com/repo/user
SCRIPT=path/to/file

Optional Properties:

  • GIT_BRANCH: checkout to branch or tag

Download GITHUB release files

GIT_REPO=https://github.com/so-fancy/diff-so-fancy
GITHUB_RELEASE_VERSION=latest
GITHUB_RELEASE_FILES=(diff-so-fancy)
  • GITHUB_RELEASE_VERSION: It's optional. Defaults to latest.

Export bin file

GIT_REPO=https://github.com/wfxr/forgit
BIN=(bin/git-forgit)

Enable this moudule, will create symbol-link at $ONE_DIR/enabled/bin/