Updated filename.H function docs with indication of #include <FL/filename.H>

and in several cases, code examples.

Solves issue raised on fltk.general (12/30/09) by Alvin.



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6986 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

FL/filename.H

@@ -34,9 +34,23 @@
     @{ */
 
 #  define FL_PATH_MAX 256 /**< all path buffers should use this length */
-/** Gets the file name from a path. \return a pointer to the char after the last slash, or to \p filename if there is none. */
+/** Gets the file name from a path. 
+    Similar to basename(3), exceptions shown below.
+    \code
+    #include <FL/filename.H>
+    [..]
+    const char *out;
+    out = fl_filename_name("/usr/lib");     // out="lib"
+    out = fl_filename_name("/usr/");        // out=""      (basename(3) returns "usr" instead)
+    out = fl_filename_name("/usr");         // out="usr"
+    out = fl_filename_name("/");            // out=""      (basename(3) returns "/" instead)
+    out = fl_filename_name(".");            // out="."
+    out = fl_filename_name("..");           // out=".."
+    \endcode
+    \return a pointer to the char after the last slash, or to \p filename if there is none.
+ */
 FL_EXPORT const char *fl_filename_name(const char * filename);
-FL_EXPORT const char *fl_filename_ext(const char *);
+FL_EXPORT const char *fl_filename_ext(const char *buf);
 FL_EXPORT char *fl_filename_setext(char *to, int tolen, const char *ext);
 FL_EXPORT int fl_filename_expand(char *to, int tolen, const char *from);
 FL_EXPORT int fl_filename_absolute(char *to, int tolen, const char *from);

src/filename_absolute.cxx

@@ -48,12 +48,19 @@ inline int isdirsep(char c) {return c=='/' || c=='\\';}
 #define isdirsep(c) ((c)=='/')
 #endif
 
-/**
- * Makes a filename absolute from a relative filename.
- * \param[out] to resulting absolute filename
- * \param[in]  tolen size of the absolute filename buffer 
- * \param[in]  from relative filename
- * \return 0 if no change, non zero otherwise
+/** Makes a filename absolute from a relative filename.
+    \code
+    #include <FL/filename.H>
+    [..]
+    chdir("/var/tmp");
+    fl_filename_absolute(out, sizeof(out), "foo.txt");         // out="/var/tmp/foo.txt"
+    fl_filename_absolute(out, sizeof(out), "./foo.txt");       // out="/var/tmp/foo.txt"
+    fl_filename_absolute(out, sizeof(out), "../log/messages"); // out="/var/log/messages"
+    \endcode
+    \param[out] to resulting absolute filename
+    \param[in]  tolen size of the absolute filename buffer 
+    \param[in]  from relative filename
+    \return 0 if no change, non zero otherwise
  */
 int fl_filename_absolute(char *to, int tolen, const char *from) {
   if (isdirsep(*from) || *from == '|'
@@ -108,12 +115,23 @@ int fl_filename_absolute(char *to, int tolen, const char *from) {
   return 1;
 }
 
-/**
- * Makes a filename relative to the current working directory.
- * \param[out] to resulting relative filename
- * \param[in]  tolen size of the relative filename buffer 
- * \param[in]  from absolute filename
- * \return 0 if no change, non zero otherwise
+/** Makes a filename relative to the current working directory.
+    \code
+    #include <FL/filename.H>
+    [..]
+    chdir("/var/tmp/somedir");       // set cwd to /var/tmp/somedir
+    [..]
+    char out[1024];
+    fl_filename_relative(out, sizeof(out), "/var/tmp/somedir/foo.txt");  // out="foo.txt",    return=1
+    fl_filename_relative(out, sizeof(out), "/var/tmp/foo.txt");          // out="../foo.txt", return=1
+    fl_filename_relative(out, sizeof(out), "foo.txt");                   // out="foo.txt",    return=0 (no change)
+    fl_filename_relative(out, sizeof(out), "./foo.txt");                 // out="./foo.txt",  return=0 (no change)
+    fl_filename_relative(out, sizeof(out), "../foo.txt");                // out="../foo.txt", return=0 (no change)
+    \endcode
+    \param[out] to resulting relative filename
+    \param[in]  tolen size of the relative filename buffer 
+    \param[in]  from absolute filename
+    \return 0 if no change, non zero otherwise
  */
 int					// O - 0 if no change, 1 if changed
 fl_filename_relative(char       *to,	// O - Relative filename

src/filename_expand.cxx

@@ -47,12 +47,27 @@ static inline int isdirsep(char c) {return c=='/' || c=='\\';}
 #define isdirsep(c) ((c)=='/')
 #endif
 
-/**
- * Expands a filename coontaining shell variables.
- * \param[out] to resulting expanded filename
- * \param[in]  tolen size of the expanded filename buffer 
- * \param[in]  from filename containing shell variables
- * \return 0 if no change, non zero otherwise
+/** Expands a filename containing shell variables and tilde (~).
+    Currently handles these variants:
+    \code
+    "~username"               // if 'username' does not exist, result will be unchanged
+    "~/file"
+    "$VARNAME"                // does NOT handle ${VARNAME}
+    \endcode
+
+    \b Examples:
+    \code
+    #include <FL/filename.H>
+    [..]
+    putenv("TMPDIR=/var/tmp");
+    fl_filename_expand(out, sizeof(out), "~fred/.cshrc");     // out="/usr/fred/.cshrc"
+    fl_filename_expand(out, sizeof(out), "~/.cshrc");         // out="/usr/<yourname>/.cshrc"
+    fl_filename_expand(out, sizeof(out), "$TMPDIR/foo.txt");  // out="/var/tmp/foo.txt"
+    \endcode
+    \param[out] to resulting expanded filename
+    \param[in]  tolen size of the expanded filename buffer 
+    \param[in]  from filename containing shell variables
+    \return 0 if no change, non zero otherwise
  */
 int fl_filename_expand(char *to,int tolen, const char *from) {
 

src/filename_ext.cxx

@@ -29,8 +29,14 @@
 
 #include <FL/filename.H>
 
-/**
-   Gets the extensions of a filename
+/** Gets the extensions of a filename.
+   \code
+   #include <FL/filename.H>
+   [..]
+   const char *out;
+   out = fl_filename_ext("/some/path/foo.txt");        // result: ".txt"
+   out = fl_filename_ext("/some/path/foo");            // result: NULL
+   \endcode
    \param[in] buf the filename to be parsed
    \return a pointer to the extension (including '.') if any or NULL otherwise
  */

src/filename_isdir.cxx

@@ -48,7 +48,13 @@ int _fl_filename_isdir_quick(const char* n) {
 }
 
 /**
-   Determines if a file exists and is a directory from its filename
+   Determines if a file exists and is a directory from its filename.
+   \code
+   #include <FL/filename.H>
+   [..]
+   fl_filename_isdir("/etc");		// returns non-zero
+   fl_filename_isdir("/etc/hosts");	// returns 0
+   \endcode
    \param[in] n the filename to parse
    \return non zero if file exists and is a directory, zero otherwise
 */

src/filename_list.cxx

@@ -58,6 +58,12 @@ int fl_casealphasort(struct dirent **a, struct dirent **b) {
    The number of entries is given as a return value. 
    If there is an error reading the directory a number less than zero is returned, 
    and errno has the reason; errno does not work under WIN32. 
+
+   \b Include:
+   \code
+   #include <FL/filename.H>
+   \endcode
+
    \param[in] d the name of the directory to list.  It does not matter if it has a trailing slash.
    \param[out] list table containing the resulting directory listing
    \param[in] sort sorting functor:

src/filename_match.cxx

@@ -40,6 +40,12 @@
     - {X|Y|Z} or {X,Y,Z} matches any one of the subexpressions literally.
     - \\x quotes the character x so it has no special meaning.
     - x all other characters must be matched exactly.
+
+    \b Include:
+    \code
+    #include <FL/filename.H>
+    \endcode
+
     \param[in] s the string to check for a match
     \param[in] p the string pattern 
     \return non zero if the string matches the pattern

src/filename_setext.cxx

@@ -26,14 +26,24 @@
 //
 
 // Replace .ext with new extension
-// If no . in name, append new extension
-// If new extension is null, act like it is ""
 
 #include <FL/filename.H>
 #include "flstring.h"
 
 /**
-   Replaces the extension in \p buf of max. size \p buflen with the extension in \p ext. 
+   Replaces the extension in \p buf of max.<br>
+   size \p buflen with the extension in \p ext.<br>
+   If there's no '.' in \p buf, \p ext is appended.<br>
+   If \p ext is NULL, behaves as if it were an empty string ("").
+
+   \b Example
+   \code
+   #include <FL/filename.H>
+   [..]
+   char buf[1024] = "/path/myfile.cxx";
+   fl_filename_setext(buf, sizeof(buf), ".txt");      // buf[] becomes "/path/myfile.txt"
+   \endcode
+
    \return buf itself for calling convenience.
 */
 char *fl_filename_setext(char *buf, int buflen, const char *ext) {

src/fl_open_uri.cxx

@@ -71,6 +71,18 @@ static int	run_program(const char *program, char **argv, char *msg, int msglen);
  *
  * On failure, the msg buffer is filled with an English error message.
  *
+ * \b Example
+ * \code
+ * #include <FL/filename.H>
+ * [..]
+ * char errmsg[512];
+ * if ( !fl_open_uri("http://google.com/", errmsg, sizeof(errmsg)) ) {
+ *     char warnmsg[768];
+ *     sprintf(warnmsg, "Error: %s", errmsg);
+ *     fl_alert(warnmsg);
+ * }
+ * \endcode
+ *
  * @param uri The URI to open
  * @param msg Optional buffer which contains the command or error message
  * @param msglen Length of optional buffer