6. IO

1. Introduction

I am explaining IO of Sather in this section.
Sather has various functions of IO, which makes it easy to write practical applications.

2. Standard output, standard error output, and standard input

2.1. Standard output

As shown previously, the standard output is created by #OUT followed by the operator + and an object which has a method to convert into a string. Pears of + and object can be chained.
Example:

a:INT:=1;
b:INT:=2;
#OUT + a + " + " + b + " = " + (a+b) + "\n";    -- 1 + 2 = 3

2.2. Standard error output

It is created by #ERR. The property is same as that of standard output.

2.3. Standard input

It is created by #IN.
It has following methods.

Name	Return type	Explanation
eof	BOOL	It returns true at the end of the input.
get_char	INT	It reads one character and returns it as integer.
get_str	STR	It reads a string till it meets the end of line. The return value does not contain the LF character.

Example: A simple program that output the user input several times.

01:     -- a simple stdin -> stdout program
02:     
03:     class MAIN is
04:        main(av: ARRAY{STR}) is
05:           i:INT:=0;
06:           s:STR;
07:           loop
08:     	 #OUT + ">";
09:     	 s:=#IN.get_str;
10:     	 if s = "" then break!; end;
11:     	 #OUT + (s+" ").repeat(i+2) + "\n";
12:     	 i := (i+1)%4;
13:           end;
14:        end;
15:     end;  -- end of MAIN

takafumi@linux:~/doc/monthly/06-06/sather$ sacomp inout.sa -o inout
takafumi@linux:~/doc/monthly/06-06/sather$ ./inout
>hello
hello hello 
>how are you?
how are you? how are you? how are you? 
>enjoy!
enjoy! enjoy! enjoy! enjoy! 
>have a nice day!
have a nice day! have a nice day! have a nice day! have a nice day! have a nice day! 
>see you tomorrow.
see you tomorrow. see you tomorrow. 
>
takafumi@linux:~/doc/monthly/06-06/sather$

3. File input and output

Method about file input and output are defined in the class FILE. Following table shows frequently used methods.
See The Online Sather Code Browser for detailed information.

Table: Frequently used constructors and methods in the FILE class

Name Explanation

open_for_read(nm:STR):SAME It opens a file named nm to read.

open_for_write(nm:STR):SAME It opens a file named nm to write.

open_for_append(nm:STR):SAME It opens a file named nm to append.

temp_file:SAME It creates a temporary file to write. The file is deleted automatically when the program terminates.

stdin:SAME It opens a file as standard input.

stdout:SAME It opens a file as standard output.

stderr:SAME It opens a file as standard error output.

close It closes a file.

str:STR It returns the file contents as a string.

get_str:STR It reads one line (including LF) from the file.

get_char:CHAR It reads one character from the file.

plus (+) It writes an object to the file. You can write like fp + obj.

flush It flushes buffer to the file.

eof:BOOL The method returns true if it is the end of file.

error:BOOL If an error occurs, it returns true.

Name	Explanation
`open_for_read(nm:STR):SAME`	It opens a file named `nm` to read.
`open_for_write(nm:STR):SAME`	It opens a file named `nm` to write.
`open_for_append(nm:STR):SAME`	It opens a file named `nm` to append.
`temp_file:SAME`	It creates a temporary file to write. The file is deleted automatically when the program terminates.
`stdin:SAME`	It opens a file as standard input.
`stdout:SAME`	It opens a file as standard output.
`stderr:SAME`	It opens a file as standard error output.
`close`	It closes a file.
`str:STR`	It returns the file contents as a string.
`get_str:STR`	It reads one line (including LF) from the file.
`get_char:CHAR`	It reads one character from the file.
`plus (+)`	It writes an object to the file. You can write like `fp + obj`.
`flush`	It flushes buffer to the file.
`eof:BOOL`	The method returns true if it is the end of file.
`error:BOOL`	If an error occurs, it returns true.

Following shows a cp (scp.sa) and cat (scat.sa) programs written in Sather.

scp.sa

01:     -- scp.sa: a simple cp program written in sather
02:     
03:     class MAIN is
04:     
05:        main(av: ARRAY{STR}) is
06:           if (av.size = 3) then
07:     	 f0:FILE:=FILE::open_for_read(av[1]);       -- open av[1] as f0
08:     	 if f0.error then
09:     	    #ERR + "Can not open " + av[1] + "\n";  -- warn if fail
10:     	 else
11:     	    f1:FILE:=FILE::open_for_write(av[2]);
12:     	    f1 + f0.str;                            -- wrote contents of f0 to f1.
13:     	    f0.close;
14:     	    f1.close;
15:     	 end;
16:           else
17:     	 #ERR + "Usage: scp [from] [to]\n";
18:           end;
19:        end;
20:     end;  -- end of MAIN

scat.sa

01:     -- scat.sa: a simple cat program written in sather
02:     
03:     class MAIN is
04:     
05:        show_file_contents(f:FILE) 
06:           pre ~f.error
07:        is
08:           loop
09:     	 until!(f.eof);                    -- check if it reaches the end of file
10:     	 #OUT + f.get_str;                 -- getting one line
11:           end;
12:        end;
13:     
14:        main(av: ARRAY{STR}) is
15:           if (av.size = 1) then
16:     	 show_file_contents(FILE::stdin);
17:           else
18:     	 i:INT;
19:     	 f:FILE;
20:     	 loop
21:     	    i:=1.upto!(av.size-1);
22:     	    if av[i] ="-" then
23:     	       f:=FILE::stdin;
24:     	    else
25:     	       f:=FILE::open_for_read(av[i]);
26:     	    end;
27:     	    if f.error then
28:     	       #ERR + "Can not open " + av[i] + "\n";
29:     	       break!;
30:     	    else
31:     	       show_file_contents(f);
32:     	       f.close;
33:     	    end;
34:     	 end;
35:           end;
36:        end;
37:     end;  -- end of MAIN

4. Formating

Using the FMT class is most convenient, while several ways are available. This class takes a format string and objects and returns a formatted string. For the format string, you can use C language compatible way, as well as Sather's specific. Even you can mix them. The C compatible way is available, however, only for the STR, INT, and FLT classes.

#FMT formats up to 10 objects and convert it to a formatted string.
FMT::format(format_string:STR, objs:ARRAY{$FMT}) formats arbitrary number of objects that have the $FMT method.

See Formatting output with Sather for the Sather specific way.

Example:

01:     -- fmt.sa: a simple cp program written in sather
02:     
03:     class MAIN is
04:     
05:        main(av: ARRAY{STR}) is
06:           #OUT + #FMT("%d %06d %X %06X %x %o %06o\n", 255, 255, 255, 255, 255, 255, 255); -- up to ten items
07:     
08:           -- FMT::format takes ARRAY{$FMT} as the second argument
09:           -- sather and C format notation can be mixed
10:           #OUT + FMT::format("<>: %02d <> <#.#######e##>\n", |"hello", 1, 2.0, FLTD::pi|);  
11:        end;
12:     end;  -- end of MAIN

$ sacomp fmt.sa -o fmt
$ ./fmt
255 000255 FF 0000FF ff 377 000377
hello: 01 2.0 3.1415930e00

5. Summary

I have selected a simple way to explain IO of Sather as there are many ways, which may confuse you.
See The Online Sather Code Browser for detailed information.

I will explain about the Sather class system in detail in the following two sections.