Upgrading from older versions

If you are upgrading from an older version of Kaya you may need to make minor changes to your code. This page explains the necessary changes (versions that require no changes are not listed). Changes that will be required in future versions are also listed to allow preparation. In most cases these changes will not affect the majority of users - exceptions are highlighted by the word "MAJOR" at the start of the description.

Now Kaya 0.4 has been released, development will be split into a 0.4.x stable branch (which will not have upgrade incompatibilities unless they are absolutely essential to fix a serious or security-related bug) and a 0.5.x testing/development branch in which (usually minor) incompatibilities like those below may occur. New features will be brought back into the stable branch from the testing branch only if it can be done without disruption, but bugs will be fixed in both branches wherever possible. In general, upgrades from 0.4.x to 0.4.y (y>x) will not have incompatibilities.

Upgrades to 0.5.1

• DB::DBValue now has a new constructor DBNull for NULL values returned from queries. All the coercion functions are updated to use this, and a new isNull function can be used to test for this value. If you do your own case pattern matching on DBValue then you will need to take account of this new constructor (or move to using the provided coercion functions). Writers of database interface libraries need not make changes, but may wish to.

Upgrades to 0.5.0

• DB::DBHandle is now declared abstract to prevent accidental modifications. This will affect people writing their own database connection libraries, who will need to use the getHandle function. The source code for the existing database modules should provide useful examples.
• ltruncate, rtruncate and behead have been moved to the Prelude module. This is unlikely to affect most programs unless you have specified Strings::ltruncate at some point.

Upgrades to 0.4.0

• As advertised, all previously deprecated functions, data types and exceptions have now been removed from the modules distributed with Kaya. Using the -deprfail option when compiling will make it easier to detect these before upgrading. No new functions have been deprecated since 0.2.7
• MAJOR: Lambda functions may now modify variables in the containing scope. See the end of the functions tutorial for the implications of this. While this behaviour is correct and necessary, code written expecting the old behaviour may not work.
• The data types for colour and weight in the Kayurses module have been changed. The ColourName type has been removed entirely, although applications that worked previously should continue to work provided that they did not reference the colours as Kayurses::Red. Some of the constructors of the WeightName type have changed name, to avoid conflicts with constructors of the same name in Curses. This changes the requirement from specifying the module to renaming the constructor, which is backward incompatible but hopefully should be simpler in future.
• The rekey and xml2man utilities have been renamed to kaya-rekey and kayadoc2man respectively, to avoid conflicts with other applications.
• The KayaDoc::NoSuchEntry exception now has a String parameter that contains a description of the error. Code using this Exception must be updated to use the new type.

Upgrades to 0.2.7

• The syntax of the case statement has changed to allow full pattern matching. One consequence is that patterns are now matched in top-to-bottom order, which may cause different behaviour if the default pattern is not last (the default pattern is now represented by _ - the use of defaultstill works for now, but is strongly deprecated and may cause occasional obscure errors).
• let is now a keyword and may not be used as a variable name.
• To support prepared SQL statements, the internal format of the DBHandle data type is changing. This will not affect most users, but will affect anyone who has written their own database access library using the DB API.
• An undocumented part of the C foreign functions API which allowed foreign functions to return char* when the Kaya-side type was String has now been removed. All functions with a Kaya-side return type of String should return KString (wchar_t* - use the KSTRING() macro for conversion). Foreign function interfaces relying on this obsolete and undocumented API must be updated (note that KString has been the preferred and supported return type since Kaya 0.2.0)
• The internal format of the application encryption keys has changed. Versions of the rekey program from Kaya 0.2.6 and earlier will therefore not be able to rekey Kaya applications from Kaya 0.2.7 or later. However, Kaya 0.2.7's rekey can rekey applications produced by earlier versions of Kaya.
• CGI::flush is now flushAll. While the usual deprecation policy is being followed, there is a potential overloading conflict between CGI::flush and the new IO::flush which is likely to make this more urgent to fix. Consider whether CGI::flushAll needs to be used at all within the application.

Upgrades to 0.2.6

