Using files The calculator provides some functions which allow the program to read or write text files. These functions use stdio internally, and the functions appear similar to some of the stdio functions. Some differences do occur, as will be explained here. Names of files are subject to ~ expansion just like the C or Korn shell. For example, the file name: ~/.rc.cal refers to the file '.rc.cal' under your home directory. The file name: ~chongo/.rc.cal refers to the a file 'rc.cal' under the home directory of 'chongo'. A file can be opened for either reading, writing, or appending. To do this, the 'fopen' function is used, which accepts a filename and an open mode, both as strings. You use 'r' for reading, 'w' for writing, and 'a' for appending. For example, to open the file 'foo' for reading, the following could be used: fd = fopen('foo', 'r'); If the open is unsuccessful, the numeric value of errno is returned. If the open is successful, a value of type 'file' will be returned. You can use the 'isfile' function to test the return value to see if the open succeeded. You should assign the return value of fopen to a variable for later use. File values can be copied to more than one variable, and using any of the variables with the same file value will produce the same results. If you overwrite a variable containing a file value or don't save the result of an 'fopen', the opened file still remains open. Such 'lost' files can be recovered by using the 'files' function. This function either takes no arguments or else takes one integer argument. If no arguments are given, then 'files' returns the maximum number of opened files. If an argument is given, then the 'files' function uses it as an index into an internal table of open files, and returns a value referring to one the open files. If that entry in the table is not in use, then the null value is returned instead. Index 0 always refers to standard input, index 1 always refers to standard output, and index 2 always refers to standard error. These three files are already open by the calculator and cannot be closed. As an example of using 'files', if you wanted to assign a file value which is equivalent to stdout, you could use: stdout = files(1); The 'fclose' function is used to close a file which had been opened. When this is done, the file value associated with the file remains a file value, but appears 'closed', and cannot be used in further file-related calls (except fclose) without causing errors. This same action occurs to all copies of the file value. You do not need to explicitly close all the copies of a file value. The 'fclose' function returns the numeric value of errno if there had been an error using the file, or the null value if there was no error. File values can be printed. When this is done, the filename of the opened file is printed inside of quote marks. If the file value had been closed, then the null string is printed. If a file value is the result of a top-level expression, then in addition to the filename, the open mode, file position, and possible EOF, error, and closed status is also displayed. File values can be used inside of 'if' tests. When this is done, an opened file is TRUE, and a closed file is FALSE. As an example of this, the following loop will print the names of all the currently opened non-standard files with their indexes, and then close them: for (i = 3; i < files(); i++) { if (files(i)) { print i, files(i); fclose(files(i)); } } The functions to read from files are 'fgetline' and 'fgetc'. The 'fgetline' function accepts a file value, and returns the next input line from a file. The line is returned as a string value, and does not contain the end of line character. Empty lines return the null string. When the end of file is reached, fgetline returns the null value. (Note the distinction between a null string and a null value.) If the line contained a numeric value, then the 'eval' function can then be used to convert the string to a numeric value. Care should be used when doing this, however, since eval will generate an error if the string doesn't represent a valid expression. The 'fgetc' function returns the next character from a file as a single character string. It returns the null value when end of file is reached. The 'printf' and 'fprintf' functions are used to print results to a file (which could be stdout or stderr). The 'fprintf' function accepts a file variable, whereas the 'printf' function assumes the use of 'files(1)' (stdout). They both require a format string, which is used in almost the same way as in normal C. The differences come in the interpretation of values to be printed for various formats. Unlike in C, where an unmatched format type and value will cause problems, in the calculator nothing bad will happen. This is because the calculator knows the types of all values, and will handle them all reasonably. What this means is that you can (for example), always use %s or %d in your format strings, even if you are printing a non- string or non-numeric value. For example, the following is valid: printf("Two values are %d and %s\n", "fred", 4567); and will print "Two values are fred and 4567". Using particular format characters, however, is still useful if you wish to use width or precision arguments in the format, or if you wish to print numbers in a particular format. The following is a list of the possible numeric formats: %d print in currently defined numeric format %f print as floating point %e print as exponential %r print as decimal fractions %x print as hex fractions %o print as octal fractions %b print as binary fractions Note then, that using %d in the format makes the output configurable by using the 'config' function to change the output mode, whereas the other formats override the mode and force the output to be in the specified format. Using the precision argument will override the 'config' function to set the number of decimal places printed. For example: printf("The number is %.100f\n", 1/3); will print 100 decimal places no matter what the display configuration value is set to. The %s and %c formats are identical, and will print out the string representation of the value. In these cases, the precision argument will truncate the output the same way as in standard C. If a matrix or list is printed, then the output mode and precision affects the printing of each individual element. However, field widths are ignored since these values print using multiple lines. Field widths are also ignored if an object value prints on multiple lines. The final file-related functions are 'fflush', 'ferror', and 'feof'. The 'fflush' function forces buffered output to a file. The 'ferror' function returns nonzero if an error had occurred to a file. The 'feof' function returns nonzero if end of file has been reached while reading a file. The 'strprintf' function formats output similarly to 'printf', but the output is returned as a string value instead of being printed.