RELEASENOTE
Path: RELEASENOTE
Modified: Wed Mar 05 16:04:48 JST 2003

amrita V2.0 release note

This document is for amrita V1.0 users.

Quick Upgrading

Some APIs are changed in V2.0 but 'amrita/v1api' module is provided for V1.0 users. Most of V1.0 users can use V2.0 only by inserting this statement into the source.

   require 'amrita/v1api'
   require 'amrita/accel'

Or invoking ruby with this option

   $ ruby -r amrita/v1api -r amrita/accel your_script_using_amrita_v1.rb

VM-architecture

amrita V2.0 always converts template to BYTECODE: a internal parsed tree to execute expansion of templates. And BYTECODEs will be executed in three environment.

  * on-demand translation

    If 'amrita/accel' is not loaded or amrita_accel.so is not your
    RUBYLIB directories, amrita V2 will run in this mode.
    In pure-ruby environment, BYTECODEs will be executed by pure-ruby
    virtual machine. This VM translate BYTECODE to ruby-code and
    'eval' it.

    This is similar to prior version of 'use_compiler' option. But
    there is a big difference. The pure-ruby VM dose not translate
    BYTECODE all at once, but translate it partially on-demand so that
    it will do only works truely needed. This eliminate the start-up
    load needed with 'use_compiler' option of prior version.
  * amrita accelerator

    If amrita_accel.so was installed correctly and amrita/accel is
    loaded, amrita V2 will run in this mode.
    In this mode, the VM written in C language as a Ruby extention
    module will execute BYTECODE direct.

  * amcc -- static template compiler
    amcc is a command line utility that converts a group of html/xml
    templates to a Ruby extention module. By using this extention
    module, you can get a CCompiledTemplate object that is equivalent
    to a TemalateFile object. But its expand method is implemented in
    C code so it runs much faster than amrita accelerator.

    But amcc has two drawbacks in return to speed up
      * You need to compile a template every time you edit it.

      * You should edit your ruby script like this.
        require 'ext/amccout.so' # load the extention module you compiled
        path = .....             # set the path of your template file
        tmplate = Amccout::Templates[path] || TemplateFile.new(path)

      * An extra work is needed to reduce the compile time in some cases.
        Sometimes amcc produce milions of lines of C-code and the C
        compiler spawnd by amcc won't complete its work. You need to
        insert PRAGMAs in your template.

API change in main features

  * API of class Template is not changed

    class Amrita::Template and classes derived from it will have
    almost same API. These samples run without change using amrita/v1api.
      * sample/hello/*
      * sample/tour/time.rb
      * sample/tour/makeurl.rb
      * sample/tour/makeurl2.rb
      * sample/tour/xml1.rb
      * sample/tour/xml2.rb
      * sample/tour/xml3.rb
      * sample/tour/xhtml.rb

  * Proc object
    A Proc object can be passed as a model data, but amrita V2.0 will
    pass extra parameters to the Proc. So, if you are using Proc
    objects, you need to edit

       proc do |elem|
         ...
       end
    to

       proc do |elem, *args|
         ...
       end
    You can touch the internal of amrita-VM for performance with the
    extra 'args'. They are described in the document 'INTERNAL'.

  * compatibility layer
    Some options of Template will change. For example,
    'Template#expand_attr=' is deleted because it is always true in
    V2.0

    To save this kind of change, I wrote amrita/v1api. You can load
    this module kicking ruby like
      ruby -r amrita/v1api xxxx.rb

    or insert " require 'amrita/v1api' " in your code.
  * low level API

    Low level APIs are changed especially these sources
       amrita/compiler.rb
       amrita/format.rb
       amrita/node_expand.rb

    If you are using this APIs direct, I'm afraid you should change
    your application to use V2.0.

Amulet

(under construction)

experimental features

  * expand_attr (<a href="@url"> => <a href="http://www.ruby-lang.org/")

    This feature is supported and will be always 'ON' in V2.0
  * ams

    no change, supported but remain experimental in V2.0
  * amx

    no change, supported but remain experimental in V2.0. I will
    refine this feature by using Amulet after V2.0 release
  * cgikit

    supported but will be changed to adapting it to new verstion of
    CGIKit and amrita's new architecture.
  * PartsTemplate

    supported but it was re-inplemented by using Amulet. This feature
    is now obsolete.
  * MergeTemplate

    not supported. use Amulet instead.