Home - jmadison222/jamaratus GitHub Wiki

1. Installation

On a robust system, you might have all the system dependencies in place, so let’s just jump right in. If it doesn’t work by jumping right in, see the System Dependencies section below.

1.1. Expert Install

This project is just a bunch of scripts. If you’ve been doing Linux for a while, you know how this goes. Do the following in whatever fashion you prefer for external scripting libraries like this one:

Copy everything from the scripts directory to some directory in your path.
Point JAMARATUS_HOME at that location, either manually, or in .bashrc, or in .bash_profile.
Do . jamaratus to source the scripts either into your interactive session or your own scripts.

1.2. Beginner Install

If the expert install seems vague, do the following steps and it will work. The following steps dictate the outcome, but it keeps it simple for you, so do the following:

cd $HOME
git clone https://github.com/jmadison222/jamaratus.git
echo 'export JAMARATUS_HOME="$HOME/jamaratus/scripts"' >> .bash_profile
echo 'export PATH=$JAMARATUS_HOME:$PATH' >> .bash_profile
echo '. jamaratus' >> .bash_profile

Exit your session and start a new one. It will pick up the variables and bring all the JamAratus commands into your session.

If you need the JamAratus functions in a script, put the following line in the script, at or toward the top:

. jamaratus

1.3. Installation Testing

Run the following commands in the fresh session to see if everything is working.

Run clr. This is the color management command. You should get the following output:

222900815 1e14f424 c44a 47a2 a61e d7c1d4be1695

If this doesn’t work, see the System Dependencies section below. If it did work, you probably have all the right bash and terminal dependencies in place.

Run dfx. This is the extended version of df. You should get something like the following output:

223306154 82764926 bfaa 4028 a583 6925184b3ccf

If this doesn’t work, see the System Dependencies section below. If it did work, you probably have all the right Python dependencies in place.

2. Commands

The full list of commands is shown. Click the link to see the help text and other information about the command.

Command	Nature	Coolness	Description
action	Script	Low	Print text in the color that tells the user to take an action.
announce	Script	Low	Print the file header of the script that calls this function.
aspect	Script	Utility	Manage the aspects that are common to functions.
bail	Prompt	High	Generate kill statements for all processes but the current terminal.
cache	Script	High	Manage cache files across other components.
clr	Script	Medium	Colorize text, either the whole line, or within a line.
confirm	Script	Medium	Return 0 or 1 based on user confirmation.
crypto	Demo	High	Encode and decode using various cryptography and encoding tools.
datafile
dfx	Prompt	Low	The 'df' command with a more readable format.
dir	Prompt	Low	List directory contents with common filters and sort orders.
dock
evalx	Script	High	The 'eval' wrapper, mostly to echo the command first.
firewall
g
grepx	Prompt	Low	Make using grep faster, easier, and vividly colorized.
jams	Prompt	Low	List the commands of the JamAratus system and their descriptions.
g	Prompt	Medium	The 'git' wrapper.
krb	Prompt	Low	Manage Kerberos. (kinit, klist, kdestroy)
line1	Script	Medium	Print a line the width of the screen and an optional message.
line2	Script	Low	Print a short line and optional message after the 'line1' command.
popdx	Script	Low	The 'popd' wrapper, mostly to hide the echo to stdout.
ports
prompt	Prompt	High	Run some other function in prompt mode.
pushdx	Script	Low	The 'pushd' wrapper, mostly to hide the echo to stdout.
pyx	Prompt	Low	Program in a popular language that was designed for the masses.
readonlyx	Both	Low	Make a variable writable that had been set to read-only.
s3	Both	High	Manage S3 on AWS.
scr	Prompt	High	Manage screen preferences, such as size and line wrap.
snow	Both	Medium	Manage Snowflake, the cloud-based relational database.
to	Prompt	High	Move to directory locations based on cached names.
usage	Script	Low	Print P1 in the 'usage' message format.
watchx

The 'help' Parameter - Each command has 'help' as a reserved argument to its first parameter, such as "evalx help". Run any command with 'help' to see how it works.

3. System Dependencies

If the commands don’t work, there may be missing system dependencies or settings. The dependencies are listed in descending order of likelihood of being an issue.

Bash - Use the Bash shell. Other shells are on the roadmap, but currently Bash is the only supported shell.
Python3 - The python3 command must be on your system. It does not need to be a particularly recent version.
TERM=xterm - Set the TERM varaible to xterm. This is needed for the colors and line drawing to work.
rlwrap - This command must be present for the prompt command to function fully. The prompt will still work, but it won’t have history. The prompt command is one of the slicker but more obscure aspects of the system, so you may or may not care.
120 screen width - Commands may take the liberty of going up to 120 characters wide. Most commands try to stay within 80.

4. Customizations

Naming conflicts - If the name of any JamAratus command conflicts with another command in your system, go into the _*.sh file with the corresponding name, and on the fourth line of the script, rename the function. It’s up to you if you want to rename the file itself—that doesn’t matter.

5. Design Decisions

Tradeoffs are the essence of design. Some design choices were made that impact the user experience, your ability to customize these scripts, the maintainability of them over time, and so on. These tradeoffs are discussed here.

Positional Reserved-Word Parameters - All commands work on positional parameters, and it is common, particularly for the first parameter, to use common words. The strength of this approach is that in 99+% of cases, this allows thinking and typing to be simple and fast. That simplicity and speed contributes heavily to the core intent of this system to increase your personal efficiency. The happily accepted weakness of this design is that in a small percentage of cases, you might have wanted those words for yourself. You’re asked to give that up and figure out a work around. For example, if you wanted to use the "line1" command with "help" as your literal banner, and you did "line1 help", you wouldn’t get the banner, you’d get the help screen. Or if you wanted to use "dir" for a file you call "time", you’d instead get a directory listing in order of time. In both those cases, and other rare ones like that, you’d have to find some other thing to do. Usually, it’s not to hard. And such cases are so very rare that we accept them for the huge up-side of having fast, simple parameters to the command library.

6. About the Name

To jam is to play musical instruments with great intensity. An apparatus is the technical equipment and instruments needed for a particular activity or purpose. Jamaratus is a collection of Linux shell utilities that make your command line rock! JAM is also the initials of the original author of this system, so some reverse engineering is at play!