📦 Use standard libraries

🧩 Standard libraries

Valet comes with standard libraries that declare many useful functions to use in your commands and scripts.

To use a standard function, you need to source the library that declares it.

E.g. if you need string::getField and interactive::promptYesNo, do:

source string
source interactive

Alternatively, if you have several libraries to source, you can use the include command with a list of libraries:

include string interactive

All Valet functions are prefixed with the library name. E.g. the function string::getField is from the string library. A clear error message will be displayed if you are trying to use a library function without sourcing the library.

Important

The bash built-in source is overridden by a function in Valet. This allows to not source the same file twice, so you can safely call source mylib several times without impacting the runtime performance.

If you need to use the default source keyword, use builtin source.

👔 About library functions

The functions in Valet are implemented for a good compromise between performance and readability. They generally define clear local variables for the inputs as it makes the code more understandable. However, they do not implement input validation (beside checking if the mandatory arguments are given), it is your responsibility to ensure that the inputs are correct.

Functions return values using global variables (see performance tips and bash best practices for an explanation). Depending on the type and number of returned values, they will named as such:

${REPLY}
${REPLY2}
${REPLY3}
${REPLY_ARRAY[@]}
${REPLY_ARRAY2[@]}
${REPLY_ASSOCIATIVE_ARRAY[@]}

This ensures consistency across all functions. The trade off is that you must pay attention to how you use these variables. Calling two functions that are using the same REPLY will overwrite the value of the first function, so you will want to assign it to another variable because calling the second function.

Advanced syntax for REPLY assignment

When you want to set a returned value to a particular variable and want to avoid copying the returned value as such myVar="${REPLY}", you can use something like this:

declare MY_STRING='kebab-case' MY_OUTPUT
declare -n REPLY=MY_OUTPUT # make REPLY reference MY_OUTPUT
string::convertKebabCaseToCamelCase MY_STRING # the function writes to REPLY, which points to MY_OUTPUT
declare +n REPLY=value # we remove the reference and set another value
echo "MY_OUTPUT: ⌜${MY_OUTPUT}⌝" # will output 'kebabCase'
echo "REPLY: ⌜${REPLY}⌝" # will output 'value'

A lot of functions will accept options in addition to mandatory arguments. Options are passed using the shell parameter syntax option=value and must always come after any positional arguments.

E.g., to use the separator option of the string::getField function:

string::getField MY_STRING 1 separator=" "

For functions that accept a undetermined number of positional argument, options must be passed after the --- separator to differentiate them from the arguments:

curl::request https://example.com -X POST -H 'Authorization: token' --- failOnError=true

Note

The function documentation will always specify if the — separator is required. Assume that it is not required otherwise.

🪄 Using functions outside Valet

You can use Valet functions in your own scripts by sourcing the Valet library files. This allows you to leverage the powerful functions provided by Valet in your own bash scripts.

See this section in usage for more information.