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 10195 2005-08-09 20:40:42Z raghavan $
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: