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.
It should provide options to generate multiple, legitimate, forms of major structures such as package and collections.
It should provide a mechanism to add content to an existing package or collection.
It should allow the user to create their own templates for commonly-used tasks.
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} |
The file format for the README is set using the -r argument with the default set to markdown.
The actual license included in the LICENSE file is set using the -l argument with the default set to MIT.
These two files are used for running builds, specifically using the Travis service. These can be excluded using the –no-travis argument.
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.
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 |
|
| 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.