home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / program / funnel / writfile.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-10-23  |  11.1 KB  |  190 lines
  1. /*##############################################################################
  2.  
  3. FUNNNELWEB COPYRIGHT
  4. ====================
  5. FunnelWeb is a literate-programming macro preprocessor.
  6.  
  7. Copyright (C) 1992 Ross N. Williams.
  8.  
  9.    Ross N. Williams
  10.    ross@spam.adelaide.edu.au
  11.    16 Lerwick Avenue, Hazelwood Park 5066, Australia.
  12.  
  13. This program is free software; you can redistribute it and/or modify
  14. it under the terms of Version 2 of the GNU General Public License as
  15. published by the Free Software Foundation.
  16.  
  17. This program is distributed WITHOUT ANY WARRANTY; without even the implied
  18. warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  19. See Version 2 of the GNU General Public License for more details.
  20.  
  21. You should have received a copy of Version 2 of the GNU General Public
  22. License along with this program. If not, you can FTP the license from
  23. prep.ai.mit.edu/pub/gnu/COPYING-2 or write to the Free Software
  24. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25.  
  26. Section 2a of the license requires that all changes to this file be
  27. recorded prominently in this file. Please record all changes here.
  28.  
  29. Programmers:
  30.    RNW  Ross N. Williams  ross@spam.adelaide.edu.au
  31.  
  32. Changes:
  33.    07-May-1992  RNW  Program prepared for release under GNU GPL V2.
  34.  
  35. ##############################################################################*/
  36.  
  37.  
  38. /******************************************************************************/
  39. /*                                   WRITFILE.H                               */
  40. /******************************************************************************/
  41. /*                                                                            */
  42. /* Introduction                                                               */
  43. /* ------------                                                               */
  44. /* This package performs all of FunnelWeb's file output.                      */
  45. /* FunnelWeb performs lots of output to lots of different files:              */
  46. /*                                                                            */
  47. /*    - Standard output (to write to the screen).                             */
  48. /*    - The journal file.                                                     */
  49. /*    - The listing file.                                                     */
  50. /*    - The tangle output files.                                              */
  51. /*    - The weave output file.                                                */
  52. /*                                                                            */
  53. /* Error Detection                                                            */
  54. /* ---------------                                                            */
  55. /* As we are serious about detecting errors, every call to every IO function  */
  56. /* must have its status checked. Unfortunately this makes everything very     */
  57. /* messy. Having to check result statuses and react to them can be very       */
  58. /* awkward in deeply nested pieces of code, particularly as C does not have   */
  59. /* exceptions. As a result, the policy adopted in FunnelWeb is to RECORD when */
  60. /* an error occurs on an output stream and silently shut down that stream.    */
  61. /* Then later, at a convenient time, the error status of the stream can be    */
  62. /* checked, and an error message issued.                                      */
  63. /*                                                                            */
  64. /* The C libraries make an effort to be helpful here by providing the ferror  */
  65. /* function. However, it is not useful here for two reasons:                  */
  66. /*                                                                            */
  67. /*    1. Some calls (e.g. fwrite) are not listed as setting the error status. */
  68. /*    2. It is not guaranteed that IO calls to a stream with error status     */
  69. /*       will not cause a crash.                                              */
  70. /*    3. Even if ferror were used, it may not be supported by older compilers.*/
  71. /*                                                                            */
  72. /* This package was created to take care of the vexing problems of IO errors  */
  73. /* in output streams. It is a layer above the ANSI file library that provides */
  74. /* the elementary calls for writing. It differs in that if an error occurs,   */
  75. /* the package records that fact and simply ignores all further operations    */
  76. /* on the file. At any time, it is possible to find out whether a file is in  */
  77. /* normal mode or error mode. All this means that a piece of code can use     */
  78. /* this package to create and write to a file without worrying about errors.  */
  79. /* Then later, when the dust settles, the package can check the status  of    */
  80. /* the file, and take appropriate action if an error has been detected.       */
  81. /*                                                                            */
  82. /* Text vs Binary                                                             */
  83. /* --------------                                                             */
  84. /* This package translates all '\n' (contained in the data it has been given  */
  85. /* to write) into the appropriate environment specific representation.        */
  86. /*                                                                            */
  87. /* Facts About WF Objects                                                     */
  88. /* ----------------------                                                     */
  89. /* - A WF object is either in NORMAL or ERROR mode.                           */
  90. /* - A WF object in NORMAL mode is also either in OPEN or CLOSED mode.        */
  91. /* - The term "raise an error" means bomb the program with a message.         */
  92. /* - The comments attached to the functions given below are meant to be read  */
  93. /*   sequentially with each action or check being performed before the next.  */
  94. /* - This package can not guarantee to detect uninitialized WF objects. The   */
  95. /*   reason is that policing is performed using magic number mechanism and it */
  96. /*   is possible that a piece of random memory may contain just the right     */
  97. /*   numbers to fool the package.                                             */
  98. /*                                                                            */
  99. /******************************************************************************/
  100.  
  101. /* Ensure that the body of this header file is included at most once.         */
  102. #ifndef DONE_WRITFILE
  103. #define DONE_WRITFILE
  104.  
  105. /******************************************************************************/
  106.  
  107. #include "style.h"
  108.  
  109. /******************************************************************************/
  110.  
  111. /* We really don't want to show all the guts of this record here, but as      */
  112. /* users of the package have to be able to declare objects of this type and   */
  113. /* make them the right size, it seems as if we have no choice.                */
  114. typedef struct
  115.   {
  116.    ulong  wf_mhead;   /* Helps detect uninitialized and corrupted records.    */
  117.    bool   wf_iserr;   /* TRUE=>ERROR,   FALSE=>NORMAL.                        */
  118.    bool   wf_isope;   /* TRUE=>OPEN,    FALSE=>CLOSED.                        */
  119.    bool   wf_istxt;   /* TRUE=>TEXT,    FALSE=>BINARY.                        */
  120.    FILE  *wf_pfile;   /* Pointer to the file object.                          */
  121.    ulong  wf_mtail;   /* Helps detect uninitialized and  corrupted records.   */
  122.   } wf_t;
  123.  
  124. typedef wf_t *p_wf_t;
  125.  
  126. /******************************************************************************/
  127.  
  128. EXPORT void wf_ini P_((p_wf_t,bool));
  129. /* Initializes a WF to a well defined state in accordance with the boolean.   */
  130. /*    FALSE => State=(ERROR).                                                 */
  131. /*    TRUE  => State=(NORMAL,CLOSED).                                         */
  132. /* wf_ini must be applied to a WF before any other operation.                 */
  133. /* It can be re-applied repeatedly.                                           */
  134.  
  135. EXPORT void wf_att P_((p_wf_t,FILE *));
  136. /* If WF is uninitialized, raises an error (probably).                        */
  137. /* If WF is in ERROR mode, returns with no effect.                            */
  138. /* If WF is OPEN, raises an error.                                            */
  139. /* Attaches an already opened output file to the specified FW object.         */
  140. /* Changes the WF to the OPEN state.                                          */
  141. /* The memory that the second parameter points to must be stable.             */
  142.  
  143. EXPORT void wf_ope P_((p_wf_t,char *));
  144. /* If WF is uninitialized, raises an error (probably).                        */
  145. /* If WF is in ERROR mode, returns with no effect.                            */
  146. /* If WF is OPEN, raises an error.                                            */
  147. /* Creates an output file of the specified name and prepares it for writing.  */
  148. /* Changes the WF to the OPEN state.                                          */
  149. /* Sets the WF to the ERROR state if the file cannot be opened for writing.   */
  150.  
  151. EXPORT void wf_chr P_((p_wf_t,intchar));
  152. /* If WF is uninitialized, raises an error (probably).                        */
  153. /* If WF is in ERROR mode, returns with no effect.                            */
  154. /* If WF is CLOSED, raises an error.                                          */
  155. /* Writes the specified character to the output file associated with WF.      */
  156. /* Sets WF to the ERROR state if an error occurs during the write.            */
  157.  
  158. EXPORT void wf_wr P_((p_wf_t,char *));
  159. /* Same as wf_chr except that it writes an entire string.                     */
  160.  
  161. EXPORT void wf_wl P_((p_wf_t,char *));
  162. /* Same as wf_wr except that appends a '\n'.                                  */
  163.  
  164. EXPORT void wf_blk P_((p_wf_t,char *,size_t));
  165. /* Same as wf_wr but writes a block of bytes whose address is given by the    */
  166. /* second parameter and whose length (in bytes) is given by the third         */
  167. /* parameter.                                                                 */
  168.  
  169. EXPORT void wf_clo P_((p_wf_t));
  170. /* If WF is uninitialized, raises an error (probably).                        */
  171. /* If WF is in ERROR mode, returns with no effect.                            */
  172. /* If WF is CLOSED, raises an error.                                          */
  173. /* Flushes and closes the output file attached to WF.                         */
  174. /* Sets WF to the CLOSED state.                                               */
  175. /* Sets WF to the ERROR state if an error occurs during the close.            */
  176.  
  177. EXPORT bool wf_err P_((p_wf_t));
  178. /* If WF is uninitialized, raises an error (probably).                        */
  179. /* Returns TRUE iff WF is in the ERROR state, otherwise FALSE.                */
  180. /* This function can be called at any time so long as the WF is initialized.  */
  181.  
  182. /******************************************************************************/
  183.  
  184. /* For #ifndef preventing multiple inclusion of the body of this header file. */
  185. #endif
  186.  
  187. /******************************************************************************/
  188. /*                              End of WRITFILE.H                             */
  189. /******************************************************************************/
  190.