📗 Create a library

🧑‍💻 Setup your development environment

The section working on bash will help you set up a coding environment for bash.

Open your existing extension directory or create a new one.

📄 Add a new library file

Run the following command to create a new library file named lib-mylib.sh in the libraries.d directory of your extension:

Replace mylib with the name of your command.

valet self add-library mylib

Alternatively, create the file manually.

🔤 Define new library functions

Each function that you want to expose as a library function must be named following the mylib::myfunction convention (where mylib is the name of your library, and myfunction the name of your function).

Moreover, each function must be commented with a strict format if you want Valet to auto document them and generate vscode snippets. Many illustrations can be found in the extras/lib-valet script or in the core library scripts.

You can define multiple functions in a single library file.

An example is given below for a mylib library and a myfunction function:

# ## mylib::myfunction
# 
# A description of my function.
#
# Can be done in multiple paragraph and should be formatted as **markdown**.
#
# The following argument descriptions should be formatted precisely in order to generate
# the correct vscode snippets.
# 
# - $1: **first argument** _as string_:
#       description of the first argument
# - $@: more args _as string_:
#       For functions that take an undetermined number of arguments, you can use $@.
# - ${myOption} _as bool_:
#       (optional) Description of the option.
#       This describes an optional parameter passed as a shell parameter (e.g. `myOption=true`).
#       (defaults to false)
# 
# Returns:
# 
# - $?: 0 if ok, 1 otherwise.
# - ${REPLY}: The first returned value
# - ${REPLY_ARRAY[@]}: A second returned value, as array
# 
# ```bash
# # Example of usage
# mylib::myfunction arg1 && echo "${REPLY}"
# nonPositional=10 mylib::myfunction arg1 optional_arg2 && echo "${REPLY}"
# ```
# 
# > A comment on this particular function.
function mylib::myfunction() { :; }

✒️ Implement your library

Please find these dedicated pages to help you write better bash functions:

🛠️ Rebuild the self documentation

Once defined, run the following command to let Valet find your custom libraries:

valet self build

Finally, you can use the following command to update your libraries documentation and vscode snippets:

valet self document

It will update the lib-valet script, the lib-valet.md documentation and the vscode snippets.

🧩 Source your new library

You can now source your new library in your command files with source mylib.