PageRenderTime 23ms CodeModel.GetById 6ms app.highlight 10ms RepoModel.GetById 2ms app.codeStats 0ms

/trunk/Doc/Devel/file.html

#
HTML | 181 lines | 141 code | 40 blank | 0 comment | 0 complexity | 9ffcdf10c1e56738d226050fc67eba8c MD5 | raw file
  1<html>
  2<head>
  3<title>SWIG File Handling</title>
  4</head>
  5
  6<body>
  7<center>
  8<h1>SWIG File Handling</h1>
  9
 10<p>
 11David M. Beazley <br>
 12dave-swig@dabeaz.com<br>
 13December, 2006<br>
 14
 15</b>
 16</center>
 17
 18<h2>Introduction</h2>
 19
 20This document describes the functions related to file and filename handling in the SWIG core.   These functions are
 21defined in the header file <tt>Source/Swig/swigfile.h</tt>.   This API is considered to be stable.
 22
 23<h2>File Search Path</h2>
 24
 25These functions manipulate the search path for locating files.
 26
 27<p>
 28<b><tt>List *Swig_add_directory(const String_or_char *dirname)</tt></b>
 29
 30<blockquote>
 31Adds a new directory to the system search path.  The directory is appended to
 32the end of the search path.  Returns a list containing the current
 33system search path. 
 34</blockquote>
 35
 36<p>
 37<b><tt>void Swig_push_directory(const String_or_char *dirname)</tt></b>
 38<blockquote>
 39Pushes a temporary directory onto the search path.  This directory is searched before 
 40directories added with <tt>Swig_add_directory()</tt> except when including a system
 41file explicitly (either using #include &lt;file&gt; or calling <tt>Swig_include_sys()</tt>).
 42This function is normally used by the preprocessor to add temporary directories when
 43processing #include statements.
 44</blockquote>
 45
 46<p>
 47<b><tt>void Swig_pop_directory()</tt></b>
 48<blockquote>
 49Pops off the last pushed directory with <tt>Swig_push_directory()</tt>
 50</blockquote>
 51
 52<p>
 53<b><tt>int Swig_get_push_dir()</tt></b>
 54
 55<blockquote>
 56Returns a flag that indicates whether directory pushing is enabled or not.
 57</blockquote>
 58
 59<p>
 60<b><tt>void Swig_set_push_dir(int dopush)</tt></b>
 61<blockquote>
 62Enables or disables directory pushing.  By default, it is turned on.  However, the <tt>-I-</tt> command line
 63option to SWIG disables it.
 64</blockquote>
 65
 66<p>
 67<b><tt>List *Swig_search_path()</tt></b>
 68<blockquote>
 69Returns the current search path.
 70</blockquote>
 71
 72
 73<h2>File access functions</h2>
 74
 75<p>
 76<b><tt>FILE *Swig_open(const String_or_char *name)</tt></b>
 77
 78<blockquote>
 79Opens 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</blockquote>
 81
 82<p>
 83<b><tt>String *Swig_read_file(FILE *f)</tt></b>
 84
 85<blockquote>
 86Reads all of the data from an open file into a string which is returned.
 87</blockquote>
 88
 89<p>
 90<b><tt>String *Swig_include(const String_or_char *name)</tt></b>
 91
 92<blockquote>
 93Searches for an include file <tt>name</tt> and returns its contents as
 94a string if found.  Returns NULL if not found.  All of the applicable
 95search paths are searched when trying to locate the file.
 96</blockquote>
 97
 98<p>
 99<b><tt>String *Swig_include_sys(const String_or_char *name)</tt></b>
100
101<blockquote>
102Searches for an include file <tt>name</tt> and returns its contents as
103a string if found.  Returns NULL if not found.  All of the applicable
104search paths are searched when trying to locate the file, but
105preference is given to system paths first. This mimics the behavior
106of <tt>#include &lt;file&gt;</tt> in the preprocessor.
107</blockquote>
108
109<p>
110<b><tt>int Swig_insert_file(const String_or_char *name, File *outfile)</tt></b>
111
112<blockquote>
113Searches for a file <tt>name</tt> and dumps its contents to <tt>outfile</tt> if found.
114Returns 0 on success, -1 if the file couldn't be found.
115</blockquote>
116
117<h2>Query functions</h2>
118
119<p>
120<b><tt>String *Swig_last_file()</tt></b>
121
122<blockquote>
123Returns the full pathname of the file last opened or included.
124</blockquote>
125
126<h2>Named files</h2>
127
128<p>
129<b><tt>void *Swig_register_filebyname(const String_or_char *filename, File *outfile)</tt></b>
130
131<blockquote>
132Registers a file object <tt>outfile</tt> with a specific name <tt>filename</tt>.   This function is
133used to implement the SWIG %insert directive and to manage different sections of the output
134file such as "runtime","header","wrapper","init", etc.   Different language modules may add their own
135sections for generating Python code, Perl code, etc.
136</blockquote>
137
138<p>
139<b><tt>File *Swig_filebyname(const String_or_char *filename)</tt></b>
140<blockquote>
141This looks up a file object previously registered using <tt>Swig_register_filebyname()</tt>.  This 
142is used to implement the %insert directive.
143</blockquote>
144
145<h2>Filename utilities</h2>
146
147<p>
148<b><tt>char *Swig_file_suffix(const String_or_char *filename)</tt></b>
149<blockquote>
150Returns the suffix of a filename.  For instance, if the filename is "foo.txt", it returns ".txt".
151</blockquote>
152
153<p>
154<b><tt>char *Swig_file_basename(const String_or_char *filename)</tt></b>
155<blockquote>
156Returns the filename without the suffix attached to it.  For instance, if the filename is "foo.txt", it returns
157"foo".  The result is stored in a static variable. If you need to save it, make your own copy.
158</blockquote>
159
160<p>
161<b><tt>char *Swig_file_filename(const String_or_char *filename)</tt></b>
162<blockquote>
163Returns the filename without any leading directories.  For instance, if the filename is "/bar/spam/foo.txt", it
164returns "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</blockquote>
166
167<p>
168<b><tt>char *Swig_file_dirname(const String_or_char *filename)</tt></b>
169<blockquote>
170Returns the directory name (if any).  For instance, if the filename is "/bar/spam/foo.txt", it
171returns "/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</blockquote>
173
174<p>
175<b><tt>SWIG_FILE_DELIMITER</tt></b>
176<blockquote>
177This macro contains the file delimiter string for the local machine.  On Unix it is "/", on Windows it is "\\".
178</blockquote>
179
180</body>
181</html>