On this page:
1.1 Example
1.2 Planks
1.2.1 Create a Package
1.2.2 Create a Collection
1.2.3 Create a Module
1.2.4 Create a Test Module
1.2.5 Create a Scribble
1.3 Command-Line Flags
1.4 Adding Your Own Planks

1 Using raco

The primary purpose of this package is to add a templated content generator to the raco tool. As distributed the tool has a ’pkg new’ option that generates an idiomatic package structure. The scaffold command seeks to extend the existing package tool in three ways.

To this end scaffold defines content in the form of planks that represent templated content. A plank can be a snippet of code, a complete file, or a set of files and directories such as a whole package.

1.1 Example

The following shows the top-level sub-command help.

  $ raco scaffold

  Usage: raco scaffold <subcommand> [option ...] <arg ...>

    where any unambiguous prefix can be used for a subcommand

  

  The Racket templated content generator.

  

  For help on a particular subcommand, use 'raco scaffold <subcommand> --help'

    raco scaffold package       create a new, complete, package.

    raco scaffold collection    create a new collection.

    raco scaffold module        create a new module.

    raco scaffold testmodule    create a new rackunit test module.

    raco scaffold scribble      create basic scribble documentation.

    raco scaffold plank         expand a short code snippet.

    raco scaffold config        show default configuration values.

The following shows the expansion of a snippet of code from a user-defined plank file.

  $ raco scaffold plank -l

  test-exn

  

  $ raco scaffold plank -k fixture=my-function -k exn=contract test-exn

  (test-case

    "my-function: check for contract exception"

    (check-exn exn:fail:contract?

      (λ () (my-function))))

1.2 Planks

As mentioned already, a plank is simply some content, either a small snippet of code, a file, or a collection of files and directories that make up a templated item. A set of pre-defined planks can be created by the tool directly, each of which is described in detail below.

1.2.1 Create a Package

Invoking the package sub-command, as shown in the command-line below,

  $ raco scaffold package -d "Some new package" -V "1.0" -l MIT -r markdown \

           -L "racket/base" -u "me" -e "me@example.com" my-name

results in the Multi-Collection Package package structure shown below (numbers indicate comments in the following list).

  my-name/

  |-- README.md              {1}

  |-- LICENSE                {2}

  |-- .travis.yml            {3}

  |-- Makefile               {3}

  |-- info.rkt

  '-- my-name/

      |-- info.rkt

      |-- main.rkt

      |-- private/           {4}

      |   '-- my-name.rkt    {4}

      |-- test/

      |   '-- my-name.rkt

      '-- scribblings/

          '-- scribblings.scrbl {5}

          '-- my-name.scrbl  {5}

  1. The file format for the README is set using the -r argument with the default set to markdown.

  2. The actual license included in the LICENSE file is set using the -l argument with the default set to MIT.

  3. These two files are used for running builds, specifically using the Travis service. These can be excluded using the no-travis argument.

  4. This is a common style for keeping implementation files separate from the interface ones, here it is used as the default layout. These can be excluded using the no-private argument.

  5. By default scribble files are configured in the collection’s info.rkt to use the multi-page option (see Multi-Page Sections). This can be changed to a single-page using the single-scribble argument.

Additionally, scribble files are setup with a top-level file (named scribblings.scrbl)) that uses @include-section to include each module scribble separately. This has the advantage of smaller files to edit, and more fine-grained version control.

Single Collection Package. Adding the single-collection argument will create a structure more like the pkg new command where the collection and package are one and the same.

  my-name/

  |-- README                 {1}

  |-- LICENSE                {2}

  |-- .travis.yml            {3}

  |-- Makefile               {3}

  |-- info.rkt

  |-- main.rkt

  |-- private/               {4}

  |   '-- my-name.rkt        {4}

  |-- test/

  |   '-- my-name.rkt

  '-- scribblings/

      '-- scribblings.scrbl  {5}

      '-- my-name.scrbl      {5}

