= 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.

