Menu
▾
▴
[Pmplib-commits] SF.net SVN: pmplib: [187] trunk/pmplib/doc
|
From: <suc...@us...> - 2006-08-18 23:08:52
|
Revision: 187 Author: sucknblow Date: 2006-08-18 16:08:34 -0700 (Fri, 18 Aug 2006) ViewCVS: http://svn.sourceforge.net/pmplib/?rev=187&view=rev Log Message: ----------- API doc improvements: fix title in HTML output add rel2abs to the docs (needed a header file) fewer enum consts per line use a full stop on module names improve util.c docs document: path separator defines, more filepath stuff, rel2abs (incomplete, function looks broken to me) Modified Paths: -------------- trunk/pmplib/doc/Doxyfile trunk/pmplib/doc/pmplib-head.html trunk/pmplib/frontend/easypmp/cui/util.c trunk/pmplib/include/os.h trunk/pmplib/lib/filepath/filepath_posix.c trunk/pmplib/lib/filepath/rel2abs.c trunk/pmplib/lib/gmi/Mainpage.dox trunk/pmplib/lib/ucs2/Mainpage.dox Added Paths: ----------- trunk/pmplib/lib/filepath/rel2abs.h Modified: trunk/pmplib/doc/Doxyfile =================================================================== --- trunk/pmplib/doc/Doxyfile 2006-08-13 02:51:10 UTC (rev 186) +++ trunk/pmplib/doc/Doxyfile 2006-08-18 23:08:34 UTC (rev 187) @@ -3,7 +3,7 @@ #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- -PROJECT_NAME = PMPlib API +PROJECT_NAME = "PMPlib API" PROJECT_NUMBER = 0.12 OUTPUT_DIRECTORY = apidox CREATE_SUBDIRS = NO @@ -134,7 +134,7 @@ BINARY_TOC = NO TOC_EXPAND = NO DISABLE_INDEX = YES -ENUM_VALUES_PER_LINE = 4 +ENUM_VALUES_PER_LINE = 3 GENERATE_TREEVIEW = NO TREEVIEW_WIDTH = 250 #--------------------------------------------------------------------------- Modified: trunk/pmplib/doc/pmplib-head.html =================================================================== --- trunk/pmplib/doc/pmplib-head.html 2006-08-13 02:51:10 UTC (rev 186) +++ trunk/pmplib/doc/pmplib-head.html 2006-08-18 23:08:34 UTC (rev 187) @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> -<title>pmplib: Cui</title> +<title>$title</title> <link href="../../common.css" rel="stylesheet" type="text/css"> <link href="pmplib-api.css" rel="stylesheet" type="text/css"> <link href="tabs.css" rel="stylesheet" type="text/css"> Modified: trunk/pmplib/frontend/easypmp/cui/util.c =================================================================== --- trunk/pmplib/frontend/easypmp/cui/util.c 2006-08-13 02:51:10 UTC (rev 186) +++ trunk/pmplib/frontend/easypmp/cui/util.c 2006-08-18 23:08:34 UTC (rev 187) @@ -22,10 +22,19 @@ /* $Id$ */ -#ifdef HAVE_CONFIG_H +/** + * @file + * Utility functions for the easypmp command line program (mostly + * display related). + * + * @addtogroup cui + * @{ + */ + +#ifdef HAVE_CONFIG_H #include <config.h> #endif/*HAVE_CONFIG_H*/ -#ifdef HAVE_STRING_H +#ifdef HAVE_STRING_H #include <string.h> #endif/*HAVE_STRING_H*/ @@ -42,48 +51,46 @@ #include "util.h" -/** - * \addtogroup cui - * @{ - */ - #if CAN_GET_WIN_SIZE /** - The number of characters that can be printed on a single line, - without causing a line wrap. Since the right-most column is - required for the cursor, this is one less than the actual terminal - width. - - Defaults to 79 on systems where we can't tell the width of the - terminal. -*/ + * The number of characters that can be printed on a single line, + * without causing a line wrap. Since the right-most column is + * required for the cursor, this is one less than the actual terminal + * width. + * + * Defaults to 79 on systems where we can't tell the width of the + * terminal. + */ static volatile unsigned short int window_width; #else static const unsigned short int window_width = 79; #endif -/** - The minimum width of the terminal we're willing to entertain. If the - terminal gets narrower than this width, we treat it as this width. - Note that it must be at least 2 to allow for one character and the - cursor. +/** + * The minimum width of the terminal we're willing to entertain. If + * the terminal gets narrower than this width, we treat it as this + * width. Note that it must be at least 2 to allow for one character + * and the cursor. */ static const int min_term_width = 6; +#define POSSIBLE_TTYS 2 /** - Flags to indicate whether stdin, stdout, and stderr are attached to a - terminal. These are used to determine whether we should check the - width of some progress lines before printing them. Initialised in - display_init. + * Flags to indicate whether stdin, stdout, and stderr are attached to + * a terminal. These are used to determine whether we should check + * the width of some progress lines before printing them. Initialised + * in display_init. */ -#define POSSIBLE_TTYS 2 static int fd_is_tty[POSSIBLE_TTYS+1]; #if CAN_GET_WIN_SIZE -/** - Hander for the "terminal window changed size" signal. -*/ + +/** + * Handler for the "terminal window changed size" signal. + * + * @param unused + */ void window_size_changed(int unused) { static struct winsize wsize; @@ -98,10 +105,15 @@ #endif/*CAN_GET_WIN_SIZE*/ +/** + * Determines whether stdin, stdout and stderr are associated with a + * TTY, and update fd_is_tty accordingly. Also sets up + * window_size_changed as a signal handler. + */ void display_init() { int i; - for(i = 0; i <= 2; ++i) + for(i = 0; i <= POSSIBLE_TTYS; ++i) fd_is_tty[i] = isatty(i); #if CAN_GET_WIN_SIZE @@ -110,9 +122,13 @@ #endif/*CAN_GET_WIN_SIZE*/ } -/** - Delete all text on the current line by overwriting it with spaces, - and write a \r to return the cursor to the start of the line. +/** + * Deletes all text on the current line by overwriting it with spaces. + * + * A 'blank line' is written to a given file pointer, @p fp. That is, + * a number of spaces equal to the current window width is written. + * This is followed by a carriage return character, to return the + * cursor to the start of the line. */ void clear_line(FILE *fp) { @@ -124,21 +140,23 @@ fprintf(fp, fmt, ""); } - -/** - Display as much of a UCS-2 encoded string as will fit on a single - line in the terminal, and returning the cursor to the start of the - line. If the terminal is less that the given minimum width, display - that minimum number of characters anyway, even if it means the text - will wrap onto the next line. - - If fp isn't associated with a terminal, just print the whole line. - - fp - FILE* to print on - line - the UCS-2 encoded string to display - min-width - minimum number of characters to print +/** + * Displays a UCS-2 string truncated for the terminal width. + * + * Displays as much of a UCS-2 encoded string as will fit on a single + * line in the terminal, and returning the cursor to the start of the + * line. If the terminal is less that the given minimum width, that + * minimum number of characters is displayed anyway, even if it means + * the text will wrap onto the next line. + * + * If @p fp isn't associated with a terminal, just print the whole line. + * + * @param fp FILE* to print on + * @param line the UCS-2 encoded string to display + * @param min_width minimum number of characters to print */ -void display_line(FILE *fp, const ucs2char_t* const line, unsigned int min_width) +void display_line(FILE *fp, const ucs2char_t* const line, + unsigned int min_width) { int writing_to_tty; /* Check if writing to a terminal. If so, clear the current line. */ @@ -174,19 +192,17 @@ } } -/** - Generic display method for progress messages consisting of a number - and a string. - - @param n number to be shown in the numeric part - @param msg message +/** + * Generic display method for progress messages consisting of a + * number and a string. + * + * @param fp + * @param n number to be shown in the numeric part + * @param msg message + * + * @return */ -int -easypmp_progress_num_str( - FILE *fp, - size_t n, - const ucs2char_t* msg - ) +int easypmp_progress_num_str(FILE *fp, size_t n, const ucs2char_t* msg) { /* A terminal must be of a certain width in order to usefully @@ -194,7 +210,7 @@ Specifically, it needs to be wide enough to display the number of files read. - display_line is used to trucate the line in this way. + display_line is used to truncate the line in this way. */ // Numeric part, plus associated punctuation @@ -222,7 +238,8 @@ fprints_fixed(fp, format, value, ucs2len(value)); } -void fprints_fixed(FILE *fp, const char *format, const ucs2char_t* value, size_t length) +void fprints_fixed(FILE *fp, const char *format, const ucs2char_t* value, + size_t length) { char *mbs = NULL; ucs2char_t* tmp = alloca(sizeof(ucs2char_t) * (length+1)); Modified: trunk/pmplib/include/os.h =================================================================== --- trunk/pmplib/include/os.h 2006-08-13 02:51:10 UTC (rev 186) +++ trunk/pmplib/include/os.h 2006-08-18 23:08:34 UTC (rev 187) @@ -1,5 +1,5 @@ /* - * Compatibility staff among operating systems and compilers. + * Compatibility stuff among operating systems and compilers. * * Copyright (c) 2005-2006 Nyaochi * @@ -55,7 +55,14 @@ #else +/** + * The native path separator for the current system, as a character. + */ #define PATHCHAR '/' + +/** + * The native path separator for the current system, as a string. + */ #define PATHSTR "/" #endif Modified: trunk/pmplib/lib/filepath/filepath_posix.c =================================================================== --- trunk/pmplib/lib/filepath/filepath_posix.c 2006-08-13 02:51:10 UTC (rev 186) +++ trunk/pmplib/lib/filepath/filepath_posix.c 2006-08-18 23:08:34 UTC (rev 187) @@ -2,6 +2,7 @@ * File/path utility implemented with POSIX API. * * Copyright (c) 2005 Nyaochi + * Copyright (c) 2006 Martin Ellis <mar...@kd...> * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -43,10 +44,9 @@ #include <string.h> #include <sys/stat.h> -#include <filepath.h> +#include "filepath.h" +#include "rel2abs.h" -ucs2char_t *rel2abs(const ucs2char_t *path, const ucs2char_t *base, ucs2char_t *ucs2char_t, size_t size); - int find_file(const ucs2char_t* path, int recursive, filepath_findfile_callback callback, void *instance) { DIR *dirp = NULL; @@ -174,7 +174,6 @@ * terminator). * * @param path the path name to be modified. - * * @return a pointer to the last character in the new path. */ ucs2char_t* filepath_removeslash(ucs2char_t* path) @@ -187,6 +186,15 @@ return (path + length); } +/** + * Determines if a filename has a given extension (case-insensitive). + * + * + * @param filename file name to be checked. + * @param ext file name extension to check for. + * @return non-nil if the filename has the given extension, or nil + * otherwise. + */ int filepath_hasext(const ucs2char_t* filename, const ucs2char_t* ext) { const ucs2char_t* p = search_extension((ucs2char_t*)filename); @@ -200,6 +208,10 @@ p++; ext++; } + /* ME: This seems redundant... won't "return (*p == *q);" do? + We only need to know whether we've reached the end of both + strings... + */ return (ucs2lower(*p) == ucs2lower(*ext)); } @@ -281,6 +293,15 @@ } } +/** + * Replace native path separators in a path with another character. + * + * The native path separators (i.e. '/' on POSIX-like systems) in the + * given @p path are replaced with the given character, @p c. The + * path is modified in place. + * @param path the path in which path separators are to be replaced. + * @param c the replacement character. + */ void filepath_replace_slash(ucs2char_t* path, ucs2char_t c) { while (*path) { @@ -315,6 +336,17 @@ } } +/** + * Tests whether a path name is relative. + * + * Checks whether the given @p path begins with a path separator + * character. If the path does begin with a path separator, then it + * is absolute and nil is returned. Otherwise the path is relative, + * and a non-nil value is returned. + * + * @param path the path to be tested for being relative. + * @return non-nil if the path name is relative, nil otherwise. + */ int filepath_is_relative(const ucs2char_t* path) { return (*path != PATHCHAR); @@ -330,11 +362,34 @@ return (rel2abs(relative, base, absolute, MAX_PATH) != NULL); } +/** + * Tests whether a path name has a given prefix. + * + * Tests whether the @p path name begins with the named @p root. If + * @p root names a directory with a trailing path separator, then this + * function is useful for checking whether a directory (or file) with + * the given @p path would be a sub-directory of (respectively, file + * located below) @p root. + * @param path the path name to be checked for a given prefix. + * @param root the prefix to check for. + * @return non-nil if the path name starts with the given @p root and + * nil otherwise. + */ int filepath_is_same_root(const ucs2char_t* path, const ucs2char_t* root) { return (ucs2ncmp(path, root, ucs2len(root)) == 0); } +/** + * Compares the modification times of two files. + * + * The modification times of @p file1 and @p file2 are compared, and + * the difference between them is returned. The result is: + * - < 0, if file2 was modified more recently than file1; + * - = 0, if the modification times are the same; + * - > 0, if file1 was modified more recently than file2. + * @return the difference in modification times between the two files. + */ int filepath_compare_lastupdate(const ucs2char_t* file1, const ucs2char_t* file2) { int ret = 0; @@ -375,6 +430,20 @@ return ret; } +/** + * Removes the named file. + * + * The given @p file name is converted to a multi-byte character + * string, which is used as an argument to the 'remove' function in + * the C library. Thus, if the @p file name refers to a file, then + * that file is unlinked. If it refers to a directory, and that + * directory is empty, then the directory is deleted. The value + * returned is the result of the calling remove, i.e. 0 on success, + * and -1 on error. The value of errno will be set in the case of an + * error. + * @param file the path name to be unlinked/deleted. + * @return 0 on success, -1 on error. + */ int filepath_removefile(const ucs2char_t* file) { int ret = 0; Modified: trunk/pmplib/lib/filepath/rel2abs.c =================================================================== --- trunk/pmplib/lib/filepath/rel2abs.c 2006-08-13 02:51:10 UTC (rev 186) +++ trunk/pmplib/lib/filepath/rel2abs.c 2006-08-18 23:08:34 UTC (rev 187) @@ -1,6 +1,7 @@ /* * Copyright (c) 1997 Shigio Yamaguchi. All rights reserved. * Copyright (c) 1999 Tama Communications Corporation. All rights reserved. + * Copyright (c) 2006 Martin Ellis <mar...@kd...>. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -23,6 +24,14 @@ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. */ + +/* + * @file + * + * @addtogroup filepath + * @{ + */ + #ifdef HAVE_CONFIG_H #include <config.h> #endif/*HAVE_CONFIG_H_*/ @@ -32,22 +41,30 @@ #include <stdlib.h> #include <ucs2char.h> -/* - * rel2abs: convert an relative path name into absolute. +#include "rel2abs.h" + +/** + * Convert an relative path name into absolute path name. * - * i) path relative path - * i) base base directory (must be absolute path) - * o) result result buffer - * i) size size of result buffer - * r) != NULL: absolute path - * == NULL: error + * If the given @p path is already an absolute path, and the @p result + * buffer is large enough, then the absolute path is used as the + * @p result. + * + * On error, returns nil and sets errno to one of the following + * values: + * - EINVAL - the base directory was not an absolute path (did not + * begin with a '/'), or @p size was 0; + * - ERANGE - the @p size of the @p result buffer was too small. + * + * @param path relative path to convert. + * @param base base directory (must be absolute path). + * @param result result buffer. + * @param size size of result buffer. + * + * @return non-nil on success, nil if there was an error. */ -ucs2char_t * -rel2abs(path, base, result, size) - const ucs2char_t *path; - const ucs2char_t *base; - ucs2char_t *result; - const size_t size; +ucs2char_t* rel2abs(const ucs2char_t *path, const ucs2char_t *base, + ucs2char_t *result, const size_t size) { static const ucs2char_t ucs2cs_dot[] = {'.',0}; static const ucs2char_t ucs2cs_dot_dot[] = {'.','.',0}; @@ -62,6 +79,7 @@ int length; if (*path == '/') { + /* if the given path is absolute, just use that as the result */ if (ucs2len(path) >= size) goto erange; ucs2cpy(result, path); @@ -141,3 +159,4 @@ errno = ERANGE; return (NULL); } +/** @} */ Added: trunk/pmplib/lib/filepath/rel2abs.h =================================================================== --- trunk/pmplib/lib/filepath/rel2abs.h (rev 0) +++ trunk/pmplib/lib/filepath/rel2abs.h 2006-08-18 23:08:34 UTC (rev 187) @@ -0,0 +1,42 @@ +/* + * Relative to absolute path name conversion function (signature). + * + * Copyright (c) 2006 Martin Ellis <mar...@kd...> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA, or visit + * http://www.gnu.org/copyleft/gpl.html . + * + */ + +/* $Id: util.h 183 2006-08-12 18:46:14Z sucknblow $ */ + +#ifndef __REL2ABS_H__ +#define __REL2ABS_H__ + +/** + * \addtogroup filepath + * @{ + */ + +ucs2char_t *rel2abs(const ucs2char_t *path, + const ucs2char_t *base, + ucs2char_t *ucs2char_t, + size_t size); +/** @} */ + +#endif/*__UTIL_H__*/ + + + Modified: trunk/pmplib/lib/gmi/Mainpage.dox =================================================================== --- trunk/pmplib/lib/gmi/Mainpage.dox 2006-08-13 02:51:10 UTC (rev 186) +++ trunk/pmplib/lib/gmi/Mainpage.dox 2006-08-18 23:08:34 UTC (rev 187) @@ -1,5 +1,5 @@ /** - * \defgroup gmi Media file tag reading library (gmi) + * \defgroup gmi Media file tag reading library (gmi). * * This module provides functions for reading tags from media files. */ Modified: trunk/pmplib/lib/ucs2/Mainpage.dox =================================================================== --- trunk/pmplib/lib/ucs2/Mainpage.dox 2006-08-13 02:51:10 UTC (rev 186) +++ trunk/pmplib/lib/ucs2/Mainpage.dox 2006-08-18 23:08:34 UTC (rev 187) @@ -1,5 +1,5 @@ /** - * \defgroup ucs2 UCS-2 string library + * \defgroup ucs2 UCS-2 string library. * * This module provides functions for working with UCS-2 encoded * strings. This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
