Add documentation and CHANGES for special variables and typemap attributes.

Also add info about special variable expansions in special variable
macros.

3 files changed, 109 insertions, 0 deletions

diff --git a/CHANGES.current b/CHANGES.current
index 0c56946f8..cd5ae106a 100644
--- a/CHANGES.current
+++ b/CHANGES.current
@@ -5,6 +5,41 @@ See the RELEASENOTES file for a summary of changes in each release.
 Version 3.0.7 (in progress)
 ===========================
 
+2015-07-22: wsfulton
+            Support for special variable expansion in typemap attributes. Example usage expansion
+            in the 'out' attribute (C# specific):
+
+              %typemap(ctype, out="$*1_ltype") unsigned int& "$*1_ltype"
+
+            is equivalent to the following as $*1_ltype expands to 'unsigned int':
+
+              %typemap(ctype, out="unsigned int") unsigned int& "unsigned int"
+
+            Special variables can be used within special variable macros too. Example usage expansion:
+
+              %typemap(cstype) unsigned int "uint"
+              %typemap(cstype, out="$typemap(cstype, $*1_ltype)") unsigned int& "$typemap(cstype, $*1_ltype)"
+
+            Special variables are expanded first and hence the above is equivalent to:
+
+              %typemap(cstype, out="$typemap(cstype, unsigned int)") unsigned int& "$typemap(cstype, unsigned int)"
+
+            which then expands to:
+
+              %typemap(cstype, out="uint") unsigned int& "uint"
+
+2015-07-22: lindleyf
+	    Apply patch #439 - support for $typemap() (aka embedded typemaps or special variable
+            macros) in typemap attributes. A simple example where $typemap() is expanded in the
+            'out' attribute (C# specific):
+
+              %typemap(cstype) unsigned int "uint"
+              %typemap(cstype, out="$typemap(cstype, unsigned int)") unsigned int& "$typemap(cstype, unsigned int)"
+
+            is equivalent to:
+
+              %typemap(cstype, out="uint") unsigned int& "uint"
+
 2015-07-18: m7thon
 	    [Python] Docstrings provided via %feature("docstring") are now quoted and added to
             the tp_doc slot when using python builtin classes (-builtin). When no docstring is
diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html
index 793f2ed21..06c858b29 100644
--- a/Doc/Manual/Contents.html
+++ b/Doc/Manual/Contents.html
@@ -441,6 +441,8 @@
 <li><a href="Typemaps.html#Typemaps_special_macro_descriptor">$descriptor(type)</a>
 <li><a href="Typemaps.html#Typemaps_special_macro_typemap">$typemap(method, typepattern)</a>
 </ul>
+<li><a href="Typemaps.html#Typemaps_special_variable_attributes">Special variables and typemap attributes</a>
+<li><a href="Typemaps.html#Typemaps_special_variables_and_macros">Special variables combined with special variable macros</a>
 </ul>
 <li><a href="Typemaps.html#Typemaps_nn25">Common typemap methods</a>
 <ul>
diff --git a/Doc/Manual/Typemaps.html b/Doc/Manual/Typemaps.html
index 5f484531b..ee7495674 100644
--- a/Doc/Manual/Typemaps.html
+++ b/Doc/Manual/Typemaps.html
@@ -48,6 +48,8 @@
 <li><a href="#Typemaps_special_macro_descriptor">$descriptor(type)</a>
 <li><a href="#Typemaps_special_macro_typemap">$typemap(method, typepattern)</a>
 </ul>
+<li><a href="#Typemaps_special_variable_attributes">Special variables and typemap attributes</a>
+<li><a href="#Typemaps_special_variables_and_macros">Special variables combined with special variable macros</a>
 </ul>
 <li><a href="#Typemaps_nn25">Common typemap methods</a>
 <ul>
@@ -2425,6 +2427,76 @@ The result is the following expansion
 </pre>
 </div>
 
+
+<H3><a name="Typemaps_special_variable_attributes"></a>11.4.5 Special variables and typemap attributes</H3>
+
+
+<p>
+As of SWIG-3.0.7 typemap attributes will also expand special variables and special variable macros.
+</p>
+
+<p>
+Example usage showing the expansion in the 'out' attribute (C# specific) as well as the main typemap body:
+</p>
+
+<div class="code">
+<pre>
+%typemap(ctype, out="$*1_ltype") unsigned int&amp; "$*1_ltype"
+</pre>
+</div>
+
+<p>
+is equivalent to the following as <tt>$*1_ltype</tt> expands to <tt>unsigned int</tt>:
+</p>
+
+<div class="code">
+<pre>
+%typemap(ctype, out="unsigned int") unsigned int&amp; "unsigned int"
+</pre>
+</div>
+
+<H3><a name="Typemaps_special_variables_and_macros"></a>11.4.6 Special variables combined with special variable macros</H3>
+
+
+<p>
+Special variables can also be used within special variable macros.
+The special variables are expanded before they are used in the special variable macros.
+</p>
+
+<p>
+Consider the following C# typemaps:
+</p>
+
+<div class="code">
+<pre>
+%typemap(cstype) unsigned int "uint"
+%typemap(cstype, out="$typemap(cstype, $*1_ltype)") unsigned int&amp; "$typemap(cstype, $*1_ltype)"
+</pre>
+</div>
+
+<p>
+Special variables are expanded first and hence the above is equivalent to:
+</p>
+
+<div class="code">
+<pre>
+%typemap(cstype) unsigned int "uint"
+%typemap(cstype, out="$typemap(cstype, unsigned int)") unsigned int&amp; "$typemap(cstype, unsigned int)"
+</pre>
+</div>
+
+<p>
+which then expands to:
+</p>
+
+<div class="code">
+<pre>
+%typemap(cstype) unsigned int "uint"
+%typemap(cstype, out="uint") unsigned int& "uint"
+</pre>
+</div>
+
+
 <H2><a name="Typemaps_nn25"></a>11.5 Common typemap methods</H2>