3.2 Importing and Exporting: require and provide (original) (raw)
3.2 Importing and Exporting: require and provide🔗ℹ
Imports: require in The Racket Guide introduces require.
(require require-spec ...) require-spec = module-path | (only-in require-spec id-maybe-renamed ...) (except-in require-spec id ...) (prefix-in prefix-id require-spec) (rename-in require-spec [orig-id bind-id] ...) (combine-in require-spec ...) (relative-in module-path require-spec ...) (only-meta-in phase-level require-spec ...) (only-space-in space require-spec ...) (for-syntax require-spec ...) (for-template require-spec ...) (for-label require-spec ...) (for-meta phase-level require-spec ...) (for-space space require-spec ...) derived-require-spec module-path = root-module-path (submod root-module-path submod-path-element ...) (submod "." submod-path-element ...) (submod ".." submod-path-element ...) root-module-path = (quote id) rel-string (lib rel-string ...+) id (file string) (planet id) (planet string) (planet rel-string (user-string pkg-string vers) rel-string ...) submod-path-element = id ".." id-maybe-renamed = id [orig-id bind-id] phase-level = exact-integer #f space = id #f vers = nat nat minor-vers minor-vers = nat (nat nat) (= nat) (+ nat) (- nat)
A require-spec designates a particular set of identifiers to be bound in the importing context. Each identifier is mapped to a particular export of a particular module; the identifier to bind may be different from the symbolic name of the originally exported identifier. Each identifier also binds at a particular phase level and in a binding space.
No identifier can be bound multiple times in a given combination ofphase level and binding space by an import, unless all of the bindings refer to the same original definition in the same module. In a module context, an identifier can be either imported or defined for a givenphase level and binding space, but not both.
The syntax of require-spec can be extended viadefine-require-syntax, and when multiplerequire-specs are specified in a require, the bindings of each require-spec are visible for expanding laterrequire-specs. The pre-defined forms (as exported byracket/base) are as follows:
Imports all exported bindings from the named module, using the export name for the local identifiers. (See below for information on module-path.) The lexical context of the module-path form determines the context of the introduced identifiers, adding a space scope for exports in a particular binding space, and in each export’sphase level.
If any identifier provided by module-path has a symbol form that is uninterned, the identifier is not imported (i.e., it is impossible to import a binding for an uninterned symbol). This restriction is intended to avoid compilation differences depending on whether a module has been saved to a file or not (seePrinting Compiled Code).
(only-in require-spec id-maybe-renamed ...)
Like require-spec, but constrained to those exports for which the identifiers to bind match id-maybe-renamed: asid or as orig-id in [orig-id bind-id]. If the id or orig-id of any id-maybe-renamedis not in the set that require-spec describes, a syntax error is reported.
Examples:
> tcp-listen #procedure:tcp-listen > my-accept #procedure:tcp-accept > tcp-accept tcp-accept: undefined; cannot reference an identifier before its definition in module: top-level
(except-in require-spec id ...)
Likerequire-spec, but omitting those imports for whichids are the identifiers to bind; if any id is not in the set that require-spec describes, a syntax error is reported.
Examples:
> tcp-accept #procedure:tcp-accept > tcp-listen tcp-listen: undefined; cannot reference an identifier before its definition in module: top-level
(prefix-in prefix-id require-spec)
Likerequire-spec, but adjusting each identifier to be bound by prefixing it with prefix-id. The lexical context of theprefix-id is ignored, and instead preserved from the identifiers before prefixing.
Examples:
> (require (prefix-in tcp: racket/tcp)) > tcp:tcp-accept #procedure:tcp-accept > tcp:tcp-listen #procedure:tcp-listen A syntax property with the key'import-or-export-prefix-ranges is added to the local identifier in the expanded form of require.
Changed in version 8.9.0.5 of package base: Added the 'import-or-export-prefix-rangessyntax property.
(rename-in require-spec [orig-id bind-id] ...)
Like require-spec, but replacing the identifier to bind orig-id with bind-id; if anyorig-id is not in the set that require-specdescribes, a syntax error is reported.
Examples:
> accept #procedure:tcp-accept > listen #procedure:tcp-listen
(combine-in require-spec ...)
The union of the require-specs. If two or more imports from therequire-specs have the same identifier name but they do not refer to the same original binding, a syntax error is reported.
Examples:
(relative-in module-path require-spec ...)
Like the union of the require-specs, but each relative module path in a require-spec is treated as relative to module-path instead of the enclosing context.
The require transformer that implements relative-insets current-require-module-path to adjust module paths in the require-specs.
(only-meta-in phase-level require-spec ...)
Like the combination of require-specs, but removing any binding that is not for phase-level, where #f forphase-level corresponds to the label phase level.
The following example imports bindings only at phase level 1, the transform phase:
> (require (only-meta-in 1 'nest)) > (desc) 2 3 > num-eggs num-eggs: undefined; cannot reference an identifier before its definition in module: top-level The following example imports only bindings at phase level 0, the normal phase.
> (require (only-meta-in 0 'nest)) > num-eggs 2
(only-space-in space require-spec ...)
Like the combination of require-specs, but removing any binding that is not provided for the binding space identifier byspace—which is normally an identifier, but #f forspace corresponds to the default binding space.
Added in version 8.2.0.3 of package base.
(for-meta phase-level require-spec ...)
Like the combination ofrequire-specs, but the bindings specified by each require-spec are shifted by phase-level. Thelabel phase level corresponds to #f, and a shifting combination that involves #f produces #f.
Examples:
> (require (for-meta 0 'nest)) > num-eggs 2 > (require (for-meta 1 'nest)) > (roost) 2
(for-syntax require-spec ...)
(for-template require-spec ...)
(for-label require-spec ...)
Same as(for-meta #f require-spec ...). If an identifier in any of therequire-specs is bound at more than one phase level, a syntax error is reported.
(for-space space require-spec ...)
Like the combination ofrequire-specs, but the bindings specified by each require-spec are moved to the binding spacespecified by space—which is normally an identifier, but #f for space corresponds to thedefault binding space.
A binding is moved to the new space by removing the scope for the space originally implied by require-spec, if any, and adding the scope for space, if any.
Added in version 8.2.0.3 of package base.
See define-require-syntaxfor information on expanding the set of require-specforms.
A module-path identifies a module, either a root module or a submodule that is declared lexically within another module. A root module is identified either through a concrete name in the form of an identifier, or through an indirect name that can trigger automatic loading of the module declaration. Except for the (quote id) case below, the actual resolution of a root module path is up to the currentmodule name resolver (seecurrent-module-name-resolver), and the description below corresponds to the default module name resolver.
Refers to a submodule previously declared with the nameid or a module previously declared interactively with the nameid. When id refers to a submodule, (quote id)is equivalent to (submod "." id).
Examples:
; a module declared interactively as test: > (require 'test)
A path relative to the containing source (as determined by current-load-relative-directory orcurrent-directory). Regardless of the current platform,rel-string is always parsed as a Unix-format relative path:/ is the path delimiter (multiple adjacent /s are not allowed), .. accesses the parent directory, and . accesses the current directory. The path cannot be empty or contain a leading or trailing slash, path elements before than the last one cannot include a file suffix (i.e., a. in an element other than . or ..), and the only allowed characters are ASCII letters, ASCII digits,-, +, _, ., /, and%. Furthermore, a % is allowed only when followed by two lowercase hexadecimal digits, and the digits must form a number that is not the ASCII value of a letter, digit, -,+, or _.
The % provision is intended to support a one-to-one encoding of arbitrary strings as path elements (after UTF-8 encoding). Such encodings are not decoded to arrive at a filename, but instead preserved in the file access.
If rel-string ends with a ".ss" suffix, it is converted to a ".rkt" suffix. The compiled-load handler may reverse that conversion if a ".rkt" file does not exist and a ".ss" exists.
Examples:
; a module named "x.rkt" in the same ; directory as the enclosing module's file: > (require "x.rkt") ; a module named "x.rkt" in the parent directory ; of the enclosing module file's directory: > (require "../x.rkt")
A path to a module installed into a collection (see Libraries and Collections). The rel-strings inlib are constrained similar to the plain rel-stringcase, with the additional constraint that a rel-stringcannot contain . or .. directory indicators.
The specific interpretation of the path depends on the number and shape of the rel-strings:
- If a single rel-string is provided, and if it consists of a single element (i.e., no /) with no file suffix (i.e., no .), then rel-string names acollection, and "main.rkt" is the library file name.
Examples:
; the main swindle library: > (require (lib "swindle")) ; the same: > (require (lib "swindle/main.rkt")) - If a single rel-string is provided, and if it consists of multiple /-separated elements, then each element up to the last names a collection, subcollection, etc., and the last element names a file. If the last element has no file suffix, ".rkt" is added, while a ".ss"suffix is converted to ".rkt".
Examples:
; "turbo.rkt" from the "swindle" collection: > (require (lib "swindle/turbo")) ; the same: > (require (lib "swindle/turbo.rkt")) ; the same: > (require (lib "swindle/turbo.ss")) - If a single rel-string is provided, and if it consists of a single element with a file suffix (i.e, with a .), then rel-string names a file within the "mzlib" collection. A ".ss"suffix is converted to ".rkt". (This convention is for compatibility with older version of Racket.)
Examples:
; "tar.rkt" module from the "mzlib" collection: > (require (lib "tar.ss")) - Otherwise, when multiple rel-strings are provided, the first rel-string is effectively moved after the others, and all rel-strings are appended with /separators. The resulting path names a collection, then subcollection, etc., ending with a file name. No suffix is added automatically, but a ".ss" suffix is converted to".rkt". (This convention is for compatibility with older version of Racket.)
Examples:
; "tar.rkt" module from the "mzlib" collection: > (require (lib "tar.ss" "mzlib"))
A shorthand for a lib form with a singlerel-string whose characters are the same as in the symbolic form of id. In addition to the constraints of a lib rel-string, id must not contain ..
Example:
Similar to the plain rel-stringcase, but string is a path—possibly absolute—using the current platform’s path conventions and expand-user-path. A ".ss" suffix is converted to ".rkt".
Example:
(planet id) (planet string) (planet rel-string (user-string pkg-string vers) rel-string ...) Specifies a library available via the PLaneT server.
The first form is a shorthand for the last one, where the id’s character sequence must match the following ‹spec› grammar:
‹spec› ::= ‹owner› / ‹pkg› ‹lib› ‹owner› ::= ‹elem› ‹pkg› ::= ‹elem› | ‹elem› : ‹version› ‹version› ::= ‹int› | ‹int› : ‹minor› ‹minor› ::= ‹int› | <= ‹int› >= ‹int› = ‹int› | ‹int› - ‹int› ‹lib› ::= ‹empty› | / ‹path› ‹path› ::= ‹elem› | ‹elem› / ‹path› and where an ‹elem› is a non-empty sequence of characters that are ASCII letters, ASCII digits, -, +,_, or % followed by lowercase hexadecimal digits (that do not encode one of the other allowed characters), and an‹int› is a non-empty sequence of ASCII digits. As this shorthand is expended, a ".plt" extension is added to‹pkg›, and a ".rkt" extension is added to‹path›; if no ‹path› is included, "main.rkt"is used in the expansion.
A (planet string) form is like a (planet id) form with the identifier converted to a string, except that thestring can optionally end with a file extension (i.e., a.) for a ‹path›. A ".ss" file extension is converted to ".rkt".
In the more general last form of a planet module path, therel-strings are similar to the lib form, except that the (user-string pkg-string vers) names aPLaneT-based package instead of a collection. A version specification can include an optional major and minor version, where the minor version can be a specific number or a constraint:(nat nat) specifies an inclusive range, (= nat) specifies an exact match,(+ nat) specifies a minimum version and is equivalent to just nat, and(- nat) specifies a maximum version. The =, +, and -identifiers in a minor-version constraint are recognized symbolically.
Examples:
; "main.rkt" in package "farm" by "mcdonald": > (require (planet mcdonald/farm)) ; "main.rkt" in version >= 2.0 of "farm" by "mcdonald": > (require (planet mcdonald/farm:2)) ; "main.rkt" in version >= 2.5 of "farm" by "mcdonald": > (require (planet mcdonald/farm:2:5)) ; "duck.rkt" in version >= 2.5 of "farm" by "mcdonald": > (require (planet mcdonald/farm:2:5/duck))
(submod root-module-path submod-path-element ...) (submod "." submod-path-element ...) (submod ".." submod-path-element ...) Identifies a submodule within the module specified by root-module-pathor relative to the current module in the case of (submod "." ....), where (submod ".." submod-path-element ...) is equivalent to(submod "." ".." submod-path-element ...). Submodules have symbolic names, and a sequence of identifiers as submod-path-elements determine a path of successively nested submodules with the given names. A ".." as a submod-path-element names the enclosing module of a submodule, and it’s intended for use in (submod "." ....)and (submod ".." ....) forms.
As require prepares to handle a sequence ofrequire-specs, it logs a “prefetch” message to thecurrent logger at the 'info level, using the name'module-prefetch, and including message data that is a list of two elements: a list of module paths that appear to be imported, and a directory path to use for relative module paths. The logged list of module paths may be incomplete, but a compilation manager can use approximate prefetch information to start on compilations in parallel.
Changed in version 6.0.1.10 of package base: Added prefetch logging.
(local-require require-spec ...)
Examples:
> (let () (local-require racket/control) fcontrol) #procedure:fcontrol > fcontrol fcontrol: undefined; cannot reference an identifier before its definition in module: top-level
(provide provide-spec ...) provide-spec = id | (all-defined-out) (all-from-out module-path ...) (rename-out [orig-id export-id] ...) (except-out provide-spec provide-spec ...) (prefix-out prefix-id provide-spec) (struct-out id) (combine-out provide-spec ...) (protect-out provide-spec ...) (for-meta phase-level provide-spec ...) (for-syntax provide-spec ...) (for-template provide-spec ...) (for-label provide-spec ...) (for-space space provide-spec ...) derived-provide-spec phase-level = exact-integer #f space = id #f
A provide-spec indicates one or more bindings to provide. For each exported binding, the external name is a symbol that can be different from the symbolic form of the identifier that is bound within the module. Also, each export is drawn from a particularphase level and exported at the same phase level; by default, the relevant phase level is the number ofbegin-for-syntax forms that enclose the provideform. Finally, each export is drawn from a binding spaceand exported at the same binding space.
The syntax of provide-spec can be extended by bindings toprovide transformers or provide pre-transformers, such as via define-provide-syntax, but the pre-defined forms are as follows.
Exports id, which must be boundwithin the module (i.e., either defined or imported) at the relevantphase level and binding space. The symbolic form ofid is used as the external name, and the symbolic form of the defined or imported identifier must match (otherwise, the external name could be ambiguous).
Examples:
> (require 'nest) > num-eggs 2 If id has a transformer binding to a rename transformer, then the transformer affects the exported binding. Seemake-rename-transformer for more information.
Exports all identifiers that are defined at the relevant phase level within the exporting module, and that have the same lexical context as the(all-defined-out) form, excluding bindings to rename transformers where the target identifier has the'not-provide-all-defined syntax property. The external name for each identifier is the symbolic form of the identifier. Only identifiers accessible from the lexical context of the (all-defined-out) form are included; that is, macro-introduced imports are not re-exported, unless the(all-defined-out) form was introduced at the same time.
Examples:
> (require 'nest) > num-eggs 2
(all-from-out module-path ...)
Exports all identifiers that are imported into the exporting module using arequire-spec built on each module-path (seeImporting and Exporting: require and provide) with no phase-level shift. The symbolic name for export is derived from the name that is bound within the module, as opposed to the symbolic name of the export from eachmodule-path. Only identifiers accessible from the lexical context of the module-path are included; that is, macro-introduced imports are not re-exported, unless themodule-path was introduced at the same time.
Examples:
> (module hen-house racket (require 'nest) (provide (all-from-out 'nest))) > (require 'hen-house) > num-eggs 2
(rename-out [orig-id export-id] ...)
Exports eachorig-id, which must be bound within the module at the relevant phase level and binding space. The symbolic name for each export isexport-id instead of orig-id.
Examples:
> (require 'nest) > num-eggs 2 > count count: undefined; cannot reference an identifier before its definition in module: top-level
(except-out provide-spec provide-spec ...)
Like the first provide-spec, but omitting the bindings listed in each subsequent provide-spec. If one of the latter bindings is not included in the initial provide-spec, a syntax error is reported. The symbolic export name information in the latterprovide-specs is ignored; only the bindings are used.
Examples:
> (require 'nest) > num-eggs 2 > num-chicks num-chicks: undefined; cannot reference an identifier before its definition in module: top-level
(prefix-out prefix-id provide-spec)
Like provide-spec, but with each symbolic export name fromprovide-spec prefixed with prefix-id.
Examples:
> (require 'nest) > chicken:num-eggs 2 A syntax property with the key'import-or-export-prefix-ranges is added to the exported identifier in the expanded form of provide.
Changed in version 8.9.0.5 of package base: Added the 'import-or-export-prefix-rangessyntax property.
Exports the bindings associated with a structure type id. Typically, id is bound with(struct id ....); more generally, id must have atransformer binding of structure-type information at the relevantphase level; see Structure Type Transformer Binding. Furthermore, for each identifier mentioned in the structure-type information, the enclosing module must define or import one identifier that isfree-identifier=?. If the structure-type information includes a super-type identifier, and if the identifier has atransformer binding of structure-type information, the accessor and mutator bindings of the super-type are notincluded by struct-out for export.
Examples:
> (require 'nest) > (egg-color (egg 'blue 10)) 'blue
(combine-out provide-spec ...)
The union of theprovide-specs.
Examples:
> (require 'nest) > num-eggs 2 > num-chicks 1
(protect-out provide-spec ...)
Like the union of theprovide-specs, except that the exports are protected: requiring modules may refer to these bindings, but may not extract these bindings from macro expansions or access them via eval without access privileges. For more details, see Code Inspectors. The provide-spec must specify only bindings that are defined within the exporting module.
Examples:
> (define weak-inspector (make-inspector (current-code-inspector))) > (require 'nest) > (list num-eggs num-chicks) '(2 3) > (weak-eval 'num-eggs) 2 > (weak-eval 'num-chicks) ?: access disallowed by code inspector to protected variable from module: 'nest at: num-chicks
(for-meta phase-level provide-spec ...)
Like the union of theprovide-specs, but adjusted to apply to the phase level specified by phase-level relative to the current phase level (where #f corresponds to the label phase level). In particular, an id or rename-out form as a provide-spec refers to a binding atphase-level relative to the current level, anall-defined-out exports only definitions atphase-level relative to the current phase level, and anall-from-out exports bindings imported with a shift byphase-level.
Examples:
> (require 'nest) > (test-eggs) Eggs are 2 0 > chickens 3 eval:7:0: provide: provided identifier is not defined or required at: eggs in: (provide (for-syntax eggs) chickens) > (require (for-meta 2 racket/base) (for-syntax 'nest2)) Eggs are 2 > (test) 0
(for-syntax provide-spec ...)
(for-template provide-spec ...)
(for-label provide-spec ...)
(for-space space provide-spec ...)
Like the union of theprovide-specs, but adjusted to apply to the binding spacespecified by space—where space is either an identifier or #f for the default binding space. In particular, an idor rename-out form as a provide-spec refers to a binding in space, an all-defined-out exports only definitions inspace, and an all-from-out exports bindings imported into space.
When providing a binding for a non-default binding space, normally a module should also provide a binding for the default binding space, where the default-space binding represents the intended meaning of the identifier. When a module later imports the same name in different spaces from modules that adhere to this convention, then if the two modules also (re)export the same binding for the name in the default space, the imports are likely consistent. If the two modules export different bindings for the name in the default space, then attempting to import both modules will trigger an error about conflicting imports, and a programmer can explicitly resolve the mismatch.
Added in version 8.2.0.3 of package base.
See define-provide-syntaxfor information on expanding the set of provide-spec forms.
Each export specified within a module must have a distinct symbolic export name, though the same binding can be specified with the multiple symbolic names.
(for-meta phase-level require-spec ...)
(for-syntax require-spec ...)
(for-template require-spec ...)
(for-label require-spec ...)
(for-space space require-spec ...)
(#%require raw-require-spec ...) raw-require-spec = phaseless-spec | (for-meta phase-level raw-require-spec ...) (for-syntax raw-require-spec ...) (for-template raw-require-spec ...) (for-label raw-require-spec ...) (just-meta phase-level raw-require-spec ...) (portal portal-id content) phase-level = exact-integer #f phaseless-spec = spaceless-spec (for-space space phaseless-spec ...) (just-space space spaceless-spec ...) space = id #f spaceless-spec = raw-module-path (only raw-module-path id ...) (prefix prefix-id raw-module-path) (all-except raw-module-path id ...) (prefix-all-except prefix-id raw-module-path id ...) (rename raw-module-path local-id exported-id) raw-module-path = raw-root-module-path (submod raw-root-module-path id ...+) (submod "." id ...+) raw-root-module-path = (quote id) rel-string (lib rel-string ...) id (file string) (planet rel-string (user-string pkg-string vers ...)) literal-path
The primitive import form, to which require expands. Araw-require-spec is similar to a require-spec in arequire form, except that the syntax is more constrained, not composable, and not extensible. Also, sub-form names likefor-syntax and lib are recognized symbolically, instead of via bindings. Some nested constraints are not formalized in the grammar above:
- a just-meta form cannot appear within ajust-meta form;
- a for-meta, for-syntax,for-template, or for-label form cannot appear within a for-meta,for-syntax, for-template, orfor-label form; and
- a for-space form cannot appear within afor-space form.
- a portal form cannot appear within ajust-meta form.
Except for the portal form, eachraw-require-spec corresponds to the obviousrequire-spec, but the rename sub-form has the identifiers in reverse order compared to rename-in.
For most raw-require-specs, the lexical context of theraw-require-spec determines the context of introduced identifiers. The exception is the rename sub-form, where the lexical context of the local-id is preserved.
A literal-path as a raw-root-module-path corresponds to a path in the sense of path?. Since path values are never produced by read-syntax, they appear only in programmatically constructed expressions. They also appear naturally as arguments to functions such as namespace-require, with otherwise take a quoted raw-module-spec.
The portal form provides a way to define portal syntax at any phase level. A (portal portal-id content), defines portal-id to portal syntax withcontent effectively quoted to serve as its content.
Changed in version 8.2.0.3 of package base: Added for-spaceand just-space.
Changed in version 8.3.0.8: Added portal.
(#%provide raw-provide-spec ...) raw-provide-spec = phaseless-spec | (for-meta phase-level phaseless-spec ...) (for-syntax phaseless-spec ...) (for-label phaseless-spec ...) (protect raw-provide-spec ...) phase-level = exact-integer #f phaseless-spec = spaceless-spec (for-space space spaceless-spec ...) (protect phaseless-spec ...) space = id #f spaceless-spec = id (rename local-id export-id) (struct struct-id (field-id ...)) (all-from raw-module-path) (all-from-except raw-module-path id ...) (all-defined) (all-defined-except id ...) (prefix-all-defined prefix-id) (prefix-all-defined-except prefix-id id ...) (protect spaceless-spec ...) (expand (id . datum)) (expand (id . datum) orig-form)
The primitive export form, to which provide expands. Araw-module-path is as for #%require. Aprotect sub-form cannot appear within aprotect sub-form.
Like #%require, the sub-form keywords for #%provideare recognized symbolically, and nearly everyraw-provide-spec has an obvious equivalentprovide-spec via provide, with the exception of thestruct and expand sub-forms.
A (struct struct-id (field-id ...))sub-form expands to struct-id,make-struct-id,struct:struct-id,struct-id?,struct-id-field-id for eachfield-id, andset-struct-id-field-id!for each field-id. The lexical context of thestruct-id is used for all generated identifiers.
Unlike #%require, the #%provide form is macro-extensible via an explicit expand sub-form; the(id . datum) part is locally expanded as an expression (even though it is not actually an expression), stopping when abegin form is produced; if the expansion result is(begin raw-provide-spec ...), it is spliced in place of theexpand form, otherwise a syntax error is reported. If an orig-form part is provided, then it is used instead of the#%provide form when raising syntax errors, such as a “provide identifier is not defined” error. The expandsub-form is not normally used directly; it provides a hook for implementing provide and provide transformers.
The all-from and all-from-except forms re-export only identifiers that are accessible in lexical context of the all-from or all-from-except form itself. That is, macro-introduced imports are not re-exported, unless the all-from or all-from-except form was introduced at the same time. Similarly, all-defined and its variants export only definitions accessible from the lexical context of the spaceless-spec form.
Changed in version 8.2.0.3 of package base: Added for-space.
Changed in version 8.2.0.5: Added orig-form support to expand.
3.2.1 Additional require Forms🔗ℹ
The bindings documented in this section are provided by the racket/require library, not racket/base or racket.
The following forms support more complex selection and manipulation of sets of imported identifiers.
(matching-identifiers-in regexp require-spec)
Like require-spec, but including only imports whose names match regexp. The regexp must be a literal regular expression (see Regular Expressions).
Examples:
> (require racket/require) > (require (matching-identifiers-in #rx"\\w*fish" 'zoo)) > tunafish 1 > swordfish 2 > blowfish 3 > monkey monkey: undefined; cannot reference an identifier before its definition in module: top-level
(subtract-in require-spec subtracted-spec ...)
Like require-spec, but omitting those imports that would be imported by one of the subtracted-specs.
Examples:
> (module solar-system racket (require 'earth 'mars) (provide (all-from-out 'earth) (all-from-out 'mars))) > (require racket/require) > (require (subtract-in 'solar-system 'earth)) > land land: undefined; cannot reference an identifier before its definition in module: top-level > aliens 4
(filtered-in proc-expr require-spec)
Applies an arbitrary transformation on the import names (as strings) of require-spec. The proc-expr must evaluate at expansion time to a single-argument procedure, which is applied on each of the names from require-spec. For each name, the procedure must return either a string for the import’s new name or#f to exclude the import.
For example,
imports only bindings from racket/base that match the pattern #rx"^[a-z-]+$", and it converts the names to “camel case.”
Specifies paths to modules named by the rel-strings similar to using the rel-strings directly, except that if a required module file is not found relative to the enclosing source, it is searched for in the parent directory, and then in the grand-parent directory, etc., all the way to the root directory. The discovered path relative to the enclosing source becomes part of the expanded form.
This form is useful in setting up a “project environment.” For example, using the following "config.rkt" file in the root directory of your project:
and using "utils/in-here.rkt" under the same root directory:
then path-up works for any other module under the project directory to find "config.rkt":
(require racket/require (path-up "config.rkt") (utils-in foo))
Note that the order of requires in the example is important, as each of the first two bind the identifier used in the following.
An alternative in this scenario is to use path-up directly to find the utility module:
(require racket/require (path-up "utils/foo.rkt"))
but then sub-directories that are called"utils" override the one in the project’s root. In other words, the previous method requires only a single unique name.
(multi-in subs ...+) subs = sub-path | (sub-path ...) sub-path = rel-string id
Specifies multiple files to be required from a hierarchy of directories or collections. The set of required module paths is computed as the Cartesian product of the subs groups, where eachsub-path is combined with other sub-paths in order using a / separator. A sub-path as a subsis equivalent to (sub-path). All sub-paths in a givenmulti-in form must be either strings or identifiers.
Examples:
| (require (multi-in racket (dict list))) |
|---|
| is equivalent to (require racket/dict racket/list) |
| (require (multi-in "math" "matrix" "utils.rkt")) |
| is equivalent to (require "math/matrix/utils.rkt") |
| (require (multi-in "utils" ("math.rkt" "matrix.rkt"))) |
| is equivalent to (require "utils/math.rkt" "utils/matrix.rkt") |
| (require (multi-in ("math" "matrix") "utils.rkt")) |
| is equivalent to (require "math/utils.rkt" "matrix/utils.rkt") |
| (require (multi-in ("math" "matrix") ("utils.rkt" "helpers.rkt"))) |
| is equivalent to (require "math/utils.rkt" "math/helpers.rkt" "matrix/utils.rkt" "matrix/helpers.rkt") |
3.2.2 Additional provide Forms🔗ℹ
The bindings documented in this section are provided by the racket/provide library, not racket/base or racket.
(matching-identifiers-out regexp provide-spec)
Likeprovide-spec, but including only exports of bindings with an external name that matches regexp. The regexpmust be a literal regular expression (see Regular Expressions).
(filtered-out proc-expr provide-spec)
Analogous to filtered-in, but for filtering and renaming exports.
For example,
exports only bindings that match the pattern #rx"^[a-z-]+$", and it converts the names to “camel case.”