libbash: libbash

# libbash

Version:
  0.9.10b ChangeLog

Author:
  Hai Zaar
  Gil Ran

Date:
  June 08, 2008

License
  GPL version 2

Quick jump
  - General
  - Using libbash
  - Installing
  - FAQ
  - Further reading

## General

`libbash` is a tool that enables bash dynamic-like shared libraries.

### What is libbbash?

Actually its a tool for managing bash scripts that contain functions you may want to use in various scripts.

To achieve its goal, it uses some kind of "dynamic loader" that you call to load desired bash library (actually just to `source` bash code).

### Why libbash?

In short - code reuse. That seems to be the problem of many bash programmers. The bash lacks any built-in method of separating code into libraries.

Suppose you've written some great bash script. You've surelly splitted it to some functions that do parameter parsing, etc... Now you want to reuse that code in some other script. What do you do? The general solution is to cut out that reusable code from your first script, put it in separate file, and then `source` it from both scripts.

Well, this may work fine, but what if your two scripts are completely unrelated and, in fact, belong to completely different projects, that do not share any common files. So you need to keep a copy of that reusable code in each project, and ... down we go...

The libbash was born to address the above problem. It may be seen as script organizer. It holds "reusable code" in centralized place (typically `/lib/bash/`). Then you can use it to check what libraries are available, what functions they provide and actually source desired code.

### More information

- libbash FAQ
- Available libraries

## Using libbash

### Minimal survival guide

First, list bash libraries available on your system

    #> ldbash -l
    Libraries:
    	getopts
    	hashstash

Well, if it does not tell you much, run `man` `getopts` for example. When you've decided to go with getopts, you run

    #> ldbash -e getopts
    External:
            getopts:
                    getopt_long

The above means that `getopts` library provides `getopt_long` function (use `man` to find out what it does and how to use it).

From now on can start writing your script that uses `getopt_long`. The question you ask now is: "How do I load that function to my script?" The aswer is very simple. Consider:

    #> ldbash -L getopts
    source /usr/lib/bash/getopts.sh; source /usr/lib/bash/hashstash.sh;

So all you need to do in your script is to add the following line:

    eval `ldbash -L getopts`

Note:
  You may noticed that you are actually sourcing two files: `getopts.sh` and some mysterous `hashstash.sh`. The reason is that getopts reported that it requires hashstash and libbash tracked that request and fulfilled it.

### Synopsys

`ldbash` ``[`-h` ``| `--help`]
  Show help message.

`ldbash` ``[`-l` ``| `--list`]
  List available libraries.

`ldbash` ``[`-L` ``| `--load` `lib`,``[`lib``]` ``...]
  Load library.
  Actually, it gives you a string that should be evaled (using eval (1)). After running eval(1) you will be able to use the library's functions.

`ldbash` ``[`-U` ``| `--unload` `lib`,``[`lib``]` ``...]
  Unload a library. Actually, it gives you a string that should be evaled (using eval (1)). After running eval(1) the library's functions will no longer be usable.

`ldbash` ``[`-e` ``| `--externlist` `lib`,``[`lib``]` ``...]
  List all the functions that a specific library exports.

`ldbash` ``[`--externlist-all`]
  List all the functions that listed libraries export.

`ldbash` ``[`--i` ``| `--internlist` `lib`,``[`lib``]` ``...]
  List all the functions that are defined in a specific library, but are not exported.

`ldbash` ``[`--internlist-all`]
  List all the functions that are defined in a listed library, but are not exported.

## Installing libbash

### Requirements

Actually, you need nothing except of bash. On the other hand, some (third party) libraries can use additional tools, that may not be available on your system. Anyway currently, there are none.

`libbash` was tested in bash 3.x. It may also work with 2.0x versions, but this is 'not supported' :)

Although you will need Doxygen to generate html documentation (the one you are reading at this moment).

## Further reading

- How to create and install your own libraries
- ldbash - Dynamic loader for libbash libraries.
  - man page
- ldbashconfig - Creates or updates cache file for libbash libraries.
  - man page