<commit_before>#lang scribble/doc
@(require "mz.rkt"
          (for-label framework/preferences
                     racket/runtime-path
                     launcher/launcher
                     setup/dirs))

@(define file-eval (make-base-eval))
@(interaction-eval #:eval file-eval (begin (require racket/file) (define filename (make-temporary-file))))


@title{Filesystem}

@;------------------------------------------------------------------------
@section[#:tag "findpaths"]{Locating Paths}

@defproc[(find-system-path [kind symbol?]) path?]{

Returns a machine-specific path for a standard type of path specified
by @racket[kind], which must be one of the following:

@itemize[

 @item{@indexed-racket['home-dir] --- the current @deftech{user's home
 directory}.

 On all platforms, if the @indexed-envvar{PLTUSERHOME} environment
 variable is defined as a @tech{complete} path, then the path is used
 as the user's home directory.

 On Unix and Mac OS X, when @envvar{PLTUSERHOME} does not apply,
 the user's home directory is determined by
 expanding the path @filepath{~}, which is expanded by first checking
 for a @indexed-envvar{HOME} environment variable. If none is defined,
 the @indexed-envvar{USER} and @indexed-envvar{LOGNAME} environment
 variables are consulted (in that order) to find a user name, and then
 system files are consulted to locate the user's home directory.

 On Windows, when @envvar{PLTUSERHOME} does not apply,
 the user's home directory is the user-specific profile
 directory as determined by the Windows registry. If the registry
 cannot provide a directory for some reason, the value of the
 @indexed-envvar{USERPROFILE} environment variable is used instead, as
 long as it refers to a directory that exists. If @envvar{USERPROFILE}
 also fails, the directory is the one specified by the
 @indexed-envvar{HOMEDRIVE} and @indexed-envvar{HOMEPATH} environment
 variables.  If those environment variables are not defined, or if the
 indicated directory still does not exist, the directory containing
 the current executable is used as the home directory.}

 @item{@indexed-racket['pref-dir] --- the standard directory for
 storing the current user's preferences. On Unix, the directory is
 @filepath{.racket} in the @tech{user's home directory}.  On Windows,
 it is @filepath{Racket} in the @tech{user's home directory} if
 determined by @envvar{PLTUSERHOME}, otherwise in the user's
 application-data folder as specified by the Windows registry; the
 application-data folder is usually @filepath{Application Data} in the
 user's profile directory. On Mac OS X, the preferences directory
 is @filepath{Library/Preferences} in the
 @tech{user's home directory}. The preferences directory might not exist.}

 @item{@indexed-racket['pref-file] --- a file that contains a
 symbol-keyed association list of preference values. The file's
 directory path always matches the result returned for
 @racket['pref-dir]. The file name is @filepath{racket-prefs.rktd} on Unix
 and Windows, and it is @filepath{org.racket-lang.prefs.rktd} on Mac OS
 X. The file's directory might not exist. See also
 @racket[get-preference].}

 @item{@indexed-racket['temp-dir] --- the standard directory for
 storing temporary files. On @|AllUnix|, this is the directory
 specified by the @indexed-envvar{TMPDIR} environment variable, if it
 is defined, otherwise it is the first path that exists among
 @filepath{/var/tmp}, @filepath{/usr/tmp}, and @filepath{/tmp}. On
 Windows, the result is the directory specified by the
 @indexed-envvar{TMP} or @indexed-envvar{TEMP} environment variable,
 if it is defined, otherwise it is the current directory.}

 @item{@indexed-racket['init-dir] --- the directory containing the
 initialization file used by the Racket executable.
 It is the same as the @tech{user's home directory}.}

 @item{@indexed-racket['init-file] --- the file loaded at start-up by
 the Racket executable. The directory part of the
 path is the same path as returned for @racket['init-dir].  The file
 name is platform-specific:

  @itemize[

  @item{@|AllUnix|: @indexed-file{.racketrc}}

  @item{Windows: @indexed-file{racketrc.rktl}}

  ]}

 @item{@indexed-racket['config-dir] --- a directory for
 the installation's configuration. This directory is specified by the
 @indexed-envvar{PLTCONFIGDIR} environment variable, and it can be
 overridden by the @DFlag{config} or @Flag{G} command-line flag.  If no
 environment variable or flag is specified, or if the value is not a
 legal path name, then this directory defaults to an
 @filepath{etc} directory relative to the current executable.
 If the result of @racket[(find-system-path 'config-dir)] is a
 relative path, it is relative to the current executable.
 The directory might not exist.}

 @item{@indexed-racket['addon-dir] --- a directory for
 user-specific Racket configuration, packages, and extension.
 This directory is specified by the
 @indexed-envvar{PLTADDONDIR} environment variable, and it can be
 overridden by the @DFlag{addon} or @Flag{A} command-line flag.  If no
 environment variable or flag is specified, or if the value is not a
 legal path name, then this directory defaults to
 @filepath{Library/Racket} in the @tech{user's home directory} on Mac
 OS X and @racket['pref-dir] otherwise.  The directory might not
 exist.}

 @item{@indexed-racket['doc-dir] --- the standard directory for
 storing the current user's documents. On Unix, it's
 the @tech{user's home directory}.  On Windows, it is the @tech{user's
 home directory} if determined by @envvar{PLTUSERHOME}, otherwise it
 is the user's documents folder as specified by the Windows registry;
 the documents folder is usually @filepath{My Documents} in the user's
 home directory.  On Mac OS X, it's the @filepath{Documents} directory
 in the @tech{user's home directory}.}

 @item{@indexed-racket['desk-dir] --- the directory for the current user's
 desktop. On Unix, it's the @tech{user's home directory}. On
 Windows, it is the @tech{user's home directory} if determined by
 @envvar{PLTUSERHOME}, otherwise it is the user's desktop folder as
 specified by the Windows registry; the desktop folder is usually
 @filepath{Desktop} in the user's home directory. On Mac OS X, it is
 @filepath{Desktop} in the @tech{user's home directory}}

 @item{@indexed-racket['sys-dir] --- the directory containing the
 operating system for Windows. On @|AllUnix|, the
 result is @racket["/"].}

 @item{@indexed-racket['exec-file] --- the path of the Racket
 executable as provided by the operating system for the current
 invocation. For some operating systems, the path can be relative.

 @margin-note{For GRacket, the executable path is the name of a GRacket
 executable.}}

 @item{@indexed-racket['run-file] --- the path of the current
  executable; this may be different from result for
  @racket['exec-file] because an alternate path was provided through a
  @DFlag{name} or @Flag{N} command-line flag to the Racket
  (or GRacket) executable, or because an embedding executable
  installed an alternate path. In particular a ``launcher'' script
  created by @racket[make-racket-launcher] sets this path to the
  script's path.}

 @item{@indexed-racket['collects-dir] --- a path to the main
 collection of libraries (see @secref["collects"]). If this path is
 relative, then it is relative to the executable as reported by
 @racket[(find-system-path 'exec-file)]---though the latter could be a
 soft-link or relative to the user's executable search path, so that
 the two results should be combined with
 @racket[find-executable-path].  The @racket['collects-dir] path is
 normally embedded in the Racket executable, but it can be
 overridden by the @DFlag{collects} or @Flag{X} command-line flag.}

 @item{@indexed-racket['orig-dir] --- the current directory at
 start-up, which can be useful in converting a relative-path result
 from @racket[(find-system-path 'exec-file)] or
 @racket[(find-system-path 'run-file)] to a complete path.}

 ]

@history[#:changed "6.0.0.3" @elem{Added @envvar{PLTUSERHOME}.}]}

@defproc[(path-list-string->path-list [str (or/c string? bytes?)]
                                      [default-path-list (listof path?)])
         (listof path?)]{

Parses a string or byte string containing a list of paths, and returns
a list of path strings. On @|AllUnix|, paths in a path list are
separated by a @litchar{:}; on Windows, paths are separated by a
@litchar{;}, and all @litchar{"}s in the string are discarded. Whenever the path 
list contains an empty path, the list
@racket[default-path-list] is spliced into the returned list of
paths. Parts of @racket[str] that do not form a valid path are not
included in the returned list.}


@defproc[(find-executable-path [program-sub path-string?]
                               [related-sub (or/c path-string? #f) #f]
                               [deepest? any/c #f]) 
         (or/c path? #f)]{

Finds a path for the executable @racket[program-sub], returning
@racket[#f] if the path cannot be found.

If @racket[related-sub] is not @racket[#f], then it must be a relative
path string, and the path found for @racket[program-sub] must be such
that the file or directory @racket[related-sub] exists in the same
directory as the executable. The result is then the full path for the
found @racket[related-sub], instead of the path for the executable.
 
This procedure is used by the Racket executable to find the
standard library collection directory (see @secref["collects"]).  In
this case, @racket[program] is the name used to start Racket and
@racket[related] is @racket["collects"].  The @racket[related-sub]
argument is used because, on @|AllUnix|, @racket[program-sub] may
involve a sequence of soft links; in this case,
@racket[related-sub] determines which link in the chain is relevant.

If @racket[related-sub] is not @racket[#f], then when
@racket[find-executable-path] does not find a @racket[program-sub]
that is a link to another file path, the search can continue with the
destination of the link. Further links are inspected until
@racket[related-sub] is found or the end of the chain of links is
reached. If @racket[deepest?] is @racket[#f] (the default), then the
result corresponds to the first path in a chain of links for which
@racket[related-sub] is found (and further links are not actually
explored); otherwise, the result corresponds to the last link in the
chain for which @racket[related-sub] is found.

If @racket[program-sub] is a pathless name,
@racket[find-executable-path] gets the value of the
@indexed-envvar{PATH} environment variable; if this environment
variable is defined, @racket[find-executable-path] tries each path in
@envvar{PATH} as a prefix for @racket[program-sub] using the search
algorithm described above for path-containing
@racket[program-sub]s. If the @envvar{PATH} environment variable is
not defined, @racket[program-sub] is prefixed with the current
directory and used in the search algorithm above. (On Windows, the
current directory is always implicitly the first item in
@envvar{PATH}, so @racket[find-executable-path] checks the current
directory first on Windows.)}

@;------------------------------------------------------------------------
@section[#:tag "fileutils"]{Files}

@defproc[(file-exists? [path path-string?]) boolean?]{

Returns @racket[#t] if a file (not a directory) @racket[path] exists,
@racket[#f] otherwise.

On Windows, @racket[file-exists?]  reports @racket[#t] for all
variations of the special filenames (e.g., @racket["LPT1"],
@racket["x:/baddir/LPT1"]).}<commit_msg>Fix typo in doc of find-executable-path<commit_after>#lang scribble/doc
@(require "mz.rkt"
          (for-label framework/preferences
                     racket/runtime-path
                     launcher/launcher
                     setup/dirs))

@(define file-eval (make-base-eval))
@(interaction-eval #:eval file-eval (begin (require racket/file) (define filename (make-temporary-file))))


@title{Filesystem}

@;------------------------------------------------------------------------
@section[#:tag "findpaths"]{Locating Paths}

@defproc[(find-system-path [kind symbol?]) path?]{

Returns a machine-specific path for a standard type of path specified
by @racket[kind], which must be one of the following:

@itemize[

 @item{@indexed-racket['home-dir] --- the current @deftech{user's home
 directory}.

 On all platforms, if the @indexed-envvar{PLTUSERHOME} environment
 variable is defined as a @tech{complete} path, then the path is used
 as the user's home directory.

 On Unix and Mac OS X, when @envvar{PLTUSERHOME} does not apply,
 the user's home directory is determined by
 expanding the path @filepath{~}, which is expanded by first checking
 for a @indexed-envvar{HOME} environment variable. If none is defined,
 the @indexed-envvar{USER} and @indexed-envvar{LOGNAME} environment
 variables are consulted (in that order) to find a user name, and then
 system files are consulted to locate the user's home directory.

 On Windows, when @envvar{PLTUSERHOME} does not apply,
 the user's home directory is the user-specific profile
 directory as determined by the Windows registry. If the registry
 cannot provide a directory for some reason, the value of the
 @indexed-envvar{USERPROFILE} environment variable is used instead, as
 long as it refers to a directory that exists. If @envvar{USERPROFILE}
 also fails, the directory is the one specified by the
 @indexed-envvar{HOMEDRIVE} and @indexed-envvar{HOMEPATH} environment
 variables.  If those environment variables are not defined, or if the
 indicated directory still does not exist, the directory containing
 the current executable is used as the home directory.}

 @item{@indexed-racket['pref-dir] --- the standard directory for
 storing the current user's preferences. On Unix, the directory is
 @filepath{.racket} in the @tech{user's home directory}.  On Windows,
 it is @filepath{Racket} in the @tech{user's home directory} if
 determined by @envvar{PLTUSERHOME}, otherwise in the user's
 application-data folder as specified by the Windows registry; the
 application-data folder is usually @filepath{Application Data} in the
 user's profile directory. On Mac OS X, the preferences directory
 is @filepath{Library/Preferences} in the
 @tech{user's home directory}. The preferences directory might not exist.}

 @item{@indexed-racket['pref-file] --- a file that contains a
 symbol-keyed association list of preference values. The file's
 directory path always matches the result returned for
 @racket['pref-dir]. The file name is @filepath{racket-prefs.rktd} on Unix
 and Windows, and it is @filepath{org.racket-lang.prefs.rktd} on Mac OS
 X. The file's directory might not exist. See also
 @racket[get-preference].}

 @item{@indexed-racket['temp-dir] --- the standard directory for
 storing temporary files. On @|AllUnix|, this is the directory
 specified by the @indexed-envvar{TMPDIR} environment variable, if it
 is defined, otherwise it is the first path that exists among
 @filepath{/var/tmp}, @filepath{/usr/tmp}, and @filepath{/tmp}. On
 Windows, the result is the directory specified by the
 @indexed-envvar{TMP} or @indexed-envvar{TEMP} environment variable,
 if it is defined, otherwise it is the current directory.}

 @item{@indexed-racket['init-dir] --- the directory containing the
 initialization file used by the Racket executable.
 It is the same as the @tech{user's home directory}.}

 @item{@indexed-racket['init-file] --- the file loaded at start-up by
 the Racket executable. The directory part of the
 path is the same path as returned for @racket['init-dir].  The file
 name is platform-specific:

  @itemize[

  @item{@|AllUnix|: @indexed-file{.racketrc}}

  @item{Windows: @indexed-file{racketrc.rktl}}

  ]}

 @item{@indexed-racket['config-dir] --- a directory for
 the installation's configuration. This directory is specified by the
 @indexed-envvar{PLTCONFIGDIR} environment variable, and it can be
 overridden by the @DFlag{config} or @Flag{G} command-line flag.  If no
 environment variable or flag is specified, or if the value is not a
 legal path name, then this directory defaults to an
 @filepath{etc} directory relative to the current executable.
 If the result of @racket[(find-system-path 'config-dir)] is a
 relative path, it is relative to the current executable.
 The directory might not exist.}

 @item{@indexed-racket['addon-dir] --- a directory for
 user-specific Racket configuration, packages, and extension.
 This directory is specified by the
 @indexed-envvar{PLTADDONDIR} environment variable, and it can be
 overridden by the @DFlag{addon} or @Flag{A} command-line flag.  If no
 environment variable or flag is specified, or if the value is not a
 legal path name, then this directory defaults to
 @filepath{Library/Racket} in the @tech{user's home directory} on Mac
 OS X and @racket['pref-dir] otherwise.  The directory might not
 exist.}

 @item{@indexed-racket['doc-dir] --- the standard directory for
 storing the current user's documents. On Unix, it's
 the @tech{user's home directory}.  On Windows, it is the @tech{user's
 home directory} if determined by @envvar{PLTUSERHOME}, otherwise it
 is the user's documents folder as specified by the Windows registry;
 the documents folder is usually @filepath{My Documents} in the user's
 home directory.  On Mac OS X, it's the @filepath{Documents} directory
 in the @tech{user's home directory}.}

 @item{@indexed-racket['desk-dir] --- the directory for the current user's
 desktop. On Unix, it's the @tech{user's home directory}. On
 Windows, it is the @tech{user's home directory} if determined by
 @envvar{PLTUSERHOME}, otherwise it is the user's desktop folder as
 specified by the Windows registry; the desktop folder is usually
 @filepath{Desktop} in the user's home directory. On Mac OS X, it is
 @filepath{Desktop} in the @tech{user's home directory}}

 @item{@indexed-racket['sys-dir] --- the directory containing the
 operating system for Windows. On @|AllUnix|, the
 result is @racket["/"].}

 @item{@indexed-racket['exec-file] --- the path of the Racket
 executable as provided by the operating system for the current
 invocation. For some operating systems, the path can be relative.

 @margin-note{For GRacket, the executable path is the name of a GRacket
 executable.}}

 @item{@indexed-racket['run-file] --- the path of the current
  executable; this may be different from result for
  @racket['exec-file] because an alternate path was provided through a
  @DFlag{name} or @Flag{N} command-line flag to the Racket
  (or GRacket) executable, or because an embedding executable
  installed an alternate path. In particular a ``launcher'' script
  created by @racket[make-racket-launcher] sets this path to the
  script's path.}

 @item{@indexed-racket['collects-dir] --- a path to the main
 collection of libraries (see @secref["collects"]). If this path is
 relative, then it is relative to the executable as reported by
 @racket[(find-system-path 'exec-file)]---though the latter could be a
 soft-link or relative to the user's executable search path, so that
 the two results should be combined with
 @racket[find-executable-path].  The @racket['collects-dir] path is
 normally embedded in the Racket executable, but it can be
 overridden by the @DFlag{collects} or @Flag{X} command-line flag.}

 @item{@indexed-racket['orig-dir] --- the current directory at
 start-up, which can be useful in converting a relative-path result
 from @racket[(find-system-path 'exec-file)] or
 @racket[(find-system-path 'run-file)] to a complete path.}

 ]

@history[#:changed "6.0.0.3" @elem{Added @envvar{PLTUSERHOME}.}]}

@defproc[(path-list-string->path-list [str (or/c string? bytes?)]
                                      [default-path-list (listof path?)])
         (listof path?)]{

Parses a string or byte string containing a list of paths, and returns
a list of path strings. On @|AllUnix|, paths in a path list are
separated by a @litchar{:}; on Windows, paths are separated by a
@litchar{;}, and all @litchar{"}s in the string are discarded. Whenever the path 
list contains an empty path, the list
@racket[default-path-list] is spliced into the returned list of
paths. Parts of @racket[str] that do not form a valid path are not
included in the returned list.}


@defproc[(find-executable-path [program path-string?]
                               [related (or/c path-string? #f) #f]
                               [deepest? any/c #f]) 
         (or/c path? #f)]{

Finds a path for the executable @racket[program], returning
@racket[#f] if the path cannot be found.

If @racket[related] is not @racket[#f], then it must be a relative
path string, and the path found for @racket[program] must be such
that the file or directory @racket[related] exists in the same
directory as the executable. The result is then the full path for the
found @racket[related], instead of the path for the executable.
 
This procedure is used by the Racket executable to find the
standard library collection directory (see @secref["collects"]).  In
this case, @racket[program] is the name used to start Racket and
@racket[related] is @racket["collects"].  The @racket[related]
argument is used because, on @|AllUnix|, @racket[program] may
involve a sequence of soft links; in this case,
@racket[related] determines which link in the chain is relevant.

If @racket[related] is not @racket[#f], then when
@racket[find-executable-path] does not find a @racket[program]
that is a link to another file path, the search can continue with the
destination of the link. Further links are inspected until
@racket[related] is found or the end of the chain of links is
reached. If @racket[deepest?] is @racket[#f] (the default), then the
result corresponds to the first path in a chain of links for which
@racket[related] is found (and further links are not actually
explored); otherwise, the result corresponds to the last link in the
chain for which @racket[related] is found.

If @racket[program] is a pathless name,
@racket[find-executable-path] gets the value of the
@indexed-envvar{PATH} environment variable; if this environment
variable is defined, @racket[find-executable-path] tries each path in
@envvar{PATH} as a prefix for @racket[program] using the search
algorithm described above for path-containing
@racket[program]s. If the @envvar{PATH} environment variable is
not defined, @racket[program] is prefixed with the current
directory and used in the search algorithm above. (On Windows, the
current directory is always implicitly the first item in
@envvar{PATH}, so @racket[find-executable-path] checks the current
directory first on Windows.)}

@;------------------------------------------------------------------------
@section[#:tag "fileutils"]{Files}

@defproc[(file-exists? [path path-string?]) boolean?]{

Returns @racket[#t] if a file (not a directory) @racket[path] exists,
@racket[#f] otherwise.

On Windows, @racket[file-exists?]  reports @racket[#t] for all
variations of the special filenames (e.g., @racket["LPT1"],
@racket["x:/baddir/LPT1"]).}
{'fraction_non_alphanumeric': 0.1074519646875541, 'fraction_numerical': 0.0005193006750908776, 'mean_word_length': 4.097948378557247, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5901055', 'n_tokens_mistral': 6732, 'n_tokens_neox': 6500, 'n_words': 2874}