doc.txt

Require: Specifying package abbreviations

_Require_: Specifying package abbreviations
===========================================

By Ryan Culpepper (ryanc at plt-scheme dot org)

Keywords: _require_, _module_, _package_, _library_

_require.ss_
============

To use: (require (planet "require.ss" ("ryanc" "require.plt" 1 1)))

This module provides two macros for defining require-form abbreviations.
Both abbreviation-defining forms ('define-module' and 'define-library')
automatically provide the names that they define when used within a module.

> (define-module <name> <mod-spec> ...) SYNTAX

  Defines 'require-<name>' as a macro that expands into a require form
  for the given module spec(s).  Also defines 'require-for-syntax-<name>'
  and 'require-for-template-<name>'

    (define-module list (lib "list.ss"))
    (require-list)
    ==Expands==> (require (lib "list.ss"))

    (define-module useful (lib "list.ss") (lib "etc.ss"))
    (require-useful)
    ==Expands==> (require (lib "list.ss") (lib "etc.ss"))

    (define-module test (planet "test.ss" ("schematics" "schemeunit.plt" 2)))
    (require-test)
    ==Expands==> (require (planet "test.ss" ("schematics" "schemeunit.plt" 2)))

  When 'define-module' is given a relative module spec---that is, a relative
  path---the path is interpreted relative to the location of the 'define-module'
  form, *not* relative to the use of the require-abbreviation.

    (define-module util "util.ss")  ;; location A
    (require-util)                  ;; location B
    ==Expands==> (require (file "/<directory-of-location-A>/util.ss"))

  When given exactly one module spec, 'define-module' also defines
  'dynamic-require-<name>' as a procedure:

      (define-module list (lib "list.ss"))
      (dynamic-require-list 'filter)
    is equivalent to
      (dynamic-require '(lib "list") 'filter)

> (define-library <name> <package-spec>) SYNTAX

  Defines 'require-<name>' as a macro that expands into a require form
  for the given module spec, but taking the module (file) name and 
  optional additional subdirectories at the point of usage.

  Also defines 'require-for-syntax-<name>' and 'require-for-template-<name>'
  with analogous behavior.

  A package-spec is an absolute module spec (starting with lib, file, or planet)
  with the file part omitted.

    (define-library schemeunit (planet ("schematics" "schemeunit.plt" 1 2)))
    (require-schemeunit "test.ss")
    ==Expands==> (require (planet "test.ss" ("schematics" "schemeunit.plt" 1 2)))

    (define-library dr-priv (lib "drscheme" "private"))
    (require-dr-priv "debug.ss")
    ==Expands==> (require (lib "debug.ss" "drscheme" "private"))

    (define-library dr (lib "drscheme"))
    (require-dr "debug.ss" "private")
    ==Expands==> (require (lib "debug.ss" "drscheme" "private"))

    (define-library project (file "/home/schemer/project"))
    (require-project "app.ss")
    ==Expands==> (require (file "/home/schemer/project/app.ss"))

  Also defines 'dynamic-require-<name>' as a procedure:

      (define-library dr (lib "drscheme"))
      (dynamic-require-dr "drscheme.ss" #f)
    is equivalent to
      (dynamic-require '(lib "drscheme.ss" "drscheme") #f)

Pragmatics
==========

Projects that depend on external packages and collects may benefit from defining
shortcuts to those external resources in a single local module. This reduces the 
number of changes necessary when upgrading to a new version of a PLaneT package; 
the progammer must change the version numbers in one module rather than in every
module that uses that facility.

Expected usage:

/project
  /config.ss
  /myfile1.ss
  /myfile2.ss
  ...

(module config mzscheme
  (require (planet "require.ss" ("ryanc" "require.plt" 1)))
  (define-module foo (planet "foo.ss" ("alice" "foo.plt" 3 2)))
  (define-library bar (planet ("bob" "bar.plt" 1 1)))))

;; require-foo, require-bar, etc are automatically exported

(module myfile mzscheme
  (require "config.ss")
  (require-foo)
  ...)

(module myfile2 mzscheme
  (require "config.ss")
  (require-bar "mumble.ss")
  ...)

When new versions of the 'bar.plt' package are available, the project
can switch to those by changing only the contents of the "config.ss"
file, rather than tracking down every occurrence of a require to
'bar.plt' in the project.