📗 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 command valet self add-library mylib 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.

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. 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: **argument name** _as type_:
#       The description of the first mandatory argument.
#
#       Can also be on multiple lines, be careful of the indentation.
# - $2: optional argument name _as string_:
#       (optional) This one is optional. It should not be emphasized (like the previous **argument name**).
#       (defaults to empty string)
# - $@: more args _as string_:
#       For functions that take an undetermined number of arguments, you can use $@.
# 
# Returns:
# 
# - $?: 0 if ok, 1 otherwise.
# - `RETURNED_VALUE`: The first returned value
# - `RETURNED_ARRAY`: A second returned value, as array
# 
# ```bash
# mylib::myfunction arg1 && echo "${RETURNED_VALUE}"
# mylib::myfunction arg1 optional_arg2 && echo "${RETURNED_VALUE}"
# ```
# 
# > A comment on this particular function.
function mylib::myfunction() { :; }

✒️ Implement your library

Implement the body of your function.

The following recommendations are given:

• Your function should only do one thing (i.e. it should be focused on a single task).
• Your function should be, as much as possible, self sufficient (i.e. it should not rely on global variables or other functions).
• You can use other exported functions (such as logging functions) but do not use other private functions.

🛠️ Rebuild the self documentation

Once defined, run valet self build to let Valet find your custom libraries. Finally, you can use valet self document to update your libraries documentation and vscode snippets.

It will update the lib-valet script, 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.