* Bug 15236 fixed: isglobal() page was inaccurate + wrong examples
[scilab.git] / scilab / modules / core / help / en_US / variables / isglobal.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2012 - 2016 - Scilab Enterprises
5  * Copyright (C) 2017 - Samuel GOUGEON
6  *
7  * This file is hereby licensed under the terms of the GNU GPL v2.0,
8  * pursuant to article 5.3.4 of the CeCILL v.2.1.
9  * This file was originally licensed under the terms of the CeCILL v2.1,
10  * and continues to be available under such terms.
11  * For more information, see the COPYING file which you should have received
12  * along with this program.
13  *
14  -->
15 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
16         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
17         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
18         xml:lang="en" xml:id="isglobal">
19     <refnamediv>
20         <refname>isglobal</refname>
21         <refpurpose>checks if a local variable has a global counterpart</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntax</title>
25         <synopsis>t = isglobal(varname)</synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Arguments</title>
29         <variablelist>
30             <varlistentry>
31                 <term>varname</term>
32                 <listitem>
33                     <para>
34                         text: name of any single local variable. This is not the variable itself
35                         (that provides its content), but its name.
36                     </para>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>t</term>
41                 <listitem>
42                     <para>a boolean</para>
43                 </listitem>
44             </varlistentry>
45         </variablelist>
46     </refsection>
47     <refsection>
48         <title>Description</title>
49         <para>
50             <literal>isglobal("x")</literal> returns <literal>%T</literal> if the variable
51             <varname>x</varname> is defined locally and points to a global counterpart. It returns
52             <literal>%F</literal> otherwise.
53         </para>
54         <important>
55             <itemizedlist>
56                 <listitem>
57                     If <literal>x</literal> is defined in the global space but not in the local
58                     one, <literal>isglobal("x")</literal> will return <literal>%F</literal>
59                     (as <literal>isdef("x")</literal>).
60                 </listitem>
61                 <listitem>
62                     If <varname>varname</varname> is a text not corresponding to the name of any
63                     variable, no error occurs and <literal>%F</literal> is returned.
64                 </listitem>
65             </itemizedlist>
66         </important>
67         <note>
68             The list of all variables defined in the global space (but not necessarily in the local
69             one) can be retrieved with <literal>who("global")</literal>.
70         </note>
71     </refsection>
72     <refsection>
73         <title>Examples</title>
74         <para>
75             <emphasis role="bold">Example #1</emphasis> with a predefined global variable:
76         </para>
77         <programlisting role="example"><![CDATA[
78 mprintf("%s\n", who("global")) // demolist has a global definition...
79 isdef("demolist")       // %F: ... but no local one (not yet)
80 demolist(1)             // => "Undefined variable"
81 isglobal("demolist")    // => %F, since it has no local definition
82
83 global demolist         // We define a local demolist and make it pointing to the existing global one
84 demolist($,:)           // Here is the last row of the existing global content
85 isglobal("demolist")    // => now %T
86  ]]></programlisting>
87     <screen><![CDATA[
88 --> mprintf("%s\n", who("global")) // demolist has a global definition...
89 %helps
90 %modalWarning
91 %toolboxes
92 %toolboxes_dir
93 demolist
94
95 --> isdef("demolist")     // ... but no local one (not yet)
96  ans  =
97   F
98
99 --> demolist(1)           // So: => "Undefined variable"
100 Undefined variable: demolist
101
102 --> isglobal("demolist")  // => %F, since it has no local definition
103  ans  =
104   F
105
106 --> global demolist       // We define a local demolist and make it pointing to the existing global one
107 --> demolist($,:)         // Here is the last row of the existing global content
108  ans  =
109 !Xcos  SCI\modules\xcos\demos\xcos.dem.gateway.sce  !
110
111 --> isglobal("demolist")  // => now %T
112  ans  =
113   T
114  ]]></screen>
115
116     <para>
117         <emphasis role="bold">Example #2</emphasis> with a custom variable:
118     </para>
119     <programlisting role="example"><![CDATA[
120 // In the list hereabove, "abc" does not exist. Let's create it locally and globally:
121 global abc              // initialized with []
122 isdef("abc")            // => %T
123 isglobal("abc")         // => %T
124
125 abc = %pi;              // Writes simultaneously in the local AND global spaces
126 clear abc               // We delete the local definition, but not the global one
127 abc                     // => "undefined variable"
128 isglobal("abc")         // => %F, since there is no longer any local alias
129
130 global abc              // We redefine abc connected to its global counterpart. What is it?
131 abc
132  ]]></programlisting>
133     <screen><![CDATA[
134 --> // In the list hereabove, "abc" does not exist. Let's create it locally and globally:
135 --> global abc              // initialized with []
136 --> isdef("abc")
137  ans  =
138   T
139
140 --> isglobal("abc")
141  ans  =
142   T
143
144 --> abc = %pi;              // Writes simultaneously in the local AND global spaces
145 --> clear abc               // We delete the local definition, but not the global one
146 --> abc                     // => "undefined variable"
147 Undefined variable: abc
148
149 --> isglobal("abc")         // => %F, since without local alias
150  ans  =
151   F
152
153 --> global abc              // We redefine abc connected to its global counterpart. What is it?
154 --> abc
155  abc  =
156    3.1415927
157 ]]></screen>
158     </refsection>
159     <refsection role="see also">
160         <title>See also</title>
161         <simplelist type="inline">
162             <member>
163                 <link linkend="global">global</link>
164             </member>
165             <member>
166                 <link linkend="clearglobal">clearglobal</link>
167             </member>
168             <member>
169                 <link linkend="who">who</link>
170             </member>
171             <member>
172                 <link linkend="isdef">isdef</link>
173             </member>
174         </simplelist>
175     </refsection>
176 </refentry>