On this page:
3.1 GUI Module Path Selection
get-module-path-from-user
3.2 Module Path Selection Completion Computation
find-module-path-completions
find-module-path-completions/  explicit-cache
alternate-racket-clcl/  clcp
current-library-collection-links-info/  c
current-library-collection-paths-info/  c
pkg-dirs-info/  c

3 Module Path Selection

DrRacket provides two APIs for prompting the user to select a module path. One that uses the racket/gui library with a dialog box and one, lower-level, for use with another UI that provides just the information needed for completions.

3.1 GUI Module Path Selection

 (require drracket/get-module-path)
  package: drracket-tool-lib

procedure

(get-module-path-from-user 
  [#:init init 
  #:pref pref 
  #:dir? dir?] 
  #:current-directory current-directory) 
  
(if dir?
    (or/c (listof path?) #f)
    (or/c path? #f))
  init : string? = ""
  pref : (or/c symbol? #f) = #f
  dir? : boolean? = #f
  current-directory : (or/c path-string? #f)
Opens a dialog box that facilitates choosing a path in the file system accessible via a module.

The user types a partial require path into the dialog and is shown completions of the require path and which paths they correspond to. (The initial content of the field where the user types is init.) Selecting one of the completions causes this function to return with the path of the selected one. If the dir? argument is #t, then the require path might not be complete, in which case the result is a list of directory paths corresponding to the directories where the partial require paths points. If the result is #f, then the user canceled the dialog.

The dialog also has an optional field where the path to some different racket binary than the one currently running. If that is filled in, then the dialog shows completions corresponding to how require would behave in that other racket binary. When that text field is edited, the pref is used with preferences:set and preferences:get to record its value so it persists across calls to get-module-path-from-user.

3.2 Module Path Selection Completion Computation

 (require drracket/find-module-path-completions)
  package: drracket-tool-text-lib

procedure

(find-module-path-completions dir)

  (-> string? (listof (list/c string? path?)))
  dir : path-string?
This is the completion computing function for get-module-path-from-user.

The dir argument specifies a directory for relative require paths.

The result is a function that closes over some local state that is used to cache information to speed up repeated queries. (This cache should not be used across interactions with the user as it captures details about the current file system’s directory and file layout.)

The result function’s argument is the string the user has typed and the the result function’s result is a new set of completions. Each element of the list corresponds to a completion. The string? portion of each element is the complete require and the path? portion is the path it matches in the filesystem. The get-module-path-from-user function shows the strings to the user and uses the paths to decide how to handle “return” keystrokes (and clicking on the “OK” button). If the path is a directory, then a “return” keystroke with descend into that directory (replacing the place where the user typed with the string portion of that element). If the path is not a directory, then return closes the dialog and returns the path.

Use path->relative-string/library to turn the paths into strings to show the user as potential completions.

procedure

(find-module-path-completions/explicit-cache 
  str 
  dir 
  #:pkg-dirs-cache pkg-dirs-cache 
  [#:alternate-racket alternate-racket]) 
  (listof (list/c string? path?))
  str : string?
  dir : path-string?
  pkg-dirs-cache : (box/c (or/c #f pkg-dirs-info/c))
  alternate-racket : 
(or/c #f
      path-string?
      (list/c
       current-library-collection-links-info/c
       current-library-collection-paths-info/c
       pkg-dirs-info/c))
   = #f
This is a version of find-module-path-completions that explicates the pkg-dirs-cache argument and supports using a different racket binary (as discussed in get-module-path-from-user).

The pkg-dirs-cache argument should initially be (box #f); it is filled in with the cached information and then the filled in box can be used on subsequent calls.

Use alternate-racket-clcl/clcp to get the values for the alternate-racket argument in the case that an alternate racket is used. Pass #f for the current racket.

procedure

(alternate-racket-clcl/clcp alternate-racket 
  pkg-dirs-cache) 
  
current-library-collection-links-info/c
current-library-collection-paths-info/c
pkg-dirs-info/c
  alternate-racket : path-string?
  pkg-dirs-cache : (box/c (or/c #f pkg-dirs-info/c))
Computes the information needed for completions by calling out to the external racket binary alternate-racket. Use the same pkg-dirs-cache argument as with find-module-path-completions/explicit-cache.

A contract specifying what information used by this library relevant to the current library links.
A contract specifying what information used by this library relevant to the current library collections.
A contract specifying what information used by this library relevant to the pkg directories.