From 4f1a47cff44cb62140b045ac5ae6d8c774fb879c Mon Sep 17 00:00:00 2001 From: sorear Date: Sun, 29 Aug 2010 23:24:46 +0000 Subject: [PATCH] [viv] Improve documentation a bit git-svn-id: http://svn.pugscode.org/pugs@32114 c213334d-75ef-0310-aa23-eaa082d1ae64 --- src/perl6/viv | 84 ++++++++++++++++++++--------------------------------------- 1 file changed, 28 insertions(+), 56 deletions(-) diff --git a/src/perl6/viv b/src/perl6/viv index 78a4d799d..b56ad8b36 100755 --- a/src/perl6/viv +++ b/src/perl6/viv @@ -2,36 +2,31 @@ =head1 NAME -viv - A retargettable Perl 6 metacompiler - -=head1 DESCRIPTION - -C converts code, written in a subset of Perl 6, into code in Perl 5 (and -eventually several other languages). C is B; it -makes little to no attempt to provide faithful Perl 6 semantics, so code -intended to be run through viv needs to restrict itself to a "nice" subset of -Perl 6. Exactly what "nice" means hasn't been completely nailed down, but -multithreading, the MOP, augmenting system classes, and operator overloading -are all almost certainly out. - -* First, viv reads your source code (which must be encoded in UTF-8). If the - --thaw option is provided, the source is expected to be in Storable format; - this eliminates parsing overhead and makes viv ~7 times faster. Useful for - experimenting with modifications to viv itself. - -* Second, the source code is parsed into an object-oriented abstract syntax - tree using STD.pm6 and Actions. If --freeze is passed, the process stops - here and a Storable dump is generated. - -* Translation of the parse tree into output code occurs in a single interleaved - pass, however it takes different paths for regex and non-regex code. - Non-regex code is mostly passed through, with targetted syntax-dependant - rewrites; as possible, we are changing this to generate DEEP. Regexes are - converted into a narrowed REgex AST format, which is translated into DEEP and - additionally dumped for post-translation processing by the LTM engine. - -* The DEEP engine handles differences between output formats, taking advantage - of its much narrower form. +viv - The STD.pm6 command line multitool + +=head1 SYNOPSIS + +viv [options] [file...] + + -e --evaluate TEXT Use code from the command line + --thaw Input is a --freeze dump, not Perl 6 + -o --output FILE Send result to FILE, not stdout + --noperl6lib Disable use of the PERL6LIB variable + --symlroot DIR Use DIR as parsed module cache + --concise Pretty-print the parse tree (default) + -c --check Just check syntax + --freeze Generate Storable dump of parse tree + -y --yaml Generate YAML parse tree + -5 --p5 Translate to Perl 5 syntax + -6 --p6 Translate back to Perl 6 + --psq Translate to Perlesque syntax + -s --stab Include symbol table in output + -m --match Include match tree in output + --no-indent Disable indentation of output + -l --log Be verbose while generating output + -k --keep-going Don't stop if error found during output phase + --compile-setting FILE Preparse a CORE.setting file + --help This message =cut @@ -72,29 +67,6 @@ $::MULTINESS = ''; local $::PROTO = {}; local $::PROTOSIG = {}; -sub USAGE { - print <<'END'; -viv [switches] filename - where switches can be: - -e use following argument as program - -o send output to following argument instead of STDOUT - --yaml spit out a parsable abstract syntax tree - --concise spit out a short syntaxe tree (default) - --p5 spit out a Perl 5 representation - --p6 spit out a Perl 6 representation - --psq spit out a Perlesque representation (very incomplete) - --no-indent disable output indentation for faster parsing - --freeze generate a Storable representation - --thaw use existing Storable of AST from filename - --stab include the symbol table - --pos include position info in AST - --match include match tree info in AST - --log emit debugging info to standard error - --keep-going continue after output errors -END - exit; -} - BEGIN { # Let's say you have a tricky optimization that breaks the build. You want # to know exactly which rewrite is culpable? Try bisecting with @@ -113,7 +85,7 @@ our $OPT_output = 'concise'; use FindBin; use File::Spec; -use Getopt::Long; +use Getopt::Long 2.34 'HelpMessage'; my ($boot, $symlroot); { @@ -146,7 +118,7 @@ my $r = GetOptions( "thaw" => \$OPT_thaw, "keep-going|k" => \$OPT_keep_going, "compile-setting=s" => \$OPT_compile_setting, - "help" => sub { USAGE() } + "help" => sub { HelpMessage() } ); unshift @INC, $FindBin::Bin; @@ -4197,7 +4169,7 @@ unless (caller) { exit 0; } - USAGE() unless @ARGV || $PROG; + HelpMessage() unless @ARGV || $PROG; my $r; if ($OPT_thaw) { my $raw = retrieve($_[0]); -- 2.11.4.GIT