=== modified file 'manual.scrbl' --- manual.scrbl 2012-10-02 18:47:25 +0000 +++ manual.scrbl 2012-10-02 21:33:55 +0000 @@ -1,21 +1,23 @@ #lang scribble/manual -@(require - planet/scribble - (for-label racket - "file-utils.rkt")) +@(require planet/scribble + (for-label racket + (this-package-in main))) -@defmodule/this-package[main] @title{File Utilities} -Author: Erich Rast @verbatim{erich 'at snafu.de} +@author+email["Erich Rast" "erich 'at snafu.de"] @section{Introduction} -The File Utilities library is a collection of helper functions for dealing with paths and files. +The File Utilities library is a collection of helper functions +for dealing with paths and files. -Note: Most of this library has been developed for older versions of Racket. You should check if there is a built-in Racket library function with the same functionality before using one from this library. +Note: Most of this library has been developed for older versions +of Racket. You should check if there is a built-in Racket library +function with the same functionality before using one from this library. @section{Function Reference} +@defmodule/this-package[main] @defproc[(get-file-or-folder-name [file-path (or/c string? path?)]) string?]{ @@ -23,7 +25,9 @@ @defproc[(name-as-string [file-path (or/c string? path?)]) string?]{ - If @racket[file-path] is a already string, it is returned without change, otherwise the name part of the path is returned as by @racket[get-file-or-folder-name].} + If @racket[file-path] is a already string, it is + returned without change, otherwise the name part + of the path is returned as by @racket[get-file-or-folder-name].} @defproc[(filename-main [file-path (or/c string? path?)]) string?]{ @@ -31,15 +35,24 @@ @defproc[(filename-suffix [file-path (or/c string? path?)]) string?]{ - Returns the suffix part of a file or folder path. If there are multiple suffixes, only the last one is returned. If no suffix is present, an empty string is returned.} + Returns the suffix part of a file or folder path. If there are multiple + suffixes, only the last one is returned. If no suffix is present, + an empty string is returned.} @defproc[(compose-name [name string?] [n (or/c number? boolean?)] [suffix string?]) string?]{ - Composes a file name out of a main part @racket[name], a number, and a suffix string. If the number part @racket[n] is @racket[#f] then no number will be added to the name part.} + Composes a file name out of a main part @racket[name], a number, + and a suffix string. If the number part @racket[n] is @racket[#f] + then no number will be added to the name part.} @defproc[(make-unique-name [name (or/c string? path?)] [folder path?]) string?]{ - Returns a name string that is guaranteed to be unique within @racket[folder]. Caution: This procedure creates neat file names such as @racket["file-3.txt"] for a given name @racket["file.txt"] but does so at the cost of checking for existing files with number suffixes 1, 2, ..., so for performance reasons you ought not use this function to create many files with the same base and suffix part within a folder.} + Returns a name string that is guaranteed to be unique within @racket[folder]. + Caution: This procedure creates neat file names such as @racket["file-3.txt"] + for a given name @racket["file.txt"] but does so at the cost of checking for + existing files with number suffixes 1, 2, ..., so for performance reasons you + ought not use this function to create many files with the same base and suffix + part within a folder.} @defproc[(parent-directory [path path?]) (or/c path? boolean/c)]{ @@ -47,27 +60,42 @@ @defproc[(make-unique-path [suggested-path path?]) path?]{ - Returns a file or directory path that is unique within the parent directory of @racket[suggested-path]. The same performance caveat as for @racket[make-unique-name] applies.} + Returns a file or directory path that is unique within the parent directory of + @racket[suggested-path]. The same performance caveat as for @racket[make-unique-name] applies.} @defproc[(path-equal? [p1 path?] [p2 path?]) boolean/c]{ - Returns @racket[#t] if the two paths given likely point to the same location in the file system, @racket[#f] otherwise. This method normalizes the paths, but might yield false negatives under rare circumstances. Use @racket[file=?] for a slower, but more reliable method to compare whether two paths point to the same file.} + Returns @racket[#t] if the two paths given likely point to the same location + in the file system, @racket[#f] otherwise. This method normalizes the + paths, but might yield false negatives under rare circumstances. + Use @racket[file=?] for a slower, but more reliable method to compar + e whether two paths point to the same file.} @defproc[(file=? [file1 path?] [file2 path?]) boolean/c]{ - Returns @racket[#t] if the two file paths alias the same file in the file system, @racket[#f] otherwise. This method requires read permissions on the files and temporarily opens the files for reading. It cannot be used to compare directories.} + Returns @racket[#t] if the two file paths alias the same file in the file system, + @racket[#f] otherwise. This method requires read permissions on the files + and temporarily opens the files for reading. It cannot be used to compare + directories.} @defproc[(move-folder-to [source-directory path?] [destination-directory path?]) void/c]{ - Moves the source directory into the destination directory. This method might fail with a filesystem exception if the source and destination directories do not reside on the same volume.} + Moves the source directory into the destination directory. This method might fail + with a filesystem exception if the source and destination directories do not reside on the same volume.} @defproc[(copy-folders/renaming [source-directory path?] [dest-directory path?] [pred? (path? .->. boolean/c)]) void/c]{ - Copy all files in the source directory for which @racket[pred?] returns true into the destination directory. If a file or directory with the same name already exists in the destination directory, then the target file or folder is renamed by adding a number to it before its suffix.} + Copy all files in the source directory for which @racket[pred?] returns true into + the destination directory. If a file or directory with the same name already exists in + the destination directory, then the target file or folder is renamed by adding a + number to it before its suffix.} @defproc[(file-is-visible? [file path?]) boolean/c]{ - Returns @racket[#t] if the file is visible according to Unix naming conventions, @racket[#f] otherwise. This function only checks whether the file name starts with "." and might not correctly identify other types of invisible files (e.g. on OS X).} + Returns @racket[#t] if the file is visible according to Unix naming + conventions, @racket[#f] otherwise. This function only checks whether the + file name starts with "." and might not correctly identify other types of + invisible files (e.g. on OS X).} @defproc[(count-lines [port port? (current-input-port)]) integer/c]{ @@ -75,7 +103,9 @@ @defproc[(move-file-to [source path?] [target path?]) void/c]{ - Move the file at @racket[source] to the directory @racket[target]. This function also works accross volume boundaries, in case of which the file is copied and the original file is deleted.} + Move the file at @racket[source] to the directory @racket[target]. + This function also works accross volume boundaries, in case of which the file is copied + and the original file is deleted.} @defproc[(file-equal? [file1 path?] [file2 path?]) boolean/c]{