From b39491bf6fb747fa697e317316465dccda52b113 Mon Sep 17 00:00:00 2001 From: Marco Baringer Date: Wed, 21 Nov 2012 08:17:44 +0100 Subject: [PATCH] Reordered documentation sections so that functions are grouped by what they do (instead of a semi alphabetical listing) --- doc/index.html | 283 ++++++++++++++++++++++++++----------------------- 1 file changed, 152 insertions(+), 131 deletions(-) diff --git a/doc/index.html b/doc/index.html index 6794774..a1bee63 100644 --- a/doc/index.html +++ b/doc/index.html @@ -52,26 +52,38 @@

CL-FAD - A portable pathname library for Common Lisp

  • Supported Lisp implementations
  • The CL-FAD dictionary
      -
    1. canonical-pathname -
    2. copy-file -
    3. copy-stream -
    4. delete-directory-and-files -
    5. directory-exists-p -
    6. directory-pathname-p -
    7. file-exists-p -
    8. list-directory -
    9. merge-pathnames-as-directory -
    10. merge-pathnames-as-file -
    11. pathname-absolute-p -
    12. pathname-as-directory -
    13. pathname-as-file -
    14. pathname-directory-pathname -
    15. pathname-equal -
    16. pathname-parent-directory -
    17. pathname-relative-p -
    18. pathname-root-p -
    19. walk-directory -
    20. The path package +
    21. Querying files, directories and pathnames +
        +
      1. directory-exists-p +
      2. directory-pathname-p +
      3. file-exists-p +
      4. pathname-absolute-p +
      5. pathname-equal +
      6. pathname-relative-p +
      7. pathname-root-p +
      22. +
    22. Manipulating pathnames +
        +
      1. canonical-pathname +
      2. merge-pathnames-as-directory +
      3. merge-pathnames-as-file +
      4. pathname-as-directory +
      5. pathname-as-file +
      6. pathname-directory-pathname +
      7. pathname-parent-directory +
      23. +
    23. Traversing directories +
        +
      1. list-directory +
      2. walk-directory +
      24. +
    24. Modifying the file system +
        +
      1. copy-file +
      2. copy-stream +
      3. delete-directory-and-files +
      25. +
    25. The path package
  • Acknowledgements @@ -127,23 +139,16 @@

    CL-FAD - A portable pathname library for Common Lisp


     

    The CL-FAD dictionary

    -


    [Function]
    canonical-pathname pathname => result -

    -

    Remove reduntant information from PATHNAME.

    - -

    This simply walks down PATHNAME's -pathname-directory and drops "." directories, removes :back -and its preceding element.

    +

    Querying files, directories and pathnames

    -

    NB: This function does not access the filesystem, it only looks at the -values in the pathname and works on their known (or assumed) -meanings.

    +


    [Function] +
    directory-exists-p pathspec => generalized-boolean -

    NB: Since this function does not access the filesystem it will only -remove :BACK elements from the path (not :UP -elements). Since some lisps, ccl/sbcl/clisp convert ".." in -pathnames to :UP, and not :BACK, the actual -utility of the function is limited.

    +

    +Checks whether the file named by the pathname designator pathspec +exists and if it is a directory. Returns its truename if this is the +case, NIL otherwise. The truename is returned in directory form as if +by PATHNAME-AS-DIRECTORY.


    [Function] @@ -155,19 +160,6 @@

    CL-FAD - A portable pathname library for Common Lisp

    directory designated by pathspec does actually exist.
    -


    [Function] -
    pathname-as-directory pathspec => pathname -


    -Converts the non-wild pathname designator pathspec to directory form, i.e. it returns a pathname which would return a true value if fed to DIRECTORY-PATHNAME-P. -
    - -


    [Function] -
    pathname-as-file pathspec => pathname - -


    -Converts the non-wild pathname designator pathspec to file form, i.e. it returns a pathname which would return a NIL value if fed to DIRECTORY-PATHNAME-P. -
    -


    [Function]
    file-exists-p pathspec => generalized-boolean @@ -178,35 +170,71 @@

    CL-FAD - A portable pathname library for Common Lisp

    directory is returned in directory form as if by PATHNAME-AS-DIRECTORY. -


    [Function] -
    directory-exists-p pathspec => generalized-boolean +


    [Function]
    pathname-absolute-p a => result +

    +

    Returns true if a is an absolute pathname. This simply +tests if a's directory list starts with :ABSOLUTE

    +
    + +


    [Function]
    pathname-equal a b => result +

    + +

    Returns true if a and b +represent the same pathname. This function does not access the +filesystem, it only looks at the components of the two pathnames to +test if they are the same (though by passing both a +and b to probe-file one can make this function test for +file 'sameness'.

    + +

    Equality is defined as:

    + +
      +
    • strings that are string= +
    • symbols (including nil and keywords) which are eql +
    • lists of the same length with equal (as per these rules) elements. +
    + +

    If any of these tree conditions is false for any of the components in +a and b then a +and b are different, otherwise they are the same.

    + +

    NB: This function does not convert name strings to pathnames. So +"foo.txt" and #P"foo.txt" are different pathnames.

    -

    -Checks whether the file named by the pathname designator pathspec -exists and if it is a directory. Returns its truename if this is the -case, NIL otherwise. The truename is returned in directory form as if -by PATHNAME-AS-DIRECTORY.
    -


    [Function] -
    list-directory dirname &key follow-symlinks => list +


    [Function]
    pathname-relative-p a => result +

    +

    Returns true if a is a relative pathname. This simply +tests if a's directory starts +with :RELATIVE.

    +
    -

    -

    -Returns a fresh list of pathnames corresponding to -all files within the directory named by the non-wild pathname designator dirname. The pathnames of sub-directories are returned in -directory form - see PATHNAME-AS-DIRECTORY. -

    -

    - If follow-symlinks is true (which is the - default), then the returned list contains truenames (symlinks will - be resolved) which essentially means that it might also return files - from outside the directory. This works on all platforms. -

    -

    - When follow-symlinks is NIL, it should return the actual directory - contents, which might include symlinks. (This is currently implemented only on SBCL and CCL.) -

    +


    [Function]
    pathname-root-p a => result +

    +

    Returns true if pathname is the root +directory (in other words, a directory which is its own parent).

    +
    + +

    Manipulating pathnames

    + +


    [Function]
    canonical-pathname pathname => result +

    +

    Remove reduntant information from PATHNAME.

    + +

    This simply walks down PATHNAME's +pathname-directory and drops "." directories, removes :back +and its preceding element.

    + +

    NB: This function does not access the filesystem, it only looks at the +values in the pathname and works on their known (or assumed) +meanings.

    + +

    NB: Since this function does not access the filesystem it will only +remove :BACK elements from the path (not :UP +elements). Since some lisps, ccl/sbcl/clisp convert ".." in +pathnames to :UP, and not :BACK, the actual +utility of the function is limited.


    [Function]
    merge-pathnames-as-directory &rest pathnames => result @@ -266,10 +294,17 @@

    CL-FAD - A portable pathname library for Common Lisp

    -


    [Function]
    pathname-absolute-p a => result -

    -

    Returns true if a is an absolute pathname. This simply -tests if a's directory list starts with :ABSOLUTE

    +


    [Function] +
    pathname-as-directory pathspec => pathname +


    +Converts the non-wild pathname designator pathspec to directory form, i.e. it returns a pathname which would return a true value if fed to DIRECTORY-PATHNAME-P. +
    + +


    [Function] +
    pathname-as-file pathspec => pathname + +


    +Converts the non-wild pathname designator pathspec to file form, i.e. it returns a pathname which would return a NIL value if fed to DIRECTORY-PATHNAME-P.


    [Function]
    pathname-directory-pathname pathname => result @@ -282,33 +317,6 @@

    CL-FAD - A portable pathname library for Common Lisp

    per pathname-equal) to it.

    -


    [Function]
    pathname-equal a b => result -

    - -

    Returns true if a and b -represent the same pathname. This function does not access the -filesystem, it only looks at the components of the two pathnames to -test if they are the same (though by passing both a -and b to probe-file one can make this function test for -file 'sameness'.

    - -

    Equality is defined as:

    - -
      -
    • strings that are string= -
    • symbols (including nil and keywords) which are eql -
    • lists of the same length with equal (as per these rules) elements. -
    - -

    If any of these tree conditions is false for any of the components in -a and b then a -and b are different, otherwise they are the same.

    - -

    NB: This function does not convert name strings to pathnames. So -"foo.txt" and #P"foo.txt" are different pathnames.

    - -
    -


    [Function]
    pathname-parent-directory pathname => result

    @@ -324,17 +332,27 @@

    CL-FAD - A portable pathname library for Common Lisp

    -


    [Function]
    pathname-relative-p a => result -

    -

    Returns true if a is a relative pathname. This simply -tests if a's directory starts -with :RELATIVE.

    -
    +

    Traversing directories

    -


    [Function]
    pathname-root-p a => result -

    -

    Returns true if pathname is the root -directory (in other words, a directory which is its own parent).

    +


    [Function] +
    list-directory dirname &key follow-symlinks => list + +


    +

    +Returns a fresh list of pathnames corresponding to +all files within the directory named by the non-wild pathname designator dirname. The pathnames of sub-directories are returned in +directory form - see PATHNAME-AS-DIRECTORY. +

    +

    + If follow-symlinks is true (which is the + default), then the returned list contains truenames (symlinks will + be resolved) which essentially means that it might also return files + from outside the directory. This works on all platforms. +

    +

    + When follow-symlinks is NIL, it should return the actual directory + contents, which might include symlinks. (This is currently implemented only on SBCL and CCL.) +


    [Function] @@ -367,23 +385,7 @@

    CL-FAD - A portable pathname library for Common Lisp

    -


    [Function] -
    delete-directory-and-files dirname&key if-does-not-exist => | - -


    -

    -Recursively deletes all files and directories within the directory -designated by the non-wild pathname designator dirname including -dirname itself. if-does-not-exist must be one of :ERROR or :IGNORE -where :ERROR (the default) means that an error will be signaled if the directory -dirname does not exist. -

    -

    - Warning: this function might remove files from outside the - directory, if the directory that you are deleting contains links to - external files. This is currently fixed for SBCL and CCL. -

    -
    +

    Modifying the file system


    [Function]
    copy-file from to &key overwrite => | @@ -406,6 +408,25 @@

    CL-FAD - A portable pathname library for Common Lisp

    true (which is the default), the function will signal an error if the element types aren't the same.
    +


    [Function] +
    delete-directory-and-files dirname&key if-does-not-exist => | + +


    +

    +Recursively deletes all files and directories within the directory +designated by the non-wild pathname designator dirname including +dirname itself. if-does-not-exist must be one of :ERROR or :IGNORE +where :ERROR (the default) means that an error will be signaled if the directory +dirname does not exist. +

    +

    + Warning: this function might remove files from outside the + directory, if the directory that you are deleting contains links to + external files. This is currently fixed for SBCL and CCL. +

    +
    + +

    The PATH package


    [Package]
    (defpackage path)