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