Library Name: lib_shell.a
Introduction:

The shell library contains the classes that allow programs to interface with operating system (OS) functions. These functions allow user programs to use features of the OS in a consistent fashion without knowing the details of the OS.
The CommandLine class enables access to the parameters on the command line.
The DebugLevel class provides a means of dubugging at predefined debug levels defined in Integral.h
The Filename class allows the user to create unique temporary file names, and to use and manipulate file names in a systematic fashion.
The Sdb (Signal data base) class provides a means of managing signal files and Sdb files. For a given filename, this function will test to see if the file is an Sof file containing an Sdb object. if it is, then the data will be read and each entry in this list will be inserted in place of the given filename. If it is not such a file list, the file itself will be inserted in the list.

Example:

Here is a basic example to introduce some of the methods for CommandLine and Filename:

           01  // isip include files
           02  //
           03  #include <CommandLine.h>
           04  #include <Filename.h>
           05  #include <String.h>
           06  #include <File.h>
           07
           08  // main program starts here
           09  //
           10  int main (int argc, const char **argv) {
           11
           12    // create command line
           13    //
           14    CommandLine cmdl;
           15
           16    // set help message
           17    //
           18    cmdl.setHelp(
           19    #include "helpmessage.text"
           20    );
           21
           22    // parse the command line
           23    //
           24    cmdl.parse(argc, argv);
           25
           26    // checks the number of arguments on the command line
           27    //
           28    if (cmdl.numArguments() != 3) {
           29        Console::put(L"you must specify a filename and two strings");
           30        cmdl.printUsage();
           31    }
           32
           33    // get file name
           34    //
           35    String old_filename;
           36    cmdl.getArgument(old_filename, 0);
           37
           38    // get two strings
           39    //
           40    String replacethis;
           41    String replacewith;
           42    cmdl.getArgument(replacethis, 1);
           43    cmdl.getArgument(replacewith, 2);
           44
           45    Filename filename;
           46    filename.assign(old_filename);
           47
           48    // replace the file name
           49    //
           50    filename.replace(replacethis, replacewith);
           51
           52    // changes the filename in the directory
           53    //
           54    File file;
           55    file.rename(old_filename, filename);
           56
           57    // exit gracefully
           58    //
           59    Integral::exit();
           60  }

Explanation:

Lines 3 through 6 contain the ISIP class definitions. The main program starts on line 10 with the main function definition.
On line 14, we create an instance of CommandLine. On line 18 we use the setHelp method of CommandLine to establish a help message ( -help option). This help message is in the file "helpmessage.text". Line 24 parses the CommandLine. Lines 28 through 31 check the arguments submitted on the command line. If the -help option is selected, the contents of helpmessage.text will print to the screen due to line 30. For example:

      isip20_[1]: example1.exe -help
      name: example1
      synopsis: example1 file1 string1 string2
      descr: string1 is present in file1; string2 replaces string1
      example: example1.exe filea.text a a_00

      options: none

      arguments: filename1, string1, string2

      man page: none

If there is an incorrect number of arguments on the commandline and -help is not present, an error message will be printed because of line 29. For example:

      isip20_[1]: example1.exe filea.text a
      you must specify a filename and two strings

      specify the -help option for more information

Line 35 declares a String to store the first argument on the CommandLine. The CommandLine method getArgument is used on line 36 to retrieve the name of the file and store it in the String old_filename. The same procedure is used on lines 40 through 43 to get the other two arguments (the string to be replaced and the string that will replace). An instance of Filename is created on line 45 and it is initialized to the original file name on line 46 using the assign method that is standard in ISIP classes.
The replace method in Filename takes two Strings as arguments and replaces the first string with the second in its Filename object. When the first String is found, the method replaces the first String with the second String. This method is implemented in this example program on line 50. It should be noted that this alone does not change the actual file's name. This only changes the Filename variable. To actually change the file's name, we must use the File class's method rename as on line 55.
An example call to the program:

      isip20_[1]: ls
      GNUmakefile       example1.exe      filea.text
      example1.cc       example1.o        helpmessage.text

      isip20_[1]: example1.exe filea.text a a_00

      isip20_[1]: ls
      GNUmakefile       example1.exe      filea_00.text
      example1.cc       example1.o        helpmessage.text

