JPiccola 3.6a Release Notes =========================== For questions, bug reports, and suggestions please contact: Stefan Kneubuehl Andreas Schlapbach Oscar Nierstrasz 0 Contents ========== 1 Installation 1.1 Requirements 1.2 Downloading JPiccola 1.3 Starting JPiccola 1.4 Embedding JPiccola 2 Piccola Runtime Environment 2.1 Changes since 3.4c 2.2 Changes since 3.4b 2.3 Changes since 3.4a 2.4 Changes since 3.3b 3 Full Distribution 3.1 Quick Start 3.2 Required Tools 3.3 Directory Structure 3.4 Building JPiccola 4 Known Issues 1 Installation ============== 1.1 Requirements ---------------- JPiccola requires the Java 2 Runtime Environment version 1.3.1 or better. If you don't have Java installed on your system, you can download it from http://java.sun.com 1.2 Downloading JPiccola ------------------------ Download the file JPiccola3.6a.jar from http://www.iam.unibe.ch/~scg/Research/Piccola and save it on your local system. 1.3 Starting JPiccola --------------------- To start JPiccola, use the following command: java -jar JPiccola3.6a.jar A prelude script can be specified using the "piccola.prelude" system property: java -Dprelude.picl=myprelude.picl -jar JPiccola34c.jar To execute a specific script, use the following syntax: java -jar JPiccola3.6a.jar myscript.picl The prelude as well as the script to execute are treated as Piccola resources (see description of getResource() in secion 2.3) 1.4 Embedding JPiccola ---------------------- The JPiccola 3.6a runtime environment can be embedded in any Java application. Create a Piccola runtime environment, instantiate the ch.unibe.piccol.Host class. Initialize the host (executes prelude.picl), then run a script using one of the execute... methods. Use setOut() to redirect Piccola standard output. Host host = new ch.unibe.piccola.Host(); // Output goes to System.out host.initialize(); host.executeScript("myscript.picl"); host.setOut(new FileOutputStream("piccola.out")); host.executeCode("println \"Hello World\""); 2 Piccola Runtime Environment ============================= 2.1 Changes since 3.4c ---------------------- * Enhanced support for Java arrays: added services for creation and manipulation of arrays: Integer = Host.class "java.lang.Integer" # NEW: Java class forms provide newArray service to create arrays arr = Integer.newArray 3 # NEW: Array forms provide set service to alter data arr.set(at = 0, value = 1) arr.set(at = 1, value = 4) arr.set(at = 2, value = 9) # prints 1, 4, 9 on seperate lines arr.forEach println * Alternate passing of multiple arguments to Java services: Now you can use Piccola lists to specify multiple arguments for a Java call instead of val-bindings: System = Host.class "java.lang.System" # Old, val-bindings System.setProperty(val1 = "ui.language", val2 = "german") # NEW: use Piccola list System.setProperty["ui.language", "german"] * Added support for URLClassLoader to Piccola Standard Library: # NEW: newURLClassLoader service accepts an URL and returns # class loader providing class service similar to Host.class cl1 = newURLClassLoader newURL("http://www.iam.unibe.ch/~scg/PiccolaTest.jar") # Tries to load class from JAR file MyClass = cl1.class("MyClass") # NEW: newLocalClassLoader accepts path an returns # class loader for URL "file:[path]" cl2 = newLocalClassLoader "/test/myclasses" # Tries to load class from URL "file:/test/myclasses/MyClass.class" MyClass = cl2.class("MyClass") The library script classLoader.picl is deprecated. 2.2 Changes since 3.4b ---------------------- * Use setAutoAbort service to specify whether the Piccola environment should be exited when no Piccola agents are active. Set autoAbort to false when using GUI. * The Piccola engine can now be embedded in Java applications. See 1.4. * new standard prefix operator introduced: $aForm returns a string representation of aForm: # no longer supported: aForm = myAsString: "This is a Form." string = asString(aForm) # as of JPiccola 3.4c aForm = $_: "This is a Form." string = $aForm * The label homeURL is no longer bound to a service, but directly to a form representing the script's URL. * Automatic wrapping Java object wrapping is now automated for all Java objects, not only for literals. Use the registerWrapper service to register a new Piccola wrapper at the Piccola engine: myStringWrapper X: X length: X.size() Host.registerWrapper "java.lang.String" myStringWrapper Only one wrapper is applied to each Java object introduced into the Piccola environment. The wrapper is determined in the following way: 1. Use wrapper registered for object's class. 2. If not registered, use wrapper for the superclass of object's class, recursively. Wrappers are not applied recursively, i.e. no wrappers are applied while executing wrapper code, e.g.: myStringWrapper X: X hello = "Hello" # no wrapper applied here! myStringWrapper X: X hello: "Hello" # this is ok 2.3 Changes since 3.4a ---------------------- * Form explorer is now implemented in Piccola. Java implementation has been removed. * The wrapper service Hook.wrapBoolean is now applied to all objects that are upped to Piccola and that are instances of class Boolean. * IForm's toString() now calls Piccola service bound to form's toString label if available. * Included first part of Piccola core library reference in HTML. * Fixed cascaded fixed point bug. Added PiUnit test. * Removed pop-up menu from Piccola console. Use frame menu or key shortcuts. * Included Oscar's demo scripts. * Added GenericTreeExpansionListener and GenericTreeWillExpandListener. 2.4 Changes since 3.3b ---------------------- * Underscores '_' are allowed in identifiers. E.g. # valid JPiccola code since 3.4a: MY_LABEL = () * The syntax of the collections' new operator label has changed: Old syntax: DefaultOp._new[]_ New syntax: DefaultOp.[_] * The wrapper services Hook.wrapNumber and Hook.wrapString are now applied to all objects that are upped to Piccola and that are instances of class Number respectively String. Until JPiccola 3.3, these services have benn only applied to literals. * Wrapped Java objects do no longer contain static fields. Until JPiccola 3.3b, a wrapped Java object contained bindings for the public static fields of the object's class. This is no longer the case, since such wrapped objects may be "infinite forms", i.e. not real forms (think about it!). Use wrapped classes to access public static fields. # JPiccola 3.3 code: layoutManager = Host.class("java.awt.BorderLayout").new() panel.setLayout(val = layoutManager) panel.add(val = component, val1 = layoutManager.NORTH) # JPiccola 3.4 code: BorderLayout = Host.class "java.awt.BorderLayout" layoutManager = BorderLayout.new() panel.setLayout layoutManager # the form bound to layoutManager does not contain a NORTH binding! panel.add(val1 = component, val2 = BorderLayout.NORTH) * New Java call conventions: To call a Java method with one argument, the argument can be passed directly (without val binding). E.g: System = Host.class "java.lang.System" System.out.println "Hello World" To call a Java method with multiple arguments, use the label val1 for the first argument, val2 for the second, ... E.g: # evaluates to "ello" "Hello World".substring(val1 = 1, val2 = 5) The old calling conventions are still supported but deprecated. * There are now following load services available: # loads the script described by the specified URL: load url context: # loads the file described as relative path to the current script's # location: loadRelative script context: # loads the file described as relative path to the prelude's location: loadCore script context: # tries to find the script's url with the getResource() service # (see below): loadResource script context: * Host now provides a getResource service which tries to find an URL for a specified resource name. The search order for such resources is the following: 1) If the resource name is a full URL, only this URL is used. Otherwise, the following rules apply: 2.a) Using the getResource() method of the Host's ClassLoader. This results in the following search path: - the Piccola JAR file, if the runtime distribution is used, - the Java classpath, otherwise. 2.b) Relative to the "user.dir" Java system property, i.e. in the user's current working directory. Example 1: home/kneubuhl: java -jar piccola/JPiccola3.4a.jar myscripts/test.picl search order: 1) "myscripts/test.picl" is no URL, skip 2.a) /home/kneubuhl/piccola/JPiccola3.4a.jar!myscripts/test.picl 2.b) /home/kneubuhl/myscripts/test.picl Example 2: java -jar JPiccola3.4a.jar http://www.kneubuehl.com/piccola/test.picl search order: 1) URL "http://www.kneubuehl.com/piccola/test.picl" 2.a) skip 2.b) skip Example 3: home/kneubuhl: java -classpath /lib;/home/kneubuhl/piccola ch.unibe.piccola.host.Host test.picl search order: 1) "test.picl" is no URL, skip 2.a) /lib/test.picl 2.a) /home/kneubuhl/piccola/test.picl 2.b) /home/kneubuhl/test.picl 3 Full Distribution =================== 3.1 Quick Start --------------- a) Install - Java 2 Platform, Standard Edition (J2SE) 1.3.1 or better (http://java.sun.com/j2se/) - Apache Ant 1.4 (http://jakarta.apache.org/ant/) b) Configure - CLASSPATH = 'extlib/bcel.jar:extlib/junit.jar:extlib/jakarta-ant-1.4.1-optional.jar' c) Compile - ant dbuild d) Test - ant test e) Run - ant drun 3.1 Required Tools ------------------ Required for all tasks: - Java 2 Platform, Standard Edition (J2SE) 1.3.1 or better (http://java.sun.com/j2se/) - Apache Ant 1.4 (ant.jar) (http://jakarta.apache.org/ant/) - Apache Ant 1.4 Optional Tasks (jakarta-ant-1.4.1-optional.jar) Required for compilation (dmake, dbuild, ...) - JUnit 3.7 (junit.jar) http://www.junit.org - bcel (bcel.jar) Required for parser generation (parser) - Java Compiler Compiler (JavaCC) 2.0 (JavaCC.jar) http://www.webgain.com/products/java_cc/ Required for package dependency test (jdepend) - JDepend 2.2 (jdepend.jar) http://www.clarkware.com/software/JDepend.html Required for performance analysis (prof) - Performance Analysis Tool PerfAnal (PerfAnal.jar) http://developer.java.sun.com/developer/technicalArticles/Programming/perfanal/PerfAnal.jar All tools but J2SE and Ant are included in the extlib directory 3.2 Directory Structure ----------------------- / JPiccola home directory |-- build Build directory | |-- ch -- unibe -- piccola Java classes | |-- demo Piccola demo scripts | |-- lib Piccola library | | '-- test Piccola library tests | '-- resource Piccola resources (e.g. icons) |-- javadoc Javadoc HTML files |-- extlib External libraries (JARs) '-- source |-- java -- ch -- unibe -- piccola Java source files '-- piccola Piccola source files |-- demo Piccola demo scripts |-- lib Piccola library | '-- test Piccola library tests '-- resource Piccola resources (e.g. icons) 3.3 Building JPiccola --------------------- The build process for JPiccola is based on the Jakarta ANT build tool. Use the following command in the JPiccola home directory: ant [target] where [target] is any of the following: antdtd : Creates an Ant DTD file for use with XML editors. doc : Generates JavaDoc. clean : Removes build directory. DEVELOPMENT BUILD parser : Generates the files Parser.java and ParserTokenManager.java using JavaCC and the parser specification Parser.jj. dmake : Performs debug compilation of Java sources (debug on, optimization off). dbuild : Performs clean before running dmake. drun : Runs Piccola after performing dmake. RELEASE BUILD rmake : Performs release compilation of Java sources (debug off, optimization on). jar : Creates a runtime JAR file in the Piccola home directory based on a release compilation (debug off, optimization on). TESTING / ANALYZING jdepend : Class / Package dependency analysis prof : Performance analysis jtest : Runs JUnit tests. ptest : Runs PiUnit tests. dtest : Runs PiUnit tests for demos. test : Runs JUnit and PiUnit tests.