examples/gen-tutorial

   1 #! /usr/bin/env perl
   2
   3 # This file was originally written by Peter Keller (psilord@cs.wisc.edu)
   4 # and this code is released under the same license as IOLib.
   5
   6 # The purpose of this program is to parse out the ex-NNNb / ex-NNNe sections
   7 # from all of the ex*.lisp files, and then shove them into the template
   8 # tutorial file at <example location:example> lines. This greatly simplifies
   9 # changing the codes and keeping it current to the tutorial.
  10
  11 # This script is a simple hack and can be fooled by incorrect sentinel markers
  12 # in the codebase or by out of bounds example numbers in the tutorial.tmpl
  13 # file. My advice is: don't do that.
  14
  15 use strict;
  16 use warnings;
  17
  18 sub main
  19 {
  20         my $exref;
  21
  22         $exref = load_examples();
  23         gen_tutorial($exref);
  24
  25         return 0;
  26 }
  27
  28 sub load_examples
  29 {
  30         my @files = `ls ex*.lisp`;
  31         my $file;
  32         my ($line, $location, $example, $edge);
  33         my $recording;
  34         my %ex;
  35
  36         map {chomp $_;} @files;
  37
  38         foreach $file (@files) {
  39                 # print "Processing file: $file\n";
  40
  41                 # open each file in turn, each file's prefix is the key to a hash of
  42                 # examples found in the file, and each example is keyed by ex-NNN as
  43                 # dictated in the file.
  44
  45                 open(FIN, "<$file") or die "Can't open file $file: $!";
  46                 ($location) = ($file =~ m/^(.*)\.lisp$/);
  47
  48                 # read the examples out of the source itself.
  49                 $recording = 0;
  50                 while(defined($line = <FIN>)) {
  51                         chomp $line;
  52                         if ($line =~ /;\s*ex-/) {
  53                                 # we either start recording an example, or are just finishing
  54                                 # one.
  55                                 ($example, $edge) = ($line =~ /(ex-\d+)(.)/);
  56                                 if ($edge =~ /b/) {
  57                                         $recording = 1;
  58                                         die "Premature EOF!" if (!defined($line = <FIN>));
  59                                         chomp $line;
  60                                 } else {
  61                                         $recording = 0;
  62                                 }
  63                         }
  64
  65                         if ($recording == 1) {
  66                                 push @{$ex{$location}{$example}}, $line;
  67                                 # print "Recorded: $location:$example <- $line\n";
  68                         }
  69                 }
  70
  71                 close(FIN);
  72         }
  73
  74         return \%ex;
  75 }
  76
  77 sub gen_tutorial
  78 {
  79         my ($exref) = @_;
  80         my $tmpl = "tutorial.tmpl";
  81         my $out = "tutorial";
  82         my $line;
  83         my ($location, $example);
  84         my $exline;
  85
  86         open(FIN, "<$tmpl") or die "Can't open tutorial template $tmpl: $!";
  87         open(FOUT, ">$out") or die "Can't open generated tutorial $out: $!";
  88
  89         # read each line of the template, and if I see the magical
  90         # <example location:example> format, then shove in the example code lines
  91         # from the hash table.
  92         while(defined($line = <FIN>)) {
  93                 if ($line =~ m/<example\s+.*>/) {
  94                         $line =~ s/^\s+//;
  95                         $line =~ s/\s+$//;
  96                         # if I asked for an example, then shove the block into the tutorial
  97                         # right here.
  98                         ($location, $example) = ($line =~ m/<example\s*(.*):(.*)>/);
  99                         if (!exists($exref->{$location}{$example})) {
 100                                 close(FOUT);
 101                                 unlink $out;
 102                                 die "Tried to include nonexistant example: $location:$example";
 103                         }
 104                         print FOUT "+" . "-" x 78 . "+\n";
 105                         print FOUT "|" . " " x 78 . "|\n";
 106                         foreach $exline (@{$exref->{$location}{$example}}) {
 107                                 print FOUT "$exline\n";
 108                         }
 109                         print FOUT "|" . " " x 78 . "|\n";
 110                         print FOUT "+" . "-" x 78 . "+\n";
 111                 } else {
 112                         # otherwise just copy the line over.
 113                         print FOUT $line;
 114                 }
 115         }
 116
 117         close(FOUT);
 118         close(FIN);
 119 }
 120
 121 exit main();
 122
 123