<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Miscellaneous Functions</TITLE>
<LINK HREF="slangfun-18.html" REL=previous>
<LINK HREF="slangfun.html#toc19" REL=contents>
</HEAD>
<BODY>
Next
<A HREF="slangfun-18.html">Previous</A>
<A HREF="slangfun.html#toc19">Contents</A>
<HR>
<H2><A NAME="s19">19. Miscellaneous Functions</A></H2>

<P>
<H2><A NAME="__get_reference"></A> <A NAME="ss19.1">19.1 <B>__get_reference</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get a reference to a global object
<DT><B> Usage </B><DD><P><CODE>Ref_Type __get_reference (String_Type nm)</CODE>
<DT><B> Description </B><DD><P>This function returns a reference to a global variable or function
whose name is specified by <CODE>nm</CODE>.  If no such object exists, it
returns <CODE>NULL</CODE>, otherwise it returns a reference.
<DT><B> Example </B><DD><P>For example, consider the function:
<BLOCKQUOTE><CODE>
<PRE>
    define runhooks (hook)
    {
       variable f;
       f = __get_reference (hook);
       if (f != NULL)
         @f ();
    }
</PRE>
</CODE></BLOCKQUOTE>

This function could be called from another <B>S-lang</B> function to
allow customization of that function, e.g., if the function
represents a mode, the hook could be called to setup keybindings
for the mode.
<DT><B> See Also </B><DD><P><CODE>is_defined, typeof, eval, autoload, __is_initialized, __uninitialize</CODE>
</DL>
<P>
<P>
<H2><A NAME="__uninitialize"></A> <A NAME="ss19.2">19.2 <B>__uninitialize</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Uninitialize a variable
<DT><B> Usage </B><DD><P><CODE>__uninitialize (Ref_Type x)</CODE>
<DT><B> Description </B><DD><P>The <CODE>__uninitialize</CODE> function may be used to uninitialize the
variable referenced by the parameter <CODE>x</CODE>.
<DT><B> Example </B><DD><P>The following two lines are equivalent:
<BLOCKQUOTE><CODE>
<PRE>
     () = __tmp(z);
     __uninitialize (&amp;z);
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>__tmp, __is_initialized</CODE>
</DL>
<P>
<P>
<H2><A NAME="_auto_declare"></A> <A NAME="ss19.3">19.3 <B>_auto_declare</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Set automatic variable declaration mode
<DT><B> Usage </B><DD><P><CODE>Integer_Type _auto_declare</CODE>
<DT><B> Description </B><DD><P>The <CODE>_auto_declare</CODE> may be used to have all undefined variables
implicitely declared as <CODE>static</CODE>.  If set to zero, any variable
must be declared witha <CODE>variable</CODE> declaration before it can be
used.  If set to one, then any undeclared variabled will be declared
as a <CODE>static</CODE> global variable.
<P>The <CODE>_auto_declare</CODE> variable is is local to each compilation unit and
setting its value in one unit has no effect upon its value in other
units.   The value of this variable has no effect upon the variables
in a function.
<DT><B> Example </B><DD><P>The following code will not compile if <CODE>X</CODE> not been
declared:
<BLOCKQUOTE><CODE>
<PRE>
    X = 1;
</PRE>
</CODE></BLOCKQUOTE>

However, 
<BLOCKQUOTE><CODE>
<PRE>
    _auto_declare = 1;   % declare variables as static.
    X = 1;
</PRE>
</CODE></BLOCKQUOTE>

is equivalent to 
<BLOCKQUOTE><CODE>
<PRE>
    static variable X = 1;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>This variable should be used sparingly and is intended primarily for
interactive applications where one types <B>S-lang</B> commands at a prompt.
</DL>
<P>
<P>
<H2><A NAME="getenv"></A> <A NAME="ss19.4">19.4 <B>getenv</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the value of an environment variable
<DT><B> Usage </B><DD><P><CODE>String_Type getenv(String_Type var)</CODE>
<DT><B> Description </B><DD><P>The <CODE>getenv</CODE> function returns a string that represents the
value of an environment variable <CODE>var</CODE>.  It will return
<CODE>NULL</CODE> if there is no environment variable whose name is given
by <CODE>var</CODE>.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
    if (NULL != getenv ("USE_COLOR"))
      {
        set_color ("normal", "white", "blue");
        set_color ("status", "black", "gray");
        USE_ANSI_COLORS = 1;
      }
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>putenv, strlen, is_defined</CODE>
</DL>
<P>
<P>
<H2><A NAME="implements"></A> <A NAME="ss19.5">19.5 <B>implements</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Name a private namespace
<DT><B> Usage </B><DD><P><CODE>implements (String_Type name);</CODE>
<DT><B> Description </B><DD><P>The <CODE>implements</CODE> function may be used to name the private
namespace associated with the current compilation unit.  Doing so
will enable access to the members of the namespace from outside the
unit.  The name of the global namespace is <CODE>Global</CODE>.
<DT><B> Example </B><DD><P>Suppose that some file <CODE>t.sl</CODE> contains:
<BLOCKQUOTE><CODE>
<PRE>
     implements ("Ts_Private");
     static define message (x)
     {
        Global-&gt;vmessage ("Ts_Private message: %s", x);
     }
     message ("hello");
</PRE>
</CODE></BLOCKQUOTE>

will produce <CODE>"Ts_Private message: hello"</CODE>.  This <CODE>message</CODE>
function may be accessed from outside via:
<BLOCKQUOTE><CODE>
<PRE>
    Ts_Private-&gt;message ("hi");
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>Since <CODE>message</CODE> is an intrinsic function, it is global and may
not be redefined in the global namespace.
</DL>
<P>
<P>
<H2><A NAME="putenv"></A> <A NAME="ss19.6">19.6 <B>putenv</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Add or change an environment variable
<DT><B> Usage </B><DD><P><CODE>putenv (String_Type s)</CODE>
<DT><B> Description </B><DD><P>This functions adds string <CODE>s</CODE> to the environment.  Typically,
<CODE>s</CODE> should of the form <CODE>"name=value"</CODE>.  The function
signals a <B>S-lang</B> error upon failure.
<DT><B> Notes </B><DD><P>This function is not available on all systems.
<DT><B> See Also </B><DD><P><CODE>getenv, sprintf</CODE>
</DL>
<P>
<P>
<P>
<HR>
Next
<A HREF="slangfun-18.html">Previous</A>
<A HREF="slangfun.html#toc19">Contents</A>
</BODY>
</HTML>
