Commits

gabriele renzi  committed e5cf177

readme work

  • Participants
  • Parent commits 5952f3e

Comments (0)

Files changed (1)

-Language 'z2' was created with tools/dev/mk_language_shell.pl, r32060.
+The Shakespeare Programming Language, on Parrot
 
+INTRO
+-----
+
+SPL is a language designed to allow usage of the beatiful shakespear wording 
+while writing executable code. 
+
+The reference implementation is at [1] and the official Wiki is at [2]
+
+Quoting from the original project:
+
+    The design goal was to make a language with beautiful source code that 
+    resembled Shakespeare plays. There are no fancy data or control structures, 
+    just basic arithmetic and gotos. You could say we have combined the ex- 
+    pressiveness of BASIC with the user-friendliness of assembly language. 
+
+How Reductive! SPL is a great achievement in unifying art and code, a noble
+goal which must not be underestimated.
+
+USING
+-----
+If you are reading this you must have obtained the shakespeare-parrot 
+distribution, and I congratulate you. 
+Put the files in a languages/shakespeare/ directory in a parrot source tree
+and run make. 
+make test will execute the test suite, to run your own file use
+    ../../parrot shakespeare.pir filename.spl
+since we used the standard parrot's HLLCompiler you can use the usual flags 
+such as --target=(parse|pir) to see the parse three and the PIR output.
+
+IMPLEMENTATION
+-----
+The original SPL project generates C code that con be compiled and linked with
+libspl to generate executables, through SPLC.
+The parser is built with yacc/bison and the lexer is flex. The Perl port[3] uses
+the same parser and lexer.
+
+This parrot version uses PGE to parse the grammar and generate and AST, 
+The parrot toolchain allows automatic transforming the PAST (Parrot AST) into
+POST and then PIR (parrot's high level assembly).
+
+When executed this code is translated into bytecode and it uses the functions 
+defined in src/builtins/base.pir to operate. 
+
+The runtime uses some global variables:
+* the_cast contains a list of characters, each one a tuple 
+  (value, stack, name, onstage flag)
+* the_speaker refers the current speaker, so that the references "thou" and "me"
+  are meaningful. Using objects wa another option but overkill.
+* the_condition is a boolean value that gets set from a statement 
+  ("is foo better than bar") and is later refered. Inlining of the 
+  value would require a lot of work when building the AST, while the bytecode 
+  compiler should have no problems doing it. 
+
+
+Although I did not initially look at the original source code while writing 
+the interpreter it seems that the behaviour of SPLC is the same.
+
+The list of valid words was originally generated from a list of wordlist files 
+with an AWK script I have lost track of. It's in the TODO list to fix it.
+
+Notice that since PGE doesn't do (yet) longest token matching a token like this
+    token article  {
+        | 'a'
+        | 'an'
+        | 'the'
+    }
+would cause a failure to parse "an empty bottle". The words where I had test 
+failures were reverted by hand, some may still cause failures. 
+
+
+LANGUAGE EXTENSIONS FOR TESTING SUPPORT
+---------------------------------------
+
+Shakespeare did not originally support testing explicitly, but in the modern
+world of software engineering this would have prohibited building large scale
+dramatic-software projects. 
+
+Thus, I've added two new instructions to the language to minimally support the
+Test Anything Protocol (TAP)[4]
+ * plan an evil thing!
+   will print "1..2". Every valid value can be used after the word 'plan'.
+   Suggestions for improving are welcome.
+ * proove yourself!
+   will print "ok x" where x is the value of the spoken character. 
+   Every valid value can be used after the word 'proove'
+
+Test failure is reached through out-of order printing, so for example
+
+   Scene I: a test.
+   juliet: art thou better than me?
+   romeo: if so, let us proceed to scene ii.
+   juliet: proove nothing.
+ 
+   Scene II: the right branch.
+   juliet: proove the joy!
+
+Will print "ok 1" if juliet is better than romeo, which is fine.
+If Romeo has an higher value than Juliet "ok 0" will be printed, and considered 
+as a test failure from the test harness.
+
+DIFFERENCES FROM OTHER IMPLEMENTATIONS
+--------------------------------------
+
+I wrote the parser trying not to look at the original grammar, using only the 
+examples. This means that in some ways the parser is more restrictive and in 
+some ways it is more loose. Until we have an ISO specification for SPL it is
+assumed that this is ok. 
+
+
+EXAMPLES
+--------
+The files in example are the original files used in both Lingua::Shakespeare and
+SPLC, and their operation is checked through the script t/test.rb.
+To verify that everything works you can run "make fulltest" which will execute
+both the standard test suite and the examples' test suite. 
+