6 Package Definitions

8.12

6 Package Definitions🔗ℹ

package: denxi

A package definition is Racket code using the PACKAGE_DEFINITION_MODULE_LANG module language, namely denxi/pkgdef. Since Racket source code may be viewed as data, package definitions may appear in memory as syntax objects or lists.

When evaluated, a package definition performs a collection pass that applies all terms found in Package Definition Terms to empty-package. The result is a new package, provided using (provide pkg).

6.1 Package Definition Terms🔗ℹ

syntax
(define id value)
(define (id formals ...) body ...)

define is allowed in module context to bind procedures and common values. All defines are hoisted above all other terms before evaluation.

syntax
(description string-fragment ...)

string-fragment : non-empty-string?

Sets package-description.

This form will gather all string fragments into a single string, so that you can divide up the message in source code.

Note that the string fragments are concatenated as-is, so take care with whitespace placement.

(description "This is a "
"string that will"
" appear as one line.")

syntax
(edition str)

str : non-empty-string?

Sets package-edition.

syntax
(input name)
(input name plinth)

Adds a package input to package-inputs. A form corresponds exactly to an application of make-package-input.

syntax
(metadatum id value)

Adds a string with 'id to package-metadata.

syntax
(name str)

str : non-empty-string?

Sets package-name.

syntax
(os-support os ...)

Sets package-os-support.

Each os must be a possible value of (system-type 'os).

syntax
(output name body ...)

name : non-empty-string?

Adds a package output to package-outputs.

Blank outputs like (output "name") are acceptable, but are only useful when expecting cached outputs.

syntax
(provider str)

str : non-empty-string?

Sets package-provider.

syntax
(racket-versions supported ...)

supported = (min-version max-version)
| exact-version

Sets package-racket-versions.

Each supported subform may be an inclusive Racket version range or an exact Racket version, e.g. (racket-versions ("6.0" "7.7.0.5") "5.4").

You may replace any version string with "*" to remove a bound. This way, (racket-versions ("6.0" "*")) represents all versions above and including 6.0. If the version string is not "*", it must be a valid-version?.

syntax
(revision-names str ...)

str : non-empty-string?

Sets package-revision-names.

syntax
(revision-number num)

num : revision-number?

Sets package-revision-number.

syntax
(tags t ...)

t : non-empty-string?

Sets package-tags.

syntax
(url location)

location : url-string?

Sets package-url.

6.2 Reprovided Binding Index🔗ℹ

denxi/pkgdef reprovides bindings from several other modules in the collection. They are indexed here for reference.

#%app · #%datum

apply · artifact

base32 · base64 · byte-source

coerce-source

define · description

edition · extract · extract-input

file-source · find-input · from-file

getenv

hex · http-mirrors-source · http-source

in-paths · input · input-ref · install · integrity

keep-input · keep-standalone-racket-module

lines-source

mdo · metadatum

name

os-support · output

path-matching · provider

quote

racket-versions · release-input · resolve-input · revision-names · revision-number · run

signature · sources · string-append

tags · text-source

url

6.3 Static Operations for Package Definitions🔗ℹ

(require denxi/pkgdef/static)

package: denxi

value
PACKAGE_DEFINITION_MODULE_LANG : symbol?
value
PACKAGE_DEFINITION_READER_LANG : symbol?

Collection paths for a module language and reader extension used to write package definitions.

procedure
(make-package-definition-datum [ #:id id]
body)
→ package-definition-datum?
id : symbol? = 'pkgdef
body : list?

Equivalent to (make-racket-module-datum #:id id PACKAGE_DEFINITION_MODULE_LANG body)

procedure
(get-package-definition-body datum) → list?
datum : package-definition-datum?

Returns the top-level forms of the module code in datum.

value
bare-pkgdef? : flat-contract?
=
(struct/c bare-racket-module symbol?
PACKAGE_DEFINITION_MODULE_LANG
list?)

A contract that matches a bare package definition.

value
package-definition-datum? : predicate/c

Equivalent to (racket-module-code? PACKAGE_DEFINITION_MODULE_LANG v).

procedure
(get-static-exact-package-query pkgdef
[ defaults])
→ exact-package-query?
pkgdef : bare-pkgdef?
defaults : package-query-defaults-implementation/c
= default-package-query-defaults

Returns an exact package query by reading the contents of the package definition. Undefined names are given default values from defaults.

procedure
(get-static-abbreviated-query pkgdef) → package-query?
pkgdef : bare-pkgdef?

Returns a package query containing the provider, package, edition, and revision number in pkgdef.

procedure
(get-static-simple-string pkgdef id) → any/c
pkgdef : bare-pkgdef?
id : symbol?

Equivalent to (get-static-simple-value stripped id "default").

The return value is assumed to be a string, but might not be.

procedure
(get-static-inputs pkgdef) → list?
pkgdef : bare-pkgdef?

Returns a list of all input expressions in pkgdef.

procedure
(get-static-simple-value pkgdef id default) → any/c
  pkgdef : bare-pkgdef?
  id : symbol?
  default : any/c

Searches the top-level code of pkgdef for a S-expression of form (id val). Returns the datum in val’s position, or default if no such expression exists.

procedure
(get-static-list-value pkgdef id default) → any/c
  pkgdef : bare-pkgdef?
  id : symbol?
  default : any/c

Searches the top-level code of pkgdef for a S-expression of form (id . xs). Returns xs, or default if no such expression exists.

procedure
(override-inputs pkgdef input-exprs) → bare-pkgdef?
pkgdef : bare-pkgdef?
input-exprs : list?

Functionally replaces any package inputs in pkgdef that share a name with at least one element in input-exprs.

If multiple expressions in input-exprs share a name, only the last occurrance will be used in the output.

procedure
(replace-input-expression pkgdef
input-name
replacement) → bare-pkgdef?
  pkgdef : bare-pkgdef?
  input-name : non-empty-string?
  replacement : any/c

Functionally replaces the first input form in pkgdef with replacement, where the input’s name is input-name.

1	Prerequisite Knowledge
2	Command Line Argument Parsers
3	Command Line Utilities
4	Command Line Flags
5	Packages
6	Package Definitions
7	Package Queries
8	Launchers
9	Subprograms
10	Artifacts
11	Messages
12	Package Inputs
13	Package Outputs
14	Integrity Checking
15	Signature Checking
16	Digs
17	Reader Extension
18	Sources
19	Versions
20	State
21	Settings
22	Formatting
23	URLs
24	Strings
25	Localization
26	Printer
27	Archives
28	System
29	Monads
30	Files
31	Cryptography
32	Ports
33	Security
34	Racket Module Operations
35	Codec
36	Notaries

6.1	Package Definition Terms
6.2	Reprovided Binding Index
6.3	Static Operations for Package Definitions