#lang scribble/doc
@(require scribble/manual
          scribble/eval
          scribble/bnf
          "../planet.ss"
          "eval.ss")
@(require (for-label scheme/base scribble/manual (this-package-in scheme)))

@title[#:style 'quiet #:tag "planet"]{@|PLaneT| Packages}

@defmodule/this-package[planet]

This module provides tools relating to @|PLaneT| packages.

@defform*[[
(this-package-version-symbol)
(this-package-version-symbol path)
]]{

Produces a symbol corresponding to a @scheme[planet] module path for the current
planet package, possibly with a @nonterm{path} (from the grammar of
@scheme[planet] module specs) into the package.  This is similar to
@scheme[this-package-version] and similar tools from
@schememodname[planet/util].

}

@defform[(define-planet-package name package)]{

Defines a shortcut @scheme[name] for importing modules from planet package
@scheme[package].  Subsequently, @scheme[(name module)] is equivalent to
@scheme[(planet package/module)] as a require path.  For instance, to import the
@scheme[text] and @scheme[web] modules from this package:

@schemeblock[
(define-planet-package my-package cce/scheme)
(require (my-package web) (my-package text))
]

The above @scheme[require] is equivalent to:

@schemeblock[
(require (planet cce/scheme/web) (planet cce/scheme/text))
]

}

@defform[
(this-package-in path)
]{

This
@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{require transformer}
imports the file at @scheme[path] in the current planet package.  For instance,
in this package (@scheme[#,(this-package-version-symbol)]), writing:
@schemeblock[(require (this-package-in function))]
... is equivalent to writing:
@schemeblock[(require #,(schememodname/this-package function))]

}

@defform*[[
(defmodule/this-package)
(defmodule/this-package #:use-sources [src-path ...] [src ...])
(defmodule/this-package path)
(defmodule/this-package path #:use-sources [src-path ...] [src ...])
]]{

This Scribble form corresponds to @scheme[defmodule] within a planet package.
The displayed module path is a @scheme[planet] module path to the current planet
package, possibly with a @nonterm{path} (from the grammar of @scheme[planet]
module specs) into the package.  If the @scheme[#:use-sources] option is
present, each @scheme[src-path] is similarly treated as a path into the current
planet package, while each @scheme[src] is treated normally.  Both sets of paths
are concatenated and passed to the normal @scheme[defmodule].

}

@defform*[[
(defmodule*/no-declare/this-package [src-path ...] [src ...])
]]{

This Scribble form corresponds to @scheme[defmodule*/no-declare] within a planet
package.  The displayed module paths are @scheme[planet] module paths to the
current planet package, possibly with @nonterm{path}s (from the grammar of
@scheme[planet] module specs) into the package.  Each @scheme[src-path] is
similarly treated as a path into the current planet package, while each
@scheme[src] is treated normally.  Both sets of paths are concatenated and
passed to the normal @scheme[defmodule*/no-declare].

}

@defform*[[
(schememodname/this-package)
(schememodname/this-package path)
]]{

This Scribble form corresponds to @scheme[schememodname] much like
@scheme[defmodule/this-package] above corresponds to @scheme[defmodule].  The
@scheme[path], if present, is treated as a @nonterm{path} (from the grammar of
@scheme[planet] module specs) into the current planet package, and converted
into a @scheme[planet] module spec.

}

@defform*[[
(declare-exporting/this-package [mod-path ...] [mod ...])
(declare-exporting/this-package [mod-path ...] [mod ...]
                                #:use-sources [src-path ...] [src ...])
]]{

This Scribble form corresponds to @scheme[declare-exporting] much like
@scheme[defmodule/this-package] above corresponds to @scheme[defmodule].  Each
@scheme[mod-path] and @scheme[src-path] is treated as a @nonterm{path} (from the
grammar of @scheme[planet] module specs) into the current package.  They are
concatenated with the lists of @scheme[mod]s and @scheme[src]s, respectively,
and passed to the normal @scheme[declare-exporting].

}