The result is filea.text is now filea_00.text.
It should be noted that if there are two occurances of the second string, by default, only the last occurance will be replaced. For example:

      isip20_[1]: ls
      GNUmakefile       example1.cc       example1.o
      afilea.text       example1.exe      helpmessage.text

      isip20_[1]: example1.exe afilea.text a a_00

      isip20_[1]: ls
      GNUmakefile       example1.cc       example1.o
      afilea_00.text    example1.exe      helpmessage.text

The file afilea.text is now afilea_00.text.

Example:

The next example uses Sdb to create a list of Sof files and prints the Sof information of each file to the terminal. The file names are passed as arguments in the command line. For example,

      isip20_[1]: example1.exe file1.sof file2.sof file3.sof

will print the Sof information for file1, file2, and file3.

        01	// file: $isip/doc/examples/class/shell/shell_example_01/example.cc
        02	// version: $Id: index.html 10653 2007-02-24 20:33:16Z tm334 $
        03	//
        04
        05	// this is a simple utility that displays information about sof
        06	// files. it demonstrates the basic usage of Sdb and CommandLine.
        07	//
        08
        09	// isip include files
        10	//
        11	#include <Sof.h>
        12	#include <CommandLine.h>
        13	#include <Sdb.h>
        14
        15	// main program starts here
        16	//
        17	int main(int argc, const char **argv) {
        18
        19	  // parse the command line and connect it to an Sdb object. this
        20	  // tells Sdb that all arguments on the command line are files for
        21	  // Sdb to iterate through.
        22	  //
        23	  Sdb sdb1;
        24	  CommandLine cmdl(sdb1);
        25	  cmdl.parse(argc, argv);
        26
        27	  // loop over all files in the Sdb object. the call to gotoFirst will
        28	  // return true if there is at least one file to "go" to, false if it
        29	  // is an empty list. the gotoNext call will return true if the
        30	  // current position is not the last file in the list.
        31	  //
        32	  for (boolean file = sdb1.gotoFirst(); file; file = sdb1.gotoNext()) {
        33
        34	    Sof sof1;
        35	    Filename filename;
        36
        37	    // open file in read-only mode
        38	    //
        39	    sdb1.getName(filename);
        40	    if (!sof1.open(filename, File::READ_ONLY)) {
        41	      return Error::handle(sof1.name(), L"open",
        42				   Error::TEST, __FILE__, __LINE__);
        43	    }
        44
        45	    // output information about the file to the Console
        46	    //
        47	    sof1.debug(L"This is the sof file ");
        48	    Console::put(L"\n");
        49
        50	    // close the file
        51	    //
        52	    sof1.close();
        53	  }
        54
        55	  // exit gracefully
        56	  //
        57	  Integral::exit();
        58	}

Explanation:

We include the ISIP class definitions on lines 11 through 13. The main program starts on line 17 with the main function definition.
On line 23, we create an instance of Sdb on line 24, we create an instance of CommandLine. Our Sdb object is linked to cmdl (the CommandLine object) through the constructor. On line 25, the CommandLine. The result of the code on lines 23 through 25 is a Sdb object full of the files supplied by the user on the command line.
We now iterate over the names held by the Sdb object with a for loop as specified on line 32. On line 39 we extract the current name from the Sdb object into a temporary filename object. On line 40 we open this filename with an Sof object. The call to open will return false if the file open fails or if the file is not an Sof file, hence we can error. Assuming it is an Sof file, we call the Sof debug method on line 47 to dump the file's information (table of objects and sizes) to the Console.
The command:

      isip20_[1]: example.exe graph_bin.sof graph_text.sof >output1.text

will yield the output in the file output1.text. (The output is not the file itself but the Sof information for the file printed with the debug method.) Note that these files are not lists and both are added to the DoubleLinkedList. Their information is separated by a blank line.
The file file.sof is a list:

      isip20_[1]: cat file.sof
      @ Sof v1.0 @
      @ Sdb 0 @
      graph_text.sof
      graph_bin.sof

and when you give the command:

      isip20_[1]: example.exe trans_text.sof -l file.sof > output2.text

You will get the results in output2.text. The file output1.text contains three files' information: trans_text.sof, graph_bin.sof, and graph_text.sof, , as expected. Note that the -l flag tells Sdb to expand file.sof as a file list instead of processing it as a plain file. Without the -l flag you would get two file's worth of information, the second would report as holding a single Sdb object.
This program and some example Sof files can be found in our documentation directory under class/shell/.
The following classes belong to shell:

CommandLine | DebugLevel | Filename | Sdb