Triple Collection Package. Alternatively, adding the triple-collection argument will create a package structure with three collections, a -lib for the library itself, a -doc for the scribble documentation, and a -test for all test code.

  my-name/

  |-- README                 {1}

  |-- LICENSE                {2}

  |-- .travis.yml            {3}

  |-- Makefile               {3}

  |-- info.rkt

  |-- my-name-lib/

  |   |-- info.rkt

  |   |-- main.rkt

  |   '-- private/           {4}

  |       '-- my-name.rkt    {4}

  |-- my-name-test/

  |   |-- info.rkt

  |   '-- my-name.rkt

  |-- my-name-doc

      |-- info.rkt

      |-- scribblings.scrbl  {5}

      '-- my-name.scrbl      {5}

1.2.2 Create a Collection

A collection is a subset of the first package structure above, it has it’s own info.rkt and main.rkt files as well as private, test, and documentation folders.

  my-name/

  |-- info.rkt

  |-- main.rkt

  |-- private/

  |   '-- my-name.rkt

  |-- test/

  |   '-- my-name.rkt

  '-- scribblings/

      '-- scribblings.scrbl

      '-- my-name.scrbl

1.2.3 Create a Module

A module is a subset of a collection, it creates a library module, test module, and separate scribble file.

  my-name.rkt

  test/

  '-- my-name.rkt

  scribblings/

  '-- my-name.scrbl

1.2.4 Create a Test Module

Creates a single test module in the test directory.

  test/

  '-- my-name.rkt

1.2.5 Create a Scribble

Creates a single scribble file in the scribblings directory.

  scribblings/

  '-- my-name.scrbl

1.3 Command-Line Flags

The following summarizes all of the command-line flags and the sub-commands that make use of them.

short

 

long

 

package

 

collection

 

module

 

test

 

scribble

 

plank

d

 

description

 

Y

 

Y

 

Y

 

Y

 

Y

 

Y

u

 

user

 

Y

 

Y

 

Y

 

Y

 

Y

 

U

 

github-user

 

Y

 

Y

 

Y

 

Y

 

Y

 

e

 

email

 

Y

 

Y

 

Y

 

Y

 

Y

 

E

 

github-email

 

Y

 

Y

 

Y

 

Y

 

Y

 

v

 

verbose

 

Y

 

Y

 

Y

 

Y

 

Y

 

Y

 

very-verbose

 

Y

 

Y

 

Y

 

Y

 

Y

 

Y

L

 

language

 

Y

 

Y

 

Y

 

Y

 

 

l

 

license

 

Y

 

 

 

 

 

r

 

readme

 

Y

 

 

 

 

 

 

no-private

 

Y

 

Y

 

 

 

 

 

no-travis

 

Y

 

 

 

 

 

o

 

output-dir

 

Y

 

 

 

 

 

 

single-collection

 

Y

 

 

 

 

 

 

triple-collection

 

Y

 

 

 

 

 

 

single-scribble

 

Y

 

 

 

 

 

V

 

version

 

Y

 

 

 

 

 

k

 

key-value

 

 

 

 

 

 

Y

l

 

list

 

 

 

 

 

 

Y

1.4 Adding Your Own Planks

The plank sub-command allows for the expansion of arbitrary content by looking for files of the form {{name}}.plank in the user’s ~/planks/ directory. The tool actually looks in the package internally first for planks distributed internally, and then the local folder. Calling the sub-command with the -l or list flag will have the tool list all of the matching plank files in either location.

Clearly, a user-defined file can reuse any of the template variables used in the standard planks (see Internal Arguments) or you can define your own and pass values into the template via the -k or key-value command line flag.

  $ cat ~/planks/test-exn.plank

  (test-case

    "{{fixture}}: check for {{exn}} exception"

    (check-exn exn:fail:{{exn}}?

      (λ () ({{fixture}}))))

This package makes use of the Dali template package for actual template expansion of plank files.