[rkward-cvs] SF.net SVN: rkward:[3530] trunk/rkward/doc/rkward/ writing_plugins_introduction.docbook

[tfry at users.sourceforge.net]

Revision: 3530
          http://rkward.svn.sourceforge.net/rkward/?rev=3530&view=rev
Author:   tfry
Date:     2011-04-27 11:54:37 +0000 (Wed, 27 Apr 2011)

Log Message:
-----------
Don't talk about substitue(), which will hopefully be gone from our plugins, soon. Also a word of caution about the '<<-' operator

Modified Paths:
--------------
    trunk/rkward/doc/rkward/writing_plugins_introduction.docbook

Modified: trunk/rkward/doc/rkward/writing_plugins_introduction.docbook
===================================================================
--- trunk/rkward/doc/rkward/writing_plugins_introduction.docbook	2011-04-27 07:30:30 UTC (rev 3529)
+++ trunk/rkward/doc/rkward/writing_plugins_introduction.docbook	2011-04-27 11:54:37 UTC (rev 3530)
@@ -44,6 +44,7 @@
 <year>2007</year>
 <year>2008</year>
 <year>2010</year>
+<year>2011</year>
 <holder>Thomas Friedrichsmeier</holder>
 </copyright>
 <!-- Translators: put here the copyright notice of the translation -->
@@ -51,8 +52,8 @@
      and in the FDL itself on how to use it. -->
 <legalnotice>&FDLNotice;</legalnotice>
 
-<date>2010-09-10</date>
-<releaseinfo>0.5.5.00</releaseinfo>
+<date>2011-04-27</date>
+<releaseinfo>0.5.6.00</releaseinfo>
 
 <abstract>
 <para>
@@ -73,7 +74,7 @@
 <title>Introduction</title>
 
 <para>
-Documentation as of &kapp; release 0.5.4.
+Documentation as of &kapp; release 0.5.6.
 </para>
 <para>
 This document describes how to write your own plugins. Note, that at the time of this writing, some of the concepts are not yet set it stone. Therefore, this document should be regarded as an introduction to the current approach, and as a basis for discussion. All sorts of comments are welcome.
@@ -520,23 +521,11 @@
 More often than not you will have to create one or more temporary R objects in the code generated by your plugin. Normally, you do not want those to be placed in the user's workspace, potentially even overwriting user variables. Hence, all plugin generated code is run in a local() environment (see R help page on function local()). This means, all variables you create are temporary and will not be saved permanently.
 </para>
 <para>
-If the user explicitely asks for a variable to be saved, you will need to assign to that object using ".GlobalEnv$objectname <- value".
+If the user explicitely asks for a variable to be saved, you will need to assign to that object using ".GlobalEnv$objectname <- value". In general, do not use the "<<-"-operator. It will not necessarily assign in .GlobalEnv.
 </para>
 <para>
-One important pitfall is using eval() to evaluate substitutes. Here, you need to note that eval will by default use the current environment for evaluation, i.e. the local one. This will work well most of the times, but if you define any temporary variables in the local environment, and you are trying to fetch user variables of the same name using eval, you will get errors. For example:
+One important pitfall is using eval(). Here, you need to note that eval will by default use the current environment for evaluation, i.e. the local one. This will work well most of the times, but but not always. Thus, if you need to use eval(), you will probably want to specify the "envir" parameter: eval(..., envir=globalenv()).
 </para>
-<programlisting>
-# "objects" is the name of both a local temporary variable, and a user selected variable
-objects <- substitute (user.var1, user.var2, objects, user.var4)
-# this will fail: objects[3] is "the object named 'objects'", but this now refers to your
-# temporary variable, instead of the user variable
-third <- eval (objects[3])
-# instead, use this:
-third <- eval (objects[3], envir=globalenv())
-</programlisting>
-<para>
-To solve this, specify the evaluation environment explicitely, as shown above. This will generally be globalenv(), i.e. evaluate as if working in the global environment.
-</para>
 </section>
 
 <section id="policyformatting">


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.