Require: Specifying package abbreviations

_Require: Specifying package abbreviations_
=================================================

By Ryan Culpepper (ryanc at ccs dot neu dot edu)

Keywords: _require_, _module_, _package_, _library_

API
===

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

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

  Defines 'require-<name>' as a macro that expands into a require form
  for the given module spec.
  
    (define-module list (lib "list.ss"))
    (require-list)
    ==Expands==> (require (lib "list.ss"))

  Also defines 'require-for-syntax-<name>' and 'require-for-template-<name>'

> (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.

    (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 (lib "drscheme"))
    (require-dr "debug.ss" "private")
    ==Expands==> (require (lib "debug.ss" "drscheme" "private"))

    (define-library dr-priv (lib "drscheme" "private"))
    (require-dr-priv "debug.ss")
    ==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"))

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")
  ...)

Then, when new versions of the 'bar.plt' package are available, the projects 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 projects.

BUGS AND TODO
=============

- Add dynamic-require support