languages/squaak/doc/tutorial_episode_1.pod

   1 # Copyright (C) 2008, The Perl Foundation.
   2 # $Id$
   3
   4 =head1 PCT Tutorial Episode 1: Introduction
   5
   6 =head2 Introduction
   7
   8 This is the first episode in a tutorial series on building a compiler with the
   9 Parrot Compiler Tools. If you're interested in virtual machines, you've
  10 probably heard of the Parrot virtual machine. Parrot is a generic virtual
  11 machine designed for dynamic languages. This is in contrast with the Java
  12 virtual machine (JVM) and Microsoft's Common Language Runtime (CLR), both of
  13 which were designed to run static languages. Both the JVM and Microsoft
  14 (through the Dynamic Language Runtime -- DLR) are adding support for dynamic
  15 languages, but their primary focus is still static languages.
  16
  17 =head2 High Level Languages
  18
  19 The main purpose of a virtual machine is to run programs. These programs are
  20 typically written in some High Level Language (HLL). Some well-known dynamic
  21 languages (sometimes referred to as scripting languages) are Lua, Perl, PHP,
  22 Python, Ruby, and Tcl. Parrot is designed to be able to run all these languages.
  23 Each language that Parrot hosts, needs a compiler to parse the syntax of the
  24 language and generate Parrot instructions.
  25
  26 If you've never implemented a programming language (and maybe even if you have
  27 implemented a language), you might consider writing a compiler a bit of a black
  28 art. I know I did when I became interested. And you know what, it is. Compilers
  29 are complex programs, and implementing a language can be very difficult.
  30
  31 The Facts: 1) Parrot is suitable for running virtually any dynamic language
  32 known, but before doing so, compilers must be written, and 2) writing compilers
  33 is rather difficult.
  34
  35 =head2 The Parrot Compiler Toolkit
  36
  37 Enter the Parrot Compiler Toolkit (PCT). In order to make Parrot an interesting
  38 target for language developers, the process of constructing a compiler should be
  39 supported by the right tools. Just as any construction task becomes much easier
  40 if you have the right tools (you wouldn't build a house using only your bare
  41 hands, would you?), the same is true for constructing a compiler. The PCT was
  42 designed to do just that: provide powerful tools to make writing a compiler for
  43 Parrot childishly easy.
  44
  45 This tutorial will introduce the PCT by demonstrating the ease with which a
  46 (simple) language can be implemented for Parrot. The case study language is not
  47 as complex as a real-world language, but this tutorial is written to whet your
  48 appetite and show the power of the PCT. This tutorial will also present some
  49 exercises which you can explore in order to learn more details of the PCT not
  50 covered in this tutorial.
  51
  52 =head2 Squaak: A Simple Language
  53
  54 The case study language, named Squaak, that we will be implementing on Parrot
  55 will be a full-fledged compiler that can compile a program from source into
  56 Parrot Intermediate Representation (PIR) (or run the PIR immediately). It can
  57 also be used as a command-line interpreter. Squaak demonstrates some common
  58 language constructs, but at the same time is lacking some other, seemingly
  59 simple features. For instance, our language will not have return, break or
  60 continue statements (or equivalents in your favorite syntax).
  61
  62 Squaak will have the following features:
  63
  64 =over 4
  65
  66 =item * global and local variables
  67
  68 =item * basic types: integer, floating-point and strings
  69
  70 =item * aggregate types: arrays and hash tables
  71
  72 =item * operators: +, -, /, *, %, <, <=, >, >=, ==, !=, .., and, or, not
  73
  74 =item * subroutines and parameters
  75
  76 =item * assignments and various control statements, such as "if" and "while"
  77
  78 =back
  79
  80 As you can see, a number of common (more advanced) features are missing.
  81 Most notable are:
  82
  83 =over 4
  84
  85 =item * classes and objects
  86
  87 =item * exceptional control statements such as break and return
  88
  89 =item * advanced control statements such as switch
  90
  91 =item * closures (nested subroutines and accessing local variables in an outer scope)
  92
  93 =back
  94
  95 =head2 The Compiler Tools
  96
  97 The Parrot Compiler Tools we'll use to implement Squaak consist of the following
  98 parts:
  99
 100 =over 4
 101
 102 =item Parrot Grammar Engine (PGE).
 103
 104 The PGE is an advanced engine for regular expressions. Besides regexes as found
 105 in Perl 5, it can also be used to define language grammars, using Perl 6 syntax.
 106 (Check the references for the specification.)
 107
 108 =item Parrot Abstract Syntax Tree (PAST).
 109
 110 The PAST nodes are a set of classes defining generic abstract syntax tree nodes
 111 that represent common language constructs.
 112
 113 =item HLLCompiler class.
 114
 115 This class is the compiler driver for any PCT-based compiler.
 116
 117 =item Not Quite Perl (6) (NQP).
 118
 119 NQP is a lightweight language inspired by Perl 6 and can be used to write the
 120 methods that must be executed during the parsing phase, just as you can write
 121 actions in a Yacc/Bison input file.
 122
 123 =back
 124
 125 =head2 Getting Started
 126
 127 For this tutorial, it is assumed you have successfully compiled parrot
 128 (and maybe even run the test suite). If you browse through the languages
 129 directory in the Parrot source tree, you'll find a number of language
 130 implementations. Most of them are not complete yet; some are actively
 131 maintained actively and others aren't. If, after reading this tutorial,
 132 you feel like contributing to one of these languages, you can check out the
 133 mailing list or join IRC (see the references section for details).
 134
 135 The languages subdirectory is the right spot to put our language implementation.
 136 Parrot comes with a special shell script to generate the necessary files for a
 137 language implementation. In order to generate these files for our language,
 138 type (assuming you're in parrot's root directory):
 139
 140  $ perl tools/dev/mk_language_shell.pl Squaak languages/squaak
 141
 142 (Note: if you're on Windows, you should use backslashes.) This will generate the
 143 files in a directory languages/squaak, and use the name Squaak as the language's
 144 name. The last config step is to create the Makefile for your new language:
 145
 146  $  perl Configure.pl --languages=squaak
 147
 148 After this, go to this directory and type:
 149
 150  $ make test
 151
 152 This will compile the generated files and run the test suite. If you want more
 153 information on what files are being generated, please check out the references
 154 at the end of this episode.
 155
 156 Note that we didn't write a single line of code, and already we have the basic
 157 infrastructure in place to get us started. Of course, the generated compiler
 158 doesn't even look like the language we will be implementing, but that's ok for
 159 now. Later we'll adapt the grammar to accept our language.
 160
 161 Now you might want to actually run a simple script with this compiler. Launch
 162 your favorite editor, and put in this statement:
 163
 164  say "Squaak!";
 165
 166 Save the file (for instance as test.sq) and type:
 167
 168  $ ../../parrot squaak.pbc test.sq
 169
 170 This will run Parrot, specifying squaak.pbc as the file to be run by Parrot,
 171 which takes a single argument: the file test.sq. If all went well, you should
 172 see the following output:
 173
 174  $ ../../parrot squaak.pbc test.sq
 175  Squaak!
 176
 177 Instead of running a script file, you can also run the Squaak compiler as an
 178 interactive interpreter. Run the Squaak compiler without specifying a script
 179 file, and type the same statement as you wrote in the file:
 180
 181  $ ../../parrot squaak.pbc
 182  say "Squaak!";
 183
 184 which will print:
 185
 186  Squaak!
 187
 188 =head2 What's next?
 189
 190 This first episode of this tutorial is mainly an overview of what will be
 191 coming. Hopefully you now have a global idea of what the Parrot Compiler Tools
 192 are, and how they can be used to build a compiler targeting Parrot. If you want
 193 to check out some serious usage of the PCT, check out Rakudo (Perl 6 on Parrot)
 194 in languages/perl6 or Pynie (Python on Parrot) in languages/pynie.
 195
 196 The next episodes will focus on the step-by-step implementation of our language,
 197 including the following topics:
 198
 199 =over 4
 200
 201 =item structure of PCT-based compilers
 202
 203 =item using PGE rules to define the language grammar
 204
 205 =item implementing operator precedence using an operator precedence table
 206
 207 =item using NQP to write embedded parse actions
 208
 209 =item implementing language library routines
 210
 211 =back
 212
 213 In the mean time, experiment for yourself. You are welcome to join us on IRC
 214 (see the References section for details). Any feedback on this tutorial is
 215 appreciated.
 216
 217 =head2 Exercises
 218
 219 The exercises are provided at the end of each episode of this tutorial. In
 220 order to keep the length of this tutorial somewhat acceptable, not everything
 221 can be discussed in full detail. The answers and/or solutions to these exercises
 222 will be posted several days after the episode.
 223
 224 =head3 Advanced interactive mode.
 225
 226 Launch your favorite editor and look at the file squaak.pir in the directory
 227 languages/squaak. This file contains the main function (entry point) of the
 228 compiler. The class HLLCcompiler defines methods to set a command-line banner
 229 and prompt for your compiler when it is running in interactive mode. For
 230 instance, when you run Python in interactive mode, you'll see:
 231
 232  Python 2.5.1 (r251:54863, Apr 18 2007, 08:51:08) [MSC v.1310 32 bit (Intel)] on
 233  win32 Type "help", "copyright", "credits" or "license" for more information.
 234
 235 or something similar (depending on your Python installation and version).
 236 This text is called the command line banner. And while running in interactive
 237 mode, each line will start with:
 238
 239  >>>
 240
 241 which is called a prompt. For Squaak, we'd like to see the following when
 242 running in interactive mode (of course you can change this according to your
 243 personal taste):
 244
 245  $ ../../parrot squaak.pbc
 246  Squaak for Parrot VM.
 247  >
 248
 249 Add code to the file squaak.pir to achieve this.
 250
 251 Hint 1: Look in the onload subroutine.
 252
 253 Hint 2: Note that only double-quoted strings in PIR can interpret
 254 escape-characters such as '\n'.
 255
 256 Hint 3: The functions to do this are documented in
 257 compilers/pct/src/PCT/HLLCompiler.pir.
 258
 259 =head2 References
 260
 261 =over 4
 262
 263 =item * Parrot mailing list: parrot-porters@perl.org
 264
 265 =item * IRC: join #parrot on irc.perl.org
 266
 267 =item * Getting started with PCT: docs/pct/gettingstarted.pod
 268
 269 =item * Parrot Abstract Syntax Tree (PAST): docs/pct/past_building_blocks.pod
 270
 271 =item * Operator Precedence Parsing with PCT: docs/pct/pct_optable_guide.pod
 272
 273 =item * Perl 6/PGE rules syntax: Synopsis 5
 274
 275 =back
 276
 277
 278 =cut