Bash and more generally shells are popular command-line and scripting languages that are widely used on Unix-like operating systems, including Linux and macOS. Nervetheless, it always happen to rewrite basic operations like split, trim... by ourself. Apash is a set of these operations by simplifying their interface. It's inspired from Apache's libraries realized in JAVA.
Note that even if it's a wish, Apash is not a project of the Apache Foundation.
Let's stop talking and open the shell !
StringUtils.rightPad "123" 6 "!"
# 123!!!- Installation
- Quick Start
- Features
- Documentation
- Container
- Compatibility
- Troubleshooting
- Maintenance
- License
- Explore the API (or with the Full Summary Table)
As other shell projects, unfortunately there is no standard way to install Apash. But below are the main ones.
Install curl and git to facilitate the installation. Adapt the command with your package manager
sudo apt install curl gitModify the URL in consequence if you want a particular version, here it's for the head of the main branch:
curl -s "https://raw.githubusercontent.com/hastec-fr/apash/refs/heads/main/utils/install.sh" | bashOpen a new terminal and check the apash version:
apash --version
# 0.1.0Basher is a package manager for bash which helps you to quickly install, uninstall and update bash packages from the command line (does not look compliant with "Git Bash").
curl -s "https://raw.githubusercontent.com/basherpm/basher/master/install.sh" | bashbasher install "hastec-fr/apash""$HOME/.basher/cellar/bin/apash" init --post-installClone or download the Apash project, execute the post installation action to add apash sourcing to your startup script file ($HOME/.bashrc).
git clone "https://github.com/hastec-fr/apash.git"
cd apash
# Post installation action:
apash init --post-install
# Then open a new terminal to ensure that environnment is re-loaded.Some prerequisite could be required if you want to contribute to the project. For Testing purpose, you need to install bats-core.
basher install "bats-core/bats-core"If you're using Git Bash, prefer the bast-core installation guide: Check out a copy of the Bats repository and install it to $HOME. This will place the bats executable in $HOME/bin, which should already be in $PATH.
git clone https://github.com/bats-core/bats-core.git
cd bats-core
./install.sh $HOMEFor Documentation purpose, you need to install shdoc.
basher install "reconquest/shdoc"Once Apash is installed, you can easily use the function by importing the package you desire by using command "import" with the name of the package.
# Java style to import all methods from StringUtils
apash.import "fr.hastec.apash.commons-lang.StringUtils"
StringUtils.substring "Hello World" 0 4Do you see the 🔥Hell🔥 ? It's just the beginning.
If it's not the case, lets have a look to the troubleshooting section.
# Import only a single method
apash.import "fr.hastec.apash.commons-lang.StringUtils.indexOf"
StringUtils.indexOf "Gooood Morning" "M"
# result: 7 (yes because it start from index 0 ^^)If you don't like this way of import, you can still use the bash source. But note that an import is done inside.
source fr/hastec/apash/commons-lang/StringUtils.shApash is auto documented using the project shdoc. Each file contains an header following the formalism of shdoc in order to generate the corresponding markdown file (.md) in the doc directory.
Let's explore the features !!
To generate the documentation, you need to install the tool shdoc (ref. dependencies). Once installed, generate the documentation from the root project directory with the main apash command.
apash docApash tests are realized with the tool bats-core (ref. dependencies). Once installed, launch the campaign of tests from the root project directory.
apash testYou can also override the bats options and choose specific tests as in this example:
# Prototype: apash test [-h] [--bats-options options] [--] [test paths]
apash test --bats-options "-t --print-output-on-failure" $APASH_HOME_DIR/test/bash/lang/Math/*.batsNote that bats options are in a single argument.
If you don't like the long name, you can create your own aliases (as usually).
alias import="apash.import"
alias trim="StringUtils.trim"Just keep in mind, that aliases are usefull for your prompt but (depending of the shell) they cannot be exported naturally. By example for bash, you should source again the alias from subscript or activate the shell option (on your own):
shopt -s expand_aliases
If you don't want to install apash but test it quickly, you can pull its container on docker hub
docker run --rm hastec/apash:0.1.0 '
apash.import "fr.hastec.apash.commons-lang.StringUtils"
StringUtils.reverse "Never odd or even!"
'Result:
!neve ro ddo reveN
If you don't like to import yourself the command, then use the image with all script pre-loaded:
docker run --rm hastec/apash:0.1.0-full 'StringUtils.upperCase "Please, speak louder !!"'Result:
PLEASE, SPEAK LOUDER !!
Finally, if you want to test a script, use the light or full image and mount the script as volume.
Take care to provide an absolute host path (not relative).
cat <<EOF > ./test.sh
apash.import "fr.hastec.apash.commons-lang.StringUtils.abbreviate"
StringUtils.abbreviate "Thanks to abbreviate this long description which does not lead anywhere except to pretend that this function could have a use case." 15
EOF
docker run --rm -v "$PWD/test.sh:/home/apash/test.sh:ro" hastec/apash:0.1.0 ./test.shResult:
Thanks to ab...
Use the default command of the container to get an interactive prompt.
docker run --rm -it hastec/apash:0.1.0
apash:bash-5.2 $ echo $BASH_VERSION
# 5.2.32(1)-releaseModify your apash installation and test non regression using containers.
# From root apash workspace directory ($APASH_HOME_DIR)
docker build -t docker.io/hastec/apash:0.1.0 -f ./docker/apash-bash.dockerfile .
docker run --rm hastec/apash:0.1.0 'apash test'A more complete list of compatibility will be dressed. Currently it has been tested for bash version 5.2 and require bc to be installed.
If you don't want to install apash but test it quickly, you can pull its container on docker hub
docker run --rm hastec/apash:0.1.0 '
apash.import "fr.hastec.apash.commons-lang.StringUtils"
StringUtils.reverse "Never odd or even!"
'Result:
!neve ro ddo reveN
If you don't like to import yourself the command, then use the image with all script pre-loaded:
docker run --rm hastec/apash:0.1.0-full 'StringUtils.upperCase "Please, speak louder !!"'Result:
PLEASE, SPEAK LOUDER !!
Finally, if you want to test a script, use the light or full image and mount the script as volume.
Take care to provide an absolute host path (not relative).
cat <<EOF > ./test.sh
apash.import "fr.hastec.apash.commons-lang.StringUtils.abbreviate"
StringUtils.abbreviate "Thanks to abbreviate this long description which does not lead anywhere except to pretend that this function could have a use case." 15
EOF
docker run --rm -v "$PWD/test.sh:/home/apash/test.sh:ro" hastec/apash:0.1.0 ./test.shResult:
Thanks to ab...
Use the default command of the container to get an interactive prompt.
docker run --rm -it hastec/apash:0.1.0
apash:bash-5.2 $ echo $BASH_VERSION
# 5.2.32(1)-releaseModify your apash installation and test non regression using containers.
# From root apash workspace directory ($APASH_HOME_DIR)
docker build -t docker.io/hastec/apash:0.1.0 -f ./docker/apash-bash.dockerfile .
docker run --rm hastec/apash:0.1.0 'apash test'A more complete list of compatibility will be dressed. Currently it has been tested for bash version 5.2.
The "apash.import" function replace "." from packages by "/" and allows to source all scripts from a directory. In addition, it prevents cycling import of re-loading librairies.
It's possible to force the unitary reload of a libraries.
# Reload libraries (Re-Source)
apash.import -f path.to.the.libraryDouble check that the bind mount has an absolute path (not a relative one which does not work everywhere)
# Example of issue:
docker run --rm -v "./test.sh:/home/apash/test.sh:ro" hastec/apash:0.1.0 ./test.sh
# bash: line 1: ./test.sh: Is a directory
# docker run --rm -v "/absolute/path/to/test.sh:/home/apash/test.sh:ro" hastec/apash:0.1. ./test.sh
# For pseudo relative path, you can use the $PWD variable
docker run --rm -v "$PWD/test.sh:/home/apash/test.sh:ro" hastec/apash:0.1. ./test.shWhen tests are ran with Git Bash, functions on dates are failing because Git bash does not look to handle natively Time zones.
If you're playing with days around the change of daylight saving, you could have some troubles. Please refer to the GNU core FAQ.
Some Apash Warnings could appears if you do not have a particular command (like "bc" or "rev"). In this case, another way is implemented but notify that the main way of work is not followed and so it is preferred to install the missing command. You can disabled these warning it by exporting the following variable.
export APASH_WARNING_DEGRADED="disabled"The lastest version from github is pulled.
basher upgrade hastec-fr/apash"$APASH_HOME_DIR/utils/uninstall.sh"It removes recursively the directory $APASH_HOME_DIR and lines in startup script (.bashrc).
basher uninstall hastec-fr/apashThen remove the lines with #apashInstallTag from your profile.
# Example:
sed -i '/apashInstallTag/d' "$HOME/.bashrc""$APASH_HOME_DIR/utils/uninstall.sh"Apash is a free and open-source software licensed under the Apache License Version 2.0 License. Please see the LICENSE.txt file for details.
