User Guide

1. Bash Command Builder (BcB) is a simple debugging tool. It does only minimal analysis of a script, not the full syntax analysis that more sophisticated tools might do. In your script, BcB inserts debugging information before each line that it thinks is debuggable. However, some lines are not debuggable and inserting debugging information there will cause errors. Therefore, it relies on you to flag certain portions of the script that it cannot debug.

If you run your script and see output like this:
bcbdebugger 27
you must flag some non-debuggable lines.

BcB recognizes simple cases of Here documents and multi-line strings such as those shown in Examples 1 and 2. Simple cases are handled without your intervention. However, it is likely you can dream up constructions that BcB cannot handle. In those cases you must manually mark lines as not debuggable as follows:

Example 1: Here documents
At the first line of a Here document, set Source to /*
At the last line, set Source to */
BcB will fill in the lines in between.

Example 2: multi-line string
At the second line, set Source to /*
At the last line, set Source to */

Also note that cramming multiple statements onto one line limits debugging ability. The case statements in Example 3 are more debuggable when written on multiple lines.

2. Line numbers reported at run time are not the same as line numbers at edit time. To translate between the two, hover your pointer over the Next column to see the runtime line number.

3. BcB creates temporary files in ~/.bcb. Normally they are deleted at program completion, but if they are not feel free to delete them yourself.

With that out of the way you can finally get started.


	Bash Command Builder makes Bash a little easier for writing, debugging, and executing single commands and short scripts. o Before you start o All about script files o Creating a script o Building a command o Transparent pipes o Debugging and running a script o Some notes
	Before you start - Please read this 1. Bash Command Builder (BcB) is a simple debugging tool. It does only minimal analysis of a script, not the full syntax analysis that more sophisticated tools might do. In your script, BcB inserts debugging information before each line that it thinks is debuggable. However, some lines are not debuggable and inserting debugging information there will cause errors. Therefore, it relies on you to flag certain portions of the script that it cannot debug. If you run your script and see output like this: bcbdebugger 27 you must flag some non-debuggable lines. BcB recognizes simple cases of Here documents and multi-line strings such as those shown in Examples 1 and 2. Simple cases are handled without your intervention. However, it is likely you can dream up constructions that BcB cannot handle. In those cases you must manually mark lines as not debuggable as follows: Example 1: Here documents At the first line of a Here document, set Source to /* At the last line, set Source to / BcB will fill in the lines in between. Example 2: multi-line string At the second line, set Source to / At the last line, set Source to */ Also note that cramming multiple statements onto one line limits debugging ability. The case statements in Example 3 are more debuggable when written on multiple lines. 2. Line numbers reported at run time are not the same as line numbers at edit time. To translate between the two, hover your pointer over the Next column to see the runtime line number. 3. BcB creates temporary files in ~/.bcb. Normally they are deleted at program completion, but if they are not feel free to delete them yourself. With that out of the way you can finally get started.
	All About Script Files Bash Command Builder works with files in pairs. One file (with extension .sh or no extension) is the usual script source file that you use with Bash. The other file (with extension .bcb) is the binary file you use with Bash Command Builder. When opening a script file, open the .bcb if it exists. When you save, both the .bcb and source file are updated.
	Creating a Script Press the "Open or Create" button. Navigate to folder of your choice. Type a script name (with .sh or no extension) or a binary name (with .bcb). Press "Open." You may then type your script into the Command column and specify Source and Destination. Press the "Save script files" button to "Save" or CTRL-click it to "Save as..." You never need to enter a "shebang" line; BcB will add it when the script is saved. The script columns: o Stop - Click to set a breakpoint. o Next - Shows the next line to be executed. o Source - The data source (pipe or Tpipe) or a non-debuggable flag. o Command - The bash command statement. o $ - A button to invoke the command builder. o Dest - The data destination (pipe or Tpipe) Drag the pointer to select rows. Right-click to insert or delete rows. Press the "Search and Replace" button to find a text string in your script. The search starts at the selected row and wraps around the table. Search is case insensitive. The search dialog contains "Replace" and "Replace All" buttons. You may replace one or all of the values found by search. Replace and Replace All are case sensitive.
	Building a Command For help composing a command, on a blank line or a line with a partial command, press the "$" button to open the command builder. Use the Category and Command drop-down menus to select a command. The bottom pane will show the full man page for the command. The top pane will show the command options, extracted from the man page. Check the boxes for the options you want. Enter command arguments into the "Arguments" field. Some complex commands require options and arguments in a particular order. In those cases, it may be simpler to type the options and arguments into the Arguments field. Press "Save" or "Save & Close" to write the command back to your script. Press "Close" to cancel.
	Transparent Pipes The pipe is a handy device for passing the output of one command to the input of another. The more clever among us can string a handful of operations into a pipeline creating a compact, efficient, and totally inscrutable command line. Here we recommend writing only one command per line and using the Source and Destination columns to specify pipe usage. Furthermore, you may specify TPipes, or transparent pipes, which show you the intermediate results of a piped operation. Consider the above examples. All four do exactly the same thing. The first two are not line-by-line debuggable. The third and fourth are line-by-line debuggable. The fourth uses a transparent pipe which displays the intermediate result on the Bash window. As you debug, you can step through each part of a piped operation and watch the contents of the pipe. Transparent pipes are converted to ordinary pipes when you save to a source file.
	Debugging and Running a Script Run and debug your script using the debugging buttons. o Run - Start script execution. o Pause - Suspend script execution. o Resume -Continue script execution from the current line. o Step - Execute the next line of the script. o Stop - Terminate execution of the script. Specify command line arguments in the "Command Line Arguments" panel. When the script is paused, you may view and change variables using the "Variables" panel. To change a variable, enter a new value and press Enter. View script output in the bash window that opens when you start script execution.
	Some Notes In case of internal error, Bash Command Builder creates a file named "bcb_log.txt" in your program folder or home folder. This may be useful when reporting errors to the author. Comments, suggestions, and defect reports are always welcome. Send email to dennis508@yahoo.com.