#+OPTIONS: f:nil
#+TODO: TODO(t) IN-PROGRESS(i) DONE(d)
* Introduction
The command line is awesome. Aliases are awesome. Talking to your
computer using natural language is also pretty awesome. With bam, you
can have it all :]

** What's in a name
BAM is an anagram. An anagram of an acronym. An /acranagram/, if you
will (/anacronym/ has a nice ring to it as well, but is already
[[http://en.wikipedia.org/wiki/Anacronym][taken]]). It stands for "Multi-word Aliases for Bash".

* Installation
... is easy!

** A home for bam
Choose a directory for bam to live in (note that for best performance
this should be a directory you have write access to) ...
#+BEGIN_EXAMPLE
$ cd /path/to/bams/new/home
#+END_EXAMPLE

... and bring them home:
#+BEGIN_EXAMPLE
$ git clone git://github.com/itsjeyd/bam.git
#+END_EXAMPLE

** Bam wakes up
After a long trip through the interwebs, bam might be napping. You
want to make sure that bam is awake and ready to start playing. Get
closer and give bam a gentle pat on the head:
#+BEGIN_EXAMPLE
$ cd bam
$ chmod +x bam.py
#+END_EXAMPLE

** A name for bam
Throughout your day you probably need to be in a lot of different
places. While you're working, you can't stay right by bam's side the
whole time. You want bam to respond to your calls even if you're far
away. That is what /names/ are for:
#+BEGIN_EXAMPLE
$ sudo ln -s ~+/bam.py /usr/bin/BAMS-NEW-NAME
#+END_EXAMPLE
You can name bam anything you like. For example, =BAMS-NEW-NAME= could
be =zed=, =mia=, or even =marcellus=.

** Bam gets ready
Almost there. The last thing left to do is for bam to unpack and
set up the toy box:
#+BEGIN_EXAMPLE
$ bam setup
#+END_EXAMPLE
Make sure you call bam by the name you chose in the previous step when
doing this.

There you go. Now it's time to start teaching bam some commands.

* Usage
** Adding new aliases
You can teach bam new commands by using the (SURPRISE!) =new= command:
#+BEGIN_EXAMPLE
$ bam new
#+END_EXAMPLE
bam will first prompt you for a command...
#+BEGIN_EXAMPLE
Enter command: ls -la
#+END_EXAMPLE
... and then for an alias to associate with the command:
#+BEGIN_EXAMPLE
Enter alias: list all the files
#+END_EXAMPLE
You can then run your new command using its alias like this:
#+BEGIN_EXAMPLE
$ bam list all the files
#+END_EXAMPLE

*** Wildcards
A lot of commands work on specific files or directories. It would be
tedious to have to add different aliases for the same command just
because its arguments are different. Consider for example a command
like
#+BEGIN_EXAMPLE
$ du -sh
#+END_EXAMPLE
which can be used to determine the size of specific files or folders.
Instead of adding multiple different aliases for running this command
on different targets, bam allows you to define a single alias using
one or more /wildcards/. Wildcards are integers surrounded by square
brackets:
#+BEGIN_EXAMPLE
$ bam new
Enter command: du -sh [0]
...
Enter alias: how big is [0]
BAM! "du -sh [0]" can now be run via "how big is [0]".
#+END_EXAMPLE
You can now use this alias to ask bam about the size of any file or
folder you like by simply inserting its name (or path) into the alias
at the position of the wildcard:
#+BEGIN_EXAMPLE
$ bam how big is /home/vincent/Documents
Running "du -sh /home/vincent/Documents" ...

2.2M	.
#+END_EXAMPLE
You can use as many wildcards as you like as long as their values
(i.e., the integers between the square brackets) are unique and match
up correctly between the alias and the underlying command.

You can't do this, for example:
#+BEGIN_EXAMPLE
$ bam new
Enter command: ls -l [0] | grep [0]
...
Enter alias: list all [0] files in [0]
#+END_EXAMPLE

The following would would work ...
#+BEGIN_EXAMPLE
$ bam new
Enter command: ls -l [0] | grep [1]
...
Enter alias: list all [0] files in [1]
#+END_EXAMPLE
... but it wouldn't yield the desired results:
#+BEGIN_EXAMPLE
$ bam list all py files in /home/jules/python-project
Running "ls -l py | grep /home/jules/python-project" ...

ls: cannot access py: No such file or directory
#+END_EXAMPLE

See the "Examples" section below for a working version of this alias, as
well as some more examples for aliases using wildcards.

** Listing aliases
You can use the =list= command to make bam show you a list of all your
commands and aliases:
#+BEGIN_EXAMPLE
$ bam list
#+END_EXAMPLE
See the "Examples" section below for an example of what the output of the
=list= command will look like.

** Deleting aliases
The =delete= command is used to selectively remove aliases from bam's
database:
#+BEGIN_EXAMPLE
$ bam delete
#+END_EXAMPLE
You will be prompted for the alias you want to delete. If you enter an
alias that doesn't exist in the database, bam will tell you. If the
alias does exist, bam will ask for confirmation before proceeding.

** Removing the database
If for whatever reason you want to get rid of all of your aliases at
once, you'll have to use the =destroy= command:
#+BEGIN_EXAMPLE
$ bam destroy
#+END_EXAMPLE

** Getting help
To get a listing of all basic commands bam responds to you can use the
=help= command:
#+BEGIN_EXAMPLE
$ bam help
#+END_EXAMPLE

* Examples
#+BEGIN_EXAMPLE
ID  COMMAND                          ALIAS
0   git push origin master           push it real good
1   cp -R * [0]                      copy all files to [0]
2   ls [0] | grep [1]                show me all [1] files in [0]
3   rm *~                            get rid of temp files
4   du -sh /var/cache/apt/archives/  how big is apt cache
5   chmod +x [0]                     make [0] executable
6   bam list                         show me my aliases
7   grep -lr [0] ./*                 list files containing [0]
#+END_EXAMPLE

* Credits
BAM was, among other things, inspired by Zach Holman's very cool [[https://github.com/holman/boom][boom]]
app.