This document describes major changes to Water since Nov 21, 2004 Water v5 has a considerable number of changes since Water v4. The purpose of those changes were to make Water easier to learn, easier to use, more flexible, faster running and have a broader scope of applicability. Water v4 source code will not run in v5.

How to Convert Your Version 4 code to Version 5

  1. Save your old code in a safe place
  2. Bring a copy of your old code up in the editor
  3. Select it.
  4. Choose the right click menu, Convert Selection to / Water version 5.
This will make the most common easy changes but certainly not all. Note that this is computationally expensive and will take a while. On one fast laptop, converting a large (80K charcters) file took 20 seconds. Run your new code and compare it to the old code. It helps if you have calls to "test" in your old code that you can run in version 5. Note that you can convert tests just like you convert regular code. For difficult code sections it will hep to be able to run the coe in version 4 and compare intermediate values.

Major New Features

Math

Rich UI - ui.lines lets you draw points, lines, and polygons Can change line thickness, colors, translation, rotation and scaling. Useful for 2D graphics including animation. - Dialog boxes including: - a general purpose one that allows arbitrary other rich ui components as content and a "multiple choice" button set. See ui.show_dialog - a "yes/No" one that returns true or false: See ui.show_boolean_dialog - One that gets a string from the user: see ui.show_input_dialog - one that lets you choose file(s) and/or folder(s). see ui.show_file_dialog for_each - Powerful generalization of the old "returns" parameter. It now is called "combiner" and takes a method as an argument that lets you combine the result of each iteration in an infinite variety of ways such as collect a vector, join strings or add up numbers for a total. - Takes a number as a subject, and loops that number of times. Defmethod and Defclass Major new facility for making it easier to pass in arguments in a variety of formats. respelling of names and change of _subject. See below for details ekind.bytes A new execution kind that makes it possible to put any string in an XML tag without special quoting, even if it has unmatched angle brackets or other wierd characters. Formatters: Provides different levels of printed representations of objects. Operating System Interface new "os" class lets you execute a string as if in a "shell" or "dos prompt" on the os, returns the 'printed out' string as the value. new "ping" method for testing internet connectivity. Java calling Water Interface A new Java class named 'Water" makes it much easier to call Water from Java. Water User Folder For Windows OS, the default location of the water_user_folder has been C:\Documents and Settings\user-name\water_user_folder. The Windows US makes it hard to get to this diretory. The new default loacation is C:\Documents and Settings\user-name\My Documents\water_user_folder. which is much easier to get to via "My Documents". If you have your water_user_folder inthe lold location, it will still work, but you get a warning message in the console saing that it will be easier to work with if you simply move the folder to the new location. ROOT OBJECT The new root object is called "wob" for water object. There still is a 'thing' class for making random objects, It is a subclass of wob. wob is "tight" and doesn't allow making instances with random additional fields, but thing still does. Inheritance of fields has been made more uniform throughout. If you inherit from wob, you won't automatically be allowed to add _other_unkeyed and _other_keyed fields when creating an instance, but inherited from thing or anything that supports _other_unekeyd and _other_keyed will let you add those fields. VECTOR v is now a shortcut for vector as in to make a vector of items. SVG Scalable Vector Graphics tags have been define. See Right click menu, SVG submenu for examples. Documentation: Expanded table of contents and new index. Contracts are shown in a table as well as in CXS. Expanded Quick Reference Guide. The "doc" class now has a body that takes calls to test in it. These are formatted for presentation as an example when the doc is formatted but they can also be used as test cases. You can use the Test menu to run such files through the test runner. New example files. Error Messages More accurate selection of the source code where an error occurred. Improved error messages, some of which tell you when you've typed in something that looks like java or C what the equivalent Water is. IDE Selecting expressions by double-clicking on the end of a tag. Upper right result pane tells you what source code created the result. new right click insert menus for: Documentation Creation Math (trigonometry, random, advanced) Misc/java Vector Performance: General code speed up about 2.5 times Formatting HTML sped up more than 10 times. Testing test now takes a 'language' parameter whose value defaults to "water" but can also be "java" to facilitate testing your Java code. More test cases. Accessible from the doc. Plus a whole bunch of minor improvements all over the place! __________________ Incompatibilities Most of the syntax and semantics of the language remain the same. Some major changes were required to simplify things while increasing functionality. There is a new 'deprecation' facility that often will give error messages that tell you what has changed and how to update your code. But this doesn't work perfectly for everything, and besides its good to know what you're in for in converting old code. Below are the most common things you'll likely run in to. Version 4 == Version 5 CLASSES METHODS All uses of "expr" have been changed to "expression". All of these except wobl.expr are unlikely to have been used by most users. PARAMETERS FIELDS _new_object == _subject (in a 'make' method), _new_class == _subject (at top level within a call to class) SYNTAX \n == (now using the XML escape character convention instead of C-language convention) DO 'do' no longer takes attributes do-repeat now uses for_each. counter Becomes: 5. value FOR_EACH instead of: primes. value use something like: primes. value. skip else value Lots of new features in for_each. Please read the documentation on it. LAST now 0 (instead of 1) refers to the last element in the vector. DEFMETHOD & DEFCLASS Methods and classes are now more similar. If they define _other_unkeyed, must now all have the same ekind for _other_unkeyed. If that ekind is something other than ekind.code (the default) then it must be defined before the first call, in the order that the source code is loaded. Sometimes its inconvenient to do so, so there is a new method named declare_other_unkeyed_ekind which lets you declare the ekind of a call before the method of the call is defined. This helps the parser do the right thing. When defining a parameter in a call to method or class, the type (if any) must be in the 3rd position and the ekind (if any) must be in the 4th position. Before these two were interchangeable. the new 5th position is the "name" used only for _other_unkeyed. When calling methods or classes that have both optional parameters and _other_unkeyed, all unkeyed args will go to the _other_unkeyed parameter. Thus any optional args must be passed via key. Example: y y "defclass" is now spelled "class" "defmethod" is now spelled "method". This is shorter, doesn't leave you wondering what the "def" means, and, in the case of "method", since we are making an instance of method and "method" is the name of a class, it makes more sense than defmethod. "class" is still a method, just like defclass was. Now neither take subjects. If you want to stick a method in a class, use to make a method named "launch" in the class "boat". You can still do