diff options
| author | Dave Beazley <dave-swig@dabeaz.com> | 2006-12-19 03:49:17 +0000 |
|---|---|---|
| committer | Dave Beazley <dave-swig@dabeaz.com> | 2006-12-19 03:49:17 +0000 |
| commit | 79451aa1a708b0bd3bf4ec0f11ea7a1052a5f0a1 (patch) | |
| tree | ae6bec25fabda132bce1bb2e9e5b2764aff8ddeb /Doc/Devel | |
| parent | 4b31a3ee50f2fa9dead26ba00a58fa73e12f576f (diff) | |
| download | swig-79451aa1a708b0bd3bf4ec0f11ea7a1052a5f0a1.tar.gz | |
File management cleanup. Split API into separate header. Removed unused functions. Added documentation
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@9622 626c5289-ae23-0410-ae9c-e8d60b6d4f22
Diffstat (limited to 'Doc/Devel')
| -rw-r--r-- | Doc/Devel/file.html | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/Doc/Devel/file.html b/Doc/Devel/file.html new file mode 100644 index 000000000..86dcbb52a --- /dev/null +++ b/Doc/Devel/file.html @@ -0,0 +1,185 @@ +<html> +<head> +<title>SWIG File Handling</title> +</head> + +<body> +<center> +<h1>SWIG File Handling</h1> + +<p> +David M. Beazley <br> +dave-swig@dabeaz.com<br> + +</b> +</center> + +<h2>Introduction</h2> + +This document describes the functions related to file and filename handling in the SWIG core. These functions are +defined in the header file <tt>Source/Swig/swigfile.h</tt>. This API is considered to be stable. + +<h2>File Search Path</h2> + +These functions manipulate the search path for locating files. + +<p> +<b><tt>List *Swig_add_directory(const String_or_char *dirname)</tt></b> + +<blockquote> +Adds a new directory to the system search path. The directory is appended to +the end of the search path. Returns a list containing the current +system search path. +</blockquote> + +<p> +<b><tt>void Swig_push_directory(const String_or_char *dirname)</tt></b> +<blockquote> +Pushs a temporary directory onto the search path. This directory is searched before +directories added with <tt>Swig_add_directory()</tt> except when including a system +file explicitly (either using #include <file> or calling <tt>Swig_include_sys()</tt>). +This function is normally used by the preprocessor to add temporary directories when +processing #include statements. +</blockquote> + +<p> +<b><tt>void Swig_pop_directory()</tt></b> +<blockquote> +Pops off the last pushed directory with <tt>Swig_push_directory()</tt> +</blockquote> + +<p> +<b><tt>int Swig_get_push_dir()</tt></b> + +<blockquote> +Returns a flag that indicates whether directory pushing is enabled or not. +</blockquote> + +<p> +<b><tt>void Swig_set_push_dir(int dopush)</tt></b> +<blockquote> +Enables or disables directory pushing. By default, it is turned on. However, the <tt>-I-</tt> command line +option to SWIG disables it. +</blockquote> + +<p> +<b><tt>List *Swig_search_path()</tt></b> +<blockquote> +Returns the current search path. +</blockquote> + + +<h2>File access functions</h2> + +<p> +<b><tt>FILE *Swig_open(const String_or_char *name)</tt></b> + +<blockquote> +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. +</blockquote> + +<p> +<b><tt>String *Swig_read_file(FILE *f)</tt></b> + +<blockquote> +Reads all of the data from an open file into a string which is returned. +</blockquote> + +<p> +<b><tt>String *Swig_include(const String_or_char *name)</tt></b> + +<blockquote> +Searches for an include file <tt>name</tt> and returns its contents as +a string if found. Returns NULL if not found. All of the applicable +search paths are searched when trying to locate the file. +</blockquote> + +<p> +<b><tt>String *Swig_include_sys(const String_or_char *name)</tt></b> + +<blockquote> +Searches for an include file <tt>name</tt> and returns its contents as +a string if found. Returns NULL if not found. All of the applicable +search paths are searched when trying to locate the file, but +preference is given to system paths first. This mimics the behavior +of <tt>#include <file></tt> in the preprocessor. +</blockquote> + +<p> +<b><tt>int Swig_insert_file(const String_or_char *name, File *outfile)</tt></b> + +<blockquote> +Searches for a file <tt>name</tt> and dumps its contents to <tt>outfile</tt> if found. +Returns 0 on sucesss, -1 if the file couldn't be found. +</blockquote> + +<h2>Query functions</h2> + +<p> +<b><tt>String *Swig_last_file()</tt></b> + +<blockquote> +Returns the full pathname of the file last opened or included. +</blockquote> + +<h2>Named files</h2> + +<p> +<b><tt>void *Swig_register_filebyname(const String_or_char *filename, File *outfile)</tt></b> + +<blockquote> +Registers a file object <tt>outfile</tt> with a specific name <tt>filename</tt>. This function is +used to implement the SWIG %insert directive and to manage different sections of the output +file such as "runtime","header","wrapper","init", etc. Different language modules may add their own +sections for generating Python code, Perl code, etc. +</blockquote> + +<p> +<b><tt>File *Swig_filebyname(const String_or_char *filename)</tt></b> +<blockquote> +This looks up a file object previously registered using <tt>Swig_register_filebyname()</tt>. This +is used to implement the %insert directive. +</blockquote> + +<h2>Filename utilities</h2> + +<p> +<b><tt>char *Swig_file_suffix(const String_or_char *filename)</tt></b> +<blockquote> +Returns the suffix of a filename. For instance, if the filename is "foo.txt", it returns ".txt". +</blockquote> + +<p> +<b><tt>char *Swig_file_basename(const String_or_char *filename)</tt></b> +<blockquote> +Returns the filename without the suffix attached to it. For instance, if the filename is "foo.txt", it returns +"foo". The result is stored in a static variable. If you need to save it, make your own copy. +</blockquote> + +<p> +<b><tt>char *Swig_file_filename(const String_or_char *filename)</tt></b> +<blockquote> +Returns the filename without any leading directories. For instance, if the filename is "/bar/spam/foo.txt", it +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. +</blockquote> + +<p> +<b><tt>char *Swig_file_dirname(const String_or_char *filename)</tt></b> +<blockquote> +Returns the directory name (if any). For instance, if the filename is "/bar/spam/foo.txt", it +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. +</blockquote> + +<p> +<b><tt>SWIG_FILE_DELIMETER</tt></b> +<blockquote> +This macro contains the file delimeter string for the local machine. On unix it is "/", on Windows it is "\\". +</blockquote> + +</body> +</html> + + + + + |