Apash

Apache's Programs As SHell

👀 Introduction

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.

Disclaimer

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!!!

Table of contents

• Installation
• Quick Start
• Features
• Documentation
• Container
• Compatibility
• Troubleshooting
• Maintenance
• License
• Explore the API (or with the Full Summary Table)

📦 Installation

As other shell projects, unfortunately there is no standard way to install Apash. But below are the main ones.

Pre-requisites

Install curl and git to facilitate the installation. Adapt the command with your package manager

sudo apt install curl git

Intallation by Script

Modify 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" | bash

Open a new terminal and check the apash version:

apash --version
# 0.1.0

Installation with Basher

Basher 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").

Install Basher

curl -s "https://raw.githubusercontent.com/basherpm/basher/master/install.sh" | bash

Install Apash:

basher install "hastec-fr/apash"

Execute post installation action:

"$HOME/.basher/cellar/bin/apash" init --post-install

Raw Installation

Clone 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.

Dependencies

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 $HOME

For Documentation purpose, you need to install shdoc.

basher install "reconquest/shdoc"

[ ↑ Back to top ↑ ]

⚡️ Quick start

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 4

Do 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.sh

[ ↑ Back to top ↑ ]

📖 Documentation

Apash 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 doc

[ ↑ Back to top ↑ ]

🧪 Tests

Apash tests are realized with the tool bats-core (ref. dependencies). Once installed, launch the campaign of tests from the root project directory.

  apash test

You 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/*.bats

Note that bats options are in a single argument.

[ ↑ Back to top ↑ ]

✨ Tips

Naming

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

[ ↑ Back to top ↑ ]

🐳 Container

One shot

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.sh

Result:

Thanks to ab...

Interactive shell

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)-release

Non Regression

Modify 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'

[ ↑ Back to top ↑ ]

✅ Compatibility

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.

🐳 Container

One shot

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.sh

Result:

Thanks to ab...

Interactive shell

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)-release

Non Regression

Modify 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'

✅ Compatibility

A more complete list of compatibility will be dressed. Currently it has been tested for bash version 5.2.

❓ Troubleshooting

I have modified a library but it's not taken into account

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.library

I launch apash with a container but my script is seen as a directory

Double 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.sh

Dates issues

When 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.

Warnings appears

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"

[ ↑ Back to top ↑ ]

🛠 Maintenance

Upgrade

The lastest version from github is pulled.

Basher

basher upgrade hastec-fr/apash

Others

"$APASH_HOME_DIR/utils/uninstall.sh"

Uninstall

It removes recursively the directory $APASH_HOME_DIR and lines in startup script (.bashrc).

Basher

basher uninstall hastec-fr/apash

Then remove the lines with #apashInstallTag from your profile.

# Example:
sed -i '/apashInstallTag/d' "$HOME/.bashrc"

Others

"$APASH_HOME_DIR/utils/uninstall.sh"

📃 License

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.

[ ↑ Back to top ↑ ]