|
This document is for amrita V1.0 users.
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
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 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.
(under construction)
* 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.