MakeHandsOn, the Student Assignment Generator

This makes up student "todo" exercise directories directly from the solutions. The benefits include the following:

• To the instructor, a lot less work!

• To the student, the ability to reliably compare their work-in-progress with the working solution.

The starting assumption is that all the files for the course are organized into directories, one per assignment, rather like (say) an Eclipse workspace. In particular, the working versions should be stored in folders called "xxxsolution", e.g., "ex51solution" might be the solution version of Exercise 5.1.

This program performs various substitutions on files. It creates a copy of each "xxxsolution" directory as "xxx" (which must not exist), making all the line-based changes shown below.

Marking up the solution version of files

The following line-based changes are baked into the code:

//- through to //+ inclusive are DELETED from the output

Other changes are configurable (see below). The following are currently provided:

1) In the Solutions input folder, you need to mark TODO lines with //T instead of // TODO so the solution doesn’t show in Tasks Window in Eclipse (since you should only be editing the solutions versions).

2) //H becomes // HINT

3) Use //R for replacement variables, that is, placeholders for stuff that gets cut. This can be useful to make the exercise code compile without errors. For example:

"//T Create an int variable i containing the expression shown in the notes.
"//R int i = 0;
"//-",
"int i = Math.sqrt(jNumber) * Math.cos(kNumber);
"//+"

will print one line (in addition to the TODO comment):

 This should appear.

4) eXchange mode (//X) allows substitution of text with a block

//X+ :::text to change:::replacement text
Inside this block, any instance of "text to change" will be replaced with "replacement text"
//X-

Note that it is a straight replacement and does not use regex’s . Replacement starts immediately after the //X+ …​ line and ends at //X-

5) We remove "solution" from filenames in config files (so be warned: don’t use the word 'solution' unless you mean it to go away in the non-solution. It is case sensitive so you can refer to "the Solution" and have it work OK. This sounds painful but is required so that the Eclipse .project/.classpath files will work

6) Finally, we replace absolute paths. At present the value of ${user.home} gets turned into C:/. If you have used any absolute paths (which you shouldn’t), this could save your bacon e.g., a line containing /home/ian/testdata would be changed to C:/testdata

Actually this is implemented by looking in the system properties. E.g., assuming the default JDK System Properties list on MS-Windows says

${user.home}=C:/

then a line like

Look in /home/ian/testdata

will come out as

Look in C:/testdata

Changes are made only to files whose extensions are listed in the variable SUB_TEXT_FILE_EXTENS in the program, which currently includes most sensible filename endings, but you might want to review it.

Note that no changes will be made in directories named CVS, .svn, .git, .metadata, bin or target (see the variable IGNORE_DIRS in the source code).

Finally, a list of files can be excluded by their full name. For example, if in an exercise, the student is directed to create a file from scratch, that file should obviously exist in the solution folder but not in the generated student folder. The filename exclude-files.txt may exist only in the root of a starting (solution) directory, containing one filename per line, as for example:

$ cat ex21solution/exclude-files.txt
EventsListerTest.java

In this example, the file EventListerTest.java is the file the student must create, so neither it (nor, of course, the file ignore-files.txt) will be copied to the ex21 folder.

Customizing

The text substitutions are loaded from a properties file to be easy to change, but if you do so, the documentation above will not strictly apply!

The input format is: regex=replacement. If you do need to change it, consult the included properties file to see the examples.

You can change this by editing makehandson.properties AND re-generating the Jar file (see "Rebuilding" below). You could probably just put the new properties file on your CLASSPATH ahead of the jar file, but this hasn’t been tested.

Generating the Non_solution Versions from the Marked-up Solutions

Each folder should be named foosolution, e.g., ex41solution. This will create ex41.

Then run "java -jar makehandson.jar *solution" in the crsXXX directory. This will create ex11 from ex11solution, and so on.

There is a script in the scripts folder that may work for you if you do "mvn install".

Rebuilding the Program

The source file for makehandson is an Eclipse project. Open it in Eclipse and make any changes.

Or, using Maven 3, just do mvn package

Bugs/ToDos

See the file TODO.txt

Modifying the Program

Well, this is Github, so just fork it and hack away. If you make it better, send me a note and a pull request.

Enjoy.

Ian Darwin ian@darwinsys.com