there are certain features that many compilers share, and one of them is a command line interface. andy lester has started entering tickets for perl 6 features in the perl6 request tracker, and after thinking about implementing this for perl6, patrick and i decided that many compilers will want this functionality, so it makes sense to make it available in the Parrot Compiler Toolkit (PCT) HLLCompiler object.
the HLLCompiler object provides an interface for common high-level language compiler tasks. it allows you to implement a command line interface, compile from a file, and gives you an interactive compiler mode which evaluates standard input one line at a time.
HLLCompiler also allows you to set the transformation stages used to produce something executable from your source code. for perl6, that's source code -> parse tree -> abstract syntax tree (PAST) -> object syntax tree (POST) -> parrot intermediate representation (PIR). PIR is fed to parrot's intermediate code compiler (IMCC) to be executed. HLLCompiler's 'compile' method sets the process in motion.
although HLLCompiler offers a generic method for compilers invoked from command line, there are some options common to most compilers (indeed most programs) that would be helpful to add; '--help' is one of these options, and the subject of this patch.
view the patch here: http://perlsix.org/svn/parrot/revision/?rev=24550>
this patch does four basic things: refactors a hardcoded list of command line arguments into an attribute; adds an attribute containing usage text; handles processing of the '--help' option; and adds a usage method called from '--help'.
the first difference in the report adds two attributes to the HLLCompiler object, '@cmdoptions' and '$usage'. the names of the attributes are listed in a space separated string, which is an argument to parrot's 'split' operator. 'split' returns a PMC of type 'ResizableStringArray', which is stored in a virtual register named $P1. the list of attributes in $P1 is flattened and passed to the 'new_subclass' method of a 'Protomaker' object, which generates a parrot protoobject of type 'PCT::HLLCompiler' that includes a list of attributes with the names passed in. all this occurs when the HLLCompiler bytecode is loaded.
the next difference is in HLLCompiler's 'init' vtable function (and method), which is executed when a HLLCompiler protoobject's 'new' method is called. here, i've added values to the new attributes, '@cmdoptions' and '$usage'. '@cmdoptions' contains an array of command line options in getopts syntax. '$usage' contains a text prelude, followed by a header for the options section, and then a list of the command line options in '@cmdoptions' appended one per line.
the third difference removes the previously hardcoded list of command line options passed to the getopts object (via parrot's 'push' opcode), and replaces it with code that gets the array from '@cmdoptions' and passes each item in the array iteratively.
the fourth and fifth differences appear in the 'command_line' method of HLLCompiler, and process the '-h' or '--help' command line options. if either option is found via getopts and stored in the 'adverbs' hash, the 'usage' method is called, passing the program name (stored in the register named 'arg0'.)
the sixth and final difference defines the new 'usage' method. 'usage' takes an optional parameter which prints it's value if passed. then 'usage' prints the contents of the '$usage' attribute stored in HLLCompiler, and exits.
so, this patch provides a simple (however ugly) help text for any compiler implemented with the PCT, and allows these compilers to override the default behavior and implement a customized (and hopefully more useful) help message.
related links:
perl6 request tracker:
http://rt.perl.org/rt3/Search/Results.html?Query=Queue%20%3D%20'perl6'>
submit requests to the perl6 request tracker by mail:
mailto:perl6-bug@perl.org>
parrot object model design document (PDD15):
