c_cpp/etc/calc/help/file

   1 Using files
   2
   3     The calculator provides some functions which allow the program to
   4     read or write text files.  These functions use stdio internally,
   5     and the functions appear similar to some of the stdio functions.
   6     Some differences do occur, as will be explained here.
   7
   8     Names of files are subject to ~ expansion just like the C or
   9     Korn shell.  For example, the file name:
  10
  11             ~/.rc.cal
  12
  13     refers to the file '.rc.cal' under your home directory.  The
  14     file name:
  15
  16             ~chongo/.rc.cal
  17
  18     refers to the a file 'rc.cal' under the home directory of 'chongo'.
  19
  20     A file can be opened for either reading, writing, or appending.
  21     To do this, the 'fopen' function is used, which accepts a filename
  22     and an open mode, both as strings.  You use 'r' for reading, 'w'
  23     for writing, and 'a' for appending.  For example, to open the file
  24     'foo' for reading, the following could be used:
  25
  26             fd = fopen('foo', 'r');
  27
  28     If the open is unsuccessful, the numeric value of errno is returned.
  29     If the open is successful, a value of type 'file' will be returned.
  30     You can use the 'isfile' function to test the return value to see
  31     if the open succeeded.  You should assign the return value of fopen
  32     to a variable for later use.  File values can be copied to more than
  33     one variable, and using any of the variables with the same file value
  34     will produce the same results.
  35
  36     If you overwrite a variable containing a file value or don't save the
  37     result of an 'fopen', the opened file still remains open.  Such 'lost'
  38     files can be recovered by using the 'files' function.  This function
  39     either takes no arguments or else takes one integer argument.  If no
  40     arguments are given, then 'files' returns the maximum number of opened
  41     files.  If an argument is given, then the 'files' function uses it as
  42     an index into an internal table of open files, and returns a value
  43     referring to one the open files.  If that entry in the table is not
  44     in use, then the null value is returned instead.  Index 0 always
  45     refers to standard input, index 1 always refers to standard output,
  46     and index 2 always refers to standard error.  These three files are
  47     already open by the calculator and cannot be closed.  As an example
  48     of using 'files', if you wanted to assign a file value which is
  49     equivalent to stdout, you could use:
  50
  51             stdout = files(1);
  52
  53     The 'fclose' function is used to close a file which had been opened.
  54     When this is done, the file value associated with the file remains
  55     a file value, but appears 'closed', and cannot be used in further
  56     file-related calls (except fclose) without causing errors.  This same
  57     action occurs to all copies of the file value.  You do not need to
  58     explicitly close all the copies of a file value.  The 'fclose'
  59     function returns the numeric value of errno if there had been an
  60     error using the file, or the null value if there was no error.
  61
  62     The builtin 'strerror' can be use to convert an errno number into
  63     a slightly more meaningful error message:
  64
  65             badfile = fopen("not_a_file", "r");
  66             if (!isfile(badfile)) {
  67                 print "error #" : badfile : ":", strerror(badfile);
  68             }
  69
  70     File values can be printed.  When this is done, the filename of the
  71     opened file is printed inside of quote marks.  If the file value had
  72     been closed, then the null string is printed.  If a file value is the
  73     result of a top-level expression, then in addition to the filename,
  74     the open mode, file position, and possible EOF, error, and closed
  75     status is also displayed.
  76
  77     File values can be used inside of 'if' tests.  When this is done,
  78     an opened file is TRUE, and a closed file is FALSE.  As an example
  79     of this, the following loop will print the names of all the currently
  80     opened non-standard files with their indexes, and then close them:
  81
  82             for (i = 3; i < files(); i++) {
  83                     if (files(i)) {
  84                             print i, files(i);
  85                             fclose(files(i));
  86                     }
  87             }
  88
  89     The functions to read from files are 'fgetline' and 'fgetc'.
  90     The 'fgetline' function accepts a file value, and returns the next
  91     input line from a file.  The line is returned as a string value, and
  92     does not contain the end of line character.  Empty lines return the
  93     null string.  When the end of file is reached, fgetline returns the
  94     null value.  (Note the distinction between a null string and a null
  95     value.)  If the line contained a numeric value, then the 'eval'
  96     function can then be used to convert the string to a numeric value.
  97     Care should be used when doing this, however, since eval will
  98     generate an error if the string doesn't represent a valid expression.
  99     The 'fgetc' function returns the next character from a file as a
 100     single character string.  It returns the null value when end of file
 101     is reached.
 102
 103     The 'printf' and 'fprintf' functions are used to print results to a
 104     file (which could be stdout or stderr).  The 'fprintf' function
 105     accepts a file variable, whereas the 'printf' function assumes the
 106     use of 'files(1)' (stdout).  They both require a format string, which
 107     is used in almost the same way as in normal C.  The differences come
 108     in the interpretation of values to be printed for various formats.
 109     Unlike in C, where an unmatched format type and value will cause
 110     problems, in the calculator nothing bad will happen.  This is because
 111     the calculator knows the types of all values, and will handle them
 112     all reasonably.  What this means is that you can (for example), always
 113     use %s or %d in your format strings, even if you are printing a non-
 114     string or non-numeric value.  For example, the following is valid:
 115
 116             printf("Two values are %d and %s\n", "fred", 4567);
 117
 118     and will print "Two values are fred and 4567".
 119
 120     Using particular format characters, however, is still useful if
 121     you wish to use width or precision arguments in the format, or if
 122     you wish to print numbers in a particular format.  The following
 123     is a list of the possible numeric formats:
 124
 125             %d          print in currently defined numeric format
 126             %f          print as floating point
 127             %e          print as exponential
 128             %r          print as decimal fractions
 129             %x          print as hex fractions
 130             %o          print as octal fractions
 131             %b          print as binary fractions
 132
 133     Note then, that using %d in the format makes the output configurable
 134     by using the 'config' function to change the output mode, whereas
 135     the other formats override the mode and force the output to be in
 136     the specified format.
 137
 138     Using the precision argument will override the 'config' function
 139     to set the number of decimal places printed.  For example:
 140
 141             printf("The number is %.100f\n", 1/3);
 142
 143     will print 100 decimal places no matter what the display configuration
 144     value is set to.
 145
 146     The %s and %c formats are identical, and will print out the string
 147     representation of the value.  In these cases, the precision argument
 148     will truncate the output the same way as in standard C.
 149
 150     If a matrix or list is printed, then the output mode and precision
 151     affects the printing of each individual element.  However, field
 152     widths are ignored since these values print using multiple lines.
 153     Field widths are also ignored if an object value prints on multiple
 154     lines.
 155
 156     The functions 'fputc' and 'fputs' write a character and string to
 157     a file respectively.
 158
 159     The final file-related functions are 'fflush', 'ferror', and 'feof'.
 160     The 'fflush' function forces buffered output to a file.  The 'ferror'
 161     function returns nonzero if an error had occurred to a file.  The
 162     'feof' function returns nonzero if end of file has been reached
 163     while reading a file.
 164
 165     The 'strprintf' function formats output similarly to 'printf',
 166     but the output is returned as a string value instead of being
 167     printed.
 168
 169 ## Copyright (C) 1999-2006  Landon Curt Noll
 170 ##
 171 ## Calc is open software; you can redistribute it and/or modify it under
 172 ## the terms of the version 2.1 of the GNU Lesser General Public License
 173 ## as published by the Free Software Foundation.
 174 ##
 175 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 176 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 177 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 178 ## Public License for more details.
 179 ##
 180 ## A copy of version 2.1 of the GNU Lesser General Public License is
 181 ## distributed with calc under the filename COPYING-LGPL.  You should have
 182 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 183 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 184 ##
 185 ## @(#) $Revision: 30.1 $
 186 ## @(#) $Id: file,v 30.1 2007/03/16 11:10:42 chongo Exp $
 187 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/file,v $
 188 ##
 189 ## Under source code control:   1991/07/21 04:37:19
 190 ## File existed as early as:    1991
 191 ##
 192 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 193 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/