PageRenderTime 38ms CodeModel.GetById 11ms RepoModel.GetById 0ms app.codeStats 0ms

/trunk/Doc/Devel/file.html

#
HTML | 181 lines | 141 code | 40 blank | 0 comment | 0 complexity | 9ffcdf10c1e56738d226050fc67eba8c MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0 
    

  1. <html>
    2. 

  2. <head>
    3. 

  3. <title>SWIG File Handling</title>
    4. 

  4. </head>
    5. 

  5. 

  6. <body>
    7. 

  7. <center>
    8. 

  8. <h1>SWIG File Handling</h1>
    9. 

  9. 

  10. <p>
    11. 

  11. David M. Beazley <br>
    12. 

  12. dave-swig@dabeaz.com<br>
    13. 

  13. December, 2006<br>
    14. 

  14. 

  15. </b>
    16. 

  16. </center>
    17. 

  17. 

  18. <h2>Introduction</h2>
    19. 

  19. 

  20. This document describes the functions related to file and filename handling in the SWIG core.   These functions are
    21. 

  21. defined in the header file <tt>Source/Swig/swigfile.h</tt>.   This API is considered to be stable.
    22. 

  22. 

  23. <h2>File Search Path</h2>
    24. 

  24. 

  25. These functions manipulate the search path for locating files.
    26. 

  26. 

  27. <p>
    28. 

  28. <b><tt>List *Swig_add_directory(const String_or_char *dirname)</tt></b>
    29. 

  29. 

  30. <blockquote>
    31. 

  31. Adds a new directory to the system search path.  The directory is appended to
    32. 

  32. the end of the search path.  Returns a list containing the current
    33. 

  33. system search path. 
    34. 

  34. </blockquote>
    35. 

  35. 

  36. <p>
    37. 

  37. <b><tt>void Swig_push_directory(const String_or_char *dirname)</tt></b>
    38. 

  38. <blockquote>
    39. 

  39. Pushes a temporary directory onto the search path.  This directory is searched before 
    40. 

  40. directories added with <tt>Swig_add_directory()</tt> except when including a system
    41. 

  41. file explicitly (either using #include &lt;file&gt; or calling <tt>Swig_include_sys()</tt>).
    42. 

  42. This function is normally used by the preprocessor to add temporary directories when
    43. 

  43. processing #include statements.
    44. 

  44. </blockquote>
    45. 

  45. 

  46. <p>
    47. 

  47. <b><tt>void Swig_pop_directory()</tt></b>
    48. 

  48. <blockquote>
    49. 

  49. Pops off the last pushed directory with <tt>Swig_push_directory()</tt>
    50. 

  50. </blockquote>
    51. 

  51. 

  52. <p>
    53. 

  53. <b><tt>int Swig_get_push_dir()</tt></b>
    54. 

  54. 

  55. <blockquote>
    56. 

  56. Returns a flag that indicates whether directory pushing is enabled or not.
    57. 

  57. </blockquote>
    58. 

  58. 

  59. <p>
    60. 

  60. <b><tt>void Swig_set_push_dir(int dopush)</tt></b>
    61. 

  61. <blockquote>
    62. 

  62. Enables or disables directory pushing.  By default, it is turned on.  However, the <tt>-I-</tt> command line
    63. 

  63. option to SWIG disables it.
    64. 

  64. </blockquote>
    65. 

  65. 

  66. <p>
    67. 

  67. <b><tt>List *Swig_search_path()</tt></b>
    68. 

  68. <blockquote>
    69. 

  69. Returns the current search path.
    70. 

  70. </blockquote>
    71. 

  71. 

  72. 

  73. <h2>File access functions</h2>
    74. 

  74. 

  75. <p>
    76. 

  76. <b><tt>FILE *Swig_open(const String_or_char *name)</tt></b>
    77. 

  77. 

  78. <blockquote>
    79. 

  79. Opens a file, using the applicable search paths, and returns an open <tt>FILE *</tt> object if found.  Returns NULL if the file is not found.
    80. 

  80. </blockquote>
    81. 

  81. 

  82. <p>
    83. 

  83. <b><tt>String *Swig_read_file(FILE *f)</tt></b>
    84. 

  84. 

  85. <blockquote>
    86. 

  86. Reads all of the data from an open file into a string which is returned.
    87. 

  87. </blockquote>
    88. 

  88. 

  89. <p>
    90. 

  90. <b><tt>String *Swig_include(const String_or_char *name)</tt></b>
    91. 

  91. 

  92. <blockquote>
    93. 

  93. Searches for an include file <tt>name</tt> and returns its contents as
    94. 

  94. a string if found.  Returns NULL if not found.  All of the applicable
    95. 

  95. search paths are searched when trying to locate the file.
    96. 

  96. </blockquote>
    97. 

  97. 

  98. <p>
    99. 

  99. <b><tt>String *Swig_include_sys(const String_or_char *name)</tt></b>
    100. 

  100. 

  101. <blockquote>
    102. 

  102. Searches for an include file <tt>name</tt> and returns its contents as
    103. 

  103. a string if found.  Returns NULL if not found.  All of the applicable
    104. 

  104. search paths are searched when trying to locate the file, but
    105. 

  105. preference is given to system paths first. This mimics the behavior
    106. 

  106. of <tt>#include &lt;file&gt;</tt> in the preprocessor.
    107. 

  107. </blockquote>
    108. 

  108. 

  109. <p>
    110. 

  110. <b><tt>int Swig_insert_file(const String_or_char *name, File *outfile)</tt></b>
    111. 

  111. 

  112. <blockquote>
    113. 

  113. Searches for a file <tt>name</tt> and dumps its contents to <tt>outfile</tt> if found.
    114. 

  114. Returns 0 on success, -1 if the file couldn't be found.
    115. 

  115. </blockquote>
    116. 

  116. 

  117. <h2>Query functions</h2>
    118. 

  118. 

  119. <p>
    120. 

  120. <b><tt>String *Swig_last_file()</tt></b>
    121. 

  121. 

  122. <blockquote>
    123. 

  123. Returns the full pathname of the file last opened or included.
    124. 

  124. </blockquote>
    125. 

  125. 

  126. <h2>Named files</h2>
    127. 

  127. 

  128. <p>
    129. 

  129. <b><tt>void *Swig_register_filebyname(const String_or_char *filename, File *outfile)</tt></b>
    130. 

  130. 

  131. <blockquote>
    132. 

  132. Registers a file object <tt>outfile</tt> with a specific name <tt>filename</tt>.   This function is
    133. 

  133. used to implement the SWIG %insert directive and to manage different sections of the output
    134. 

  134. file such as "runtime","header","wrapper","init", etc.   Different language modules may add their own
    135. 

  135. sections for generating Python code, Perl code, etc.
    136. 

  136. </blockquote>
    137. 

  137. 

  138. <p>
    139. 

  139. <b><tt>File *Swig_filebyname(const String_or_char *filename)</tt></b>
    140. 

  140. <blockquote>
    141. 

  141. This looks up a file object previously registered using <tt>Swig_register_filebyname()</tt>.  This 
    142. 

  142. is used to implement the %insert directive.
    143. 

  143. </blockquote>
    144. 

  144. 

  145. <h2>Filename utilities</h2>
    146. 

  146. 

  147. <p>
    148. 

  148. <b><tt>char *Swig_file_suffix(const String_or_char *filename)</tt></b>
    149. 

  149. <blockquote>
    150. 

  150. Returns the suffix of a filename.  For instance, if the filename is "foo.txt", it returns ".txt".
    151. 

  151. </blockquote>
    152. 

  152. 

  153. <p>
    154. 

  154. <b><tt>char *Swig_file_basename(const String_or_char *filename)</tt></b>
    155. 

  155. <blockquote>
    156. 

  156. Returns the filename without the suffix attached to it.  For instance, if the filename is "foo.txt", it returns
    157. 

  157. "foo".  The result is stored in a static variable. If you need to save it, make your own copy.
    158. 

  158. </blockquote>
    159. 

  159. 

  160. <p>
    161. 

  161. <b><tt>char *Swig_file_filename(const String_or_char *filename)</tt></b>
    162. 

  162. <blockquote>
    163. 

  163. Returns the filename without any leading directories.  For instance, if the filename is "/bar/spam/foo.txt", it
    164. 

  164. returns "foo.txt".   This function is aware of local naming conventions on the machine (e.g., forward versus back slashes on Unix and Windows).   The result is stored in a static variable.  If you need to save the value, make a copy.
    165. 

  165. </blockquote>
    166. 

  166. 

  167. <p>
    168. 

  168. <b><tt>char *Swig_file_dirname(const String_or_char *filename)</tt></b>
    169. 

  169. <blockquote>
    170. 

  170. Returns the directory name (if any).  For instance, if the filename is "/bar/spam/foo.txt", it
    171. 

  171. returns "/bar/spam/".   This function is aware of local naming conventions on the machine (e.g., forward versus back slashes on Unix and Windows).  The result is stored in a static variable.  If you need to save the value, make a copy.
    172. 

  172. </blockquote>
    173. 

  173. 

  174. <p>
    175. 

  175. <b><tt>SWIG_FILE_DELIMITER</tt></b>
    176. 

  176. <blockquote>
    177. 

  177. This macro contains the file delimiter string for the local machine.  On Unix it is "/", on Windows it is "\\".
    178. 

  178. </blockquote>
    179. 

  179. 

  180. </body>
    181. 

  181. </html>
    182. 

  182.