• MAJOR: File is no longer a primitive data type - it is instead defined by the IO module. This has the following consequences:
  • Foreign function interfaces that deal with the C type FILE* will need to be rewritten. The file and ptr coercions are provided for this purpose. You may in some cases need to write an additional wrapper function to convert between FILE* and void*.
  • Modules that export data types containing File must now contain import public IO; to ensure that File is available to modules importing them.
  • The functionsPrelude::stdin, Prelude::stdout and Prelude::stderr have been moved to the IO module. Unfortunately it is not possible to provide deprecated versions in the prelude, so references to these functions in modules that do not import IO or that use the module name to refer to them will no longer work.
  • Attempting to write to a closed file handle, or read from a write-only file handle, etc. will now throw an Exception instead of silently failing or writing to a different file handle. If your code relied on this incorrect behaviour it will need to be rewritten.
• The PDCurses module is no longer provided with Kaya 0.2.6 onwards. Instead, the Curses module will link to ncurses or pdcurses as appropriate for the platform. This will make writing portable code easier in future, but requires existing code that imports PDCurses to be changed. If you only access Curses functions via the Kayurses module, then you will not need to make any changes.
• The SDL SDLEvent data type's KeyDown constructor now has a second parameter, which describes the modifier keys (e.g. Ctrl, Alt, Shift) that are available. Unfortunately, as a data type is affected, deprecation is not possible. Code that uses this constructor will have to be modified.
• The final parameter of readString has been removed. Since this parameter was optional and did nothing, no deprecated version has been provided. However, if you never set this optional parameter, your programs will compile exactly as before. Additionally, KayaDoc::maniseList is no longer public (use maniseContents instead).
• The openCipher and openHash functions have each had their final optional parameter (opening flags) changed from an Int to a list of entries from a more meaningful data type. No deprecation is provided for the old version, as this causes problems for the majority of uses where the parameter was left unspecified. Since this optional parameter was virtually unusable in practice anyway this should not cause any noticeable effect for most users.
• In the Posix module, the exception thrown by the system function on non-zero exit status now has the parameter of the exit status. For historical reasons, in previous Kaya versions this parameter would be -1*exit_status, and so while the change makes more sense (and is consistent with pclose), this may break existing code.

Upgrades to 0.2.5

• The final parameter of replace when the first parameter is a compiled regular expression has been removed. Since this parameter was optional and did absolutely nothing, no deprecated version has been provided. However, if you never set this optional parameter, your programs will compile exactly as before.
• A long-standing bug regarding assignment of array elements has now been fixed. Programs relying on the old buggy behaviour will need to be changed. In Kaya 0.2.4 and earlier, the code

  x = 5;
  a = [x,x+2];
  x++;
  putStr(a[0]+" "+a[1]+" "+x);

  would give 6 7 6. It now correctly gives 5 7 6.

Upgrades to 0.2.4

• MAJOR: A new syntax for Exceptions. The old syntax may be used by prepending the Exception definitions with a '%', but you should switch to the new Exception syntax as soon as possible, as this gives more control over catching Exceptions, and the old syntax will be removed in the future 0.3.0 version.
• MAJOR: Some changes have been made to file upload handling. It is no longer enabled by default, and the Uploaded type is now an abstract type. If you use file uploads, therefore, you must explicitly enable file uploads in your web applications, and use the access functions to retrieve data about the uploaded files. The file upload tutorial explains how to do this and covers other aspects of file uploading.

Upgrades to 0.2.1

• MAJOR: The Webprog and Webapp modules and associated file headers have now been renamed to Webapp and CGI respectively. You will therefore need to change any webprog x; lines to webapp x; and any webapp x; lines to cgi x;, and equivalent changes to import Webprog; and import Webapp;.

Upgrades to 0.2.0

• MAJOR: 'Pass by reference' is no longer the default for function arguments. Instead, a 'shallow copy' is the default. If you wish to allow a function to modify its arguments, you must use the var keyword. This is not necessary as often as you might expect - read the function parameters section of the functions tutorial for a more detailed explanation.