1 files changed, 94 insertions, 0 deletions
diff --git a/Examples/ruby/variables/index.html b/Examples/ruby/variables/index.html
new file mode 100644
index 0000000..d83a87c
--- /dev/null
+++ b/Examples/ruby/variables/index.html
@@ -0,0 +1,94 @@
+<html>
+<head>
+<title>SWIG:Examples:ruby:variables</title>
+</head>
+
+<body bgcolor="#ffffff">
+
+<tt>SWIG/Examples/ruby/variables/</tt>
+<hr>
+
+<H2>Wrapping C Global Variables</H2>
+
+<p>
+When a C global variable appears in an interface file, SWIG tries to
+wrap it using a technique known as "variable linking."  The idea is
+pretty simple---we try to create a Ruby variable (actually module method) that
+magically retrieves or updates the value of the underlying C variable when it is
+accessed.  Click <a href="example.i">here</a> to see a SWIG interface with some variable
+declarations in it.
+
+<h2>Manipulating Variables from Ruby</h2>
+
+Before going any further, it is important to understand some important
+differences between C and Ruby variables.  In C, a variable is
+simply a name that refers to a specific location in memory.  For
+example, when you declare a global variable '<tt>double a</tt>' you
+know that somewhere in memory, 8 bytes have been set aside to hold a
+<tt>double</tt> and that <tt>a</tt> is bound to this location for the
+life of the program.  In Ruby, variable creation is nothing more
+than a naming operation.  For example, when you say '<tt>a = 3</tt>',
+'a' becomes a name that refers to some object '3'.  Later on, if you say
+'<tt>a = 7.5</tt>, the name 'a' is bound to an entirely different object
+containing the value '7.5' (the contents of the original object are not
+changed).  The end result of this is that a variable in Ruby can refer
+to a virtually unlimited number of different objects (memory locations)
+over the lifetime of a program.
+
+<p>
+Because of Ruby's somewhat unusual variable assignment semantics, it is not
+possible to directly link a C global variable into an equivalent Ruby variable.
+Instead, all C global variables are accessed as attributes of the module.
+For example, if you had a global variable
+
+<blockquote>
+<pre>
+double foo;
+</pre>
+</blockquote>
+
+it will be accessed in the Ruby module as <tt>Example.foo</tt>. Click
+<a href="runme.rb">here</a> to see a script that updates and prints
+out the values of the variables using this technique.
+
+<h2>Key points</h2>
+
+<ul>
+<li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character
+string.   However, whenever the value of such a variable is set from Ruby, the old
+value is destroyed using <tt>free()</tt>.
+<li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers.
+<li>String array variables such as '<tt>char name[256]</tt>' are managed as Ruby strings, but
+when setting the value, the result is truncated to the maximum length of the array.  Furthermore, the string is assumed to be null-terminated.
+<li>When structures and classes are used as global variables, they are mapped into pointers.
+Getting the "value" returns a pointer to the global variable.  Setting the value of a structure results in a memory copy from a pointer to the global.
+</ul>
+
+<h2>Creating read-only variables</h2>
+
+The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to
+specify a collection of read-only variables.  For example:
+
+<blockquote>
+<pre>
+%immutable;
+int    status;
+double blah;
+...
+%mutable;
+</pre>
+</blockquote>
+
+The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled
+using the <tt>%mutable</tt> directive.
+
+<h2>Comments</h2>
+<ul>
+<li>Management of global variables is one of the most problematic aspects 
+of C/C++ wrapping because the scripting interface and resulting memory management
+is much trickier than simply creating a wrapper function.
+</ul>
+
+</body>
+</html>
+<hr>