The Ruby mapping supports two forms of code generation: dynamic and static.
On this page:
Using dynamic code generation, Slice files are "loaded" at run time and dynamically translated into Ruby code, which is immediately compiled and available for use by the application. This is accomplished using the Ice::loadSlice
method, as shown in the following example:
{zcode:rb} Ice::loadSlice("Color.ice") puts "My favorite color is #{M::Color.blue.to_s}" {zcode} |
For this example, we assume that Color.ice
contains the following definitions:
{zcode:slice} module M { enum Color { red, green, blue }; }; {zcode} |
Ice::loadSlice
Options in RubyThe Ice::loadSlice
method behaves like a Slice compiler in that it accepts command-line arguments for specifying preprocessor options and controlling code generation. The arguments must include at least one Slice file.
The function has the following Ruby definition:
{zcode:rb} def loadSlice(cmd, args=[]) {zcode} |
The command-line arguments can be specified entirely in the first argument, cmd
, which must be a string. The optional second argument can be used to pass additional command-line arguments as a list; this is useful when the caller already has the arguments in list form. The function always returns nil
.
For example, the following calls to Ice::loadSlice
are functionally equivalent:
{zcode:rb} Ice::loadSlice("-I/opt/IceRuby/slice Color.ice") Ice::loadSlice("-I/opt/IceRuby/slice", ["Color.ice"]) Ice::loadSlice("", ["-I/opt/IceRuby/slice", "Color.ice"]) {zcode} |
In addition to the standard compiler options, Ice::loadSlice
also supports the following command-line options:
--all
--checksum
If your Slice files depend on Ice types, you can avoid hard-coding the path name of your Ice installation directory by calling the Ice::getSliceDir
function:
{zcode:rb} Ice::loadSlice("-I" + Ice::getSliceDir() + " Color.ice") {zcode} |
This function attempts to locate the slice
subdirectory of your Ice installation using an algorithm that succeeds for the following scenarios:
make install
If the slice
subdirectory can be found, getSliceDir
returns its absolute path name, otherwise the function returns nil
.
You can specify as many Slice files as necessary in a single invocation of Ice::loadSlice
, as shown below:
{zcode:rb} Ice::loadSlice("Syscall.ice Process.ice") {zcode} |
Alternatively, you can call Ice::loadSlice
several times:
{zcode:rb} Ice::loadSlice("Syscall.ice") Ice::loadSlice("Process.ice") {zcode} |
If a Slice file includes another file, the default behavior of Ice::loadSlice
generates Ruby code only for the named file. For example, suppose Syscall.ice
includes Process.ice
as follows:
{zcode:slice} // Syscall.ice #include <Process.ice> ... {zcode} |
If you call Ice::loadSlice("-I. Syscall.ice")
, Ruby code is not generated for the Slice definitions in Process.ice
or for any definitions that may be included by Process.ice
. If you also need code to be generated for included files, one solution is to load them individually in subsequent calls to Ice::loadSlice
. However, it is much simpler, not to mention more efficient, to use the --all
option instead:
{zcode:rb} Ice::loadSlice("--all -I. Syscall.ice") {zcode} |
When you specify --all
, Ice::loadSlice
generates Ruby code for all Slice definitions included directly or indirectly from the named Slice files.
There is no harm in loading a Slice file multiple times, aside from the additional overhead associated with code generation. For example, this situation could arise when you need to load multiple top-level Slice files that happen to include a common subset of nested files. Suppose that we need to load both Syscall.ice
and Kernel.ice
, both of which include Process.ice
. The simplest way to load both files is with a single call to Ice::loadSlice
:
{zcode:rb} Ice::loadSlice("--all -I. Syscall.ice Kernel.ice") {zcode} |
Although this invocation causes the Ice extension to generate code twice for Process.ice
, the generated code is structured so that the interpreter ignores duplicate definitions. We could have avoided generating unnecessary code with the following sequence of steps:
{zcode:rb} Ice::loadSlice("--all -I. Syscall.ice") Ice::loadSlice("-I. Kernel.ice") {zcode} |
In more complex cases, however, it can be difficult or impossible to completely avoid this situation, and the overhead of code generation is usually not significant enough to justify such an effort.
The Ice::loadSlice
method must be called outside of any module scope. For example, the following code is incorrect:
{zcode:rb} # WRONG module M Ice::loadSlice("--all -I. Syscall.ice Kernel.ice") ... end {zcode} |
You should be familiar with static code generation if you have used other Slice language mappings, such as C++ or Java. Using static code generation, the Slice compiler slice2rb
generates Ruby code from your Slice definitions.
For each Slice file X.ice
, slice2rb
generates Ruby code into a file named X.rb
in the output directory. The default output directory is the current working directory, but a different directory can be specified using the --output-dir
option.
It is important to understand how slice2rb
handles include files. In the absence of the --all
option, the compiler does not generate Ruby code for Slice definitions in included files. Rather, the compiler translates Slice #include
statements into Ruby require
statements in the following manner:
-I
option) and removing the leading directory from the included file if possible./opt/App/slice/OS/Process.ice
, and we specified the options -I/opt/App
and -I/opt/App/slice
, then the shortest relative pathname is OS/Process.ice
after removing /opt/App/slice
..ice
extension with .rb
. Continuing our example from the previous step, the translated require
statement becomes
{zcode} require "OS/Process.rb" {zcode} |
As a result, you can use -I
options to tailor the require
statements generated by the compiler in order to avoid absolute pathnames and match the organizational structure of your application's source files.
There are several issues to consider when evaluating your requirements for code generation.
The requirements of your application generally dictate whether you should use dynamic or static code generation. Dynamic code generation is convenient for a number of reasons:
Static code generation, on the other hand, is appropriate in many situations:
You can safely use a combination of static and dynamic translation in an application. For it to work properly, you must correctly manage the include paths for Slice translation and the Ruby interpreter so that the statically-generated code can be imported properly by require
.
For example, suppose you want to dynamically load the following Slice definitions:
{zcode:slice} #include <Glacier2/Session.ice> module MyApp { interface MySession extends Glacier2::Session { // ... }; }; {zcode} |
Whether the included file Glacier2/Session.ice
is loaded dynamically or statically is determined by the presence of the --all
option:
{zcode:rb} sliceDir = "-I#{ENV['ICE_HOME']}/slice" # Load Glacier2/Session.ice dynamically: Ice::loadSlice(sliceDir + " --all MySession.ice") # Load Glacier2/Session.ice statically: Ice::loadSlice(sliceDir + " MySession.ice") {zcode} |
In this example, the first invocation of loadSlice
uses the --all
option so that code is generated dynamically for all included files. The second invocation omits --all
, therefore the Ruby interpreter executes the equivalent of the following statement:
{zcode} require "Glacier2/Session.rb" {zcode} |
As a result, before we can call loadSlice
we must first ensure that the interpreter can locate the statically-generated file Glacier2/Session.rb
. We can do this in a number of ways, including:
/opt/IceRuby/ruby
) to the RUBYLIB
environment variable-I
option when starting the interpreter{zcode} $:.unshift("/opt/IceRuby/ruby") {zcode} |
slice2rb
Command-Line OptionsThe Slice-to-Ruby compiler, slice2rb
, offers the following command-line options in addition to the standard options:
--all
--checksum