<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Informational Functions</TITLE>
<LINK HREF="slangfun-6.html" REL=next>
<LINK HREF="slangfun-4.html" REL=previous>
<LINK HREF="slangfun.html#toc5" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-6.html">Next</A>
<A HREF="slangfun-4.html">Previous</A>
<A HREF="slangfun.html#toc5">Contents</A>
<HR>
<H2><A NAME="s5">5. Informational Functions</A></H2>
<P>
<H2><A NAME="_NARGS"></A> <A NAME="ss5.1">5.1 <B>_NARGS</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>The number of parameters passed to a function
<DT><B> Usage </B><DD><P><CODE>Integer_Type _NARGS</CODE>
The value of the <CODE>_NARGS</CODE> variable represents the number of
arguments passed to the function. This variable is local to each
function.
<DT><B> Example </B><DD><P>This example uses the <CODE>_NARGS</CODE> variable to print the list of
values passed to the function:
<BLOCKQUOTE><CODE>
<PRE>
define print_values ()
{
variable arg;
if (_NARGS == 0)
{
message ("Nothing to print");
return;
}
foreach (__pop_args (_NARGS))
{
arg = ();
vmessage ("Argument value is: %S", arg.value);
}
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>__pop_args, __push_args, typeof</CODE>
</DL>
<P>
<P>
<H2><A NAME="__get_defined_symbols"></A> <A NAME="ss5.2">5.2 <B>__get_defined_symbols</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the symbols defined by the preprocessor
<DT><B> Usage </B><DD><P><CODE>Integer_Type __get_defined_symbols ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>__get_defined_symbols</CODE> functions is used to get the list of
all the symbols defined by the <B>S-lang</B> preprocessor. It pushes each
of the symbols on the stack followed by the number of items pushed.
<DT><B> See Also </B><DD><P><CODE>is_defined, _apropos</CODE>
</DL>
<P>
<P>
<H2><A NAME="__is_initialized"></A> <A NAME="ss5.3">5.3 <B>__is_initialized</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Determine whether or not a variable has a value
<DT><B> Usage </B><DD><P><CODE>Integer_Type __is_initialized (Ref_Type r)</CODE>
<DT><B> Description </B><DD><P>This function returns non-zero of the object referenced by <CODE>r</CODE>
is initialized, i.e., whether it has a value. It returns <CODE>0</CODE> if the
referenced object has not been initialized.
<DT><B> Example </B><DD><P>For example, the function:
<BLOCKQUOTE><CODE>
<PRE>
define zero ()
{
variable f;
return __is_initialized (&f);
}
</PRE>
</CODE></BLOCKQUOTE>
will always return zero, but
<BLOCKQUOTE><CODE>
<PRE>
define one ()
{
variable f = 0;
return __is_initialized (&f);
}
</PRE>
</CODE></BLOCKQUOTE>
will return one.
<DT><B> Notes </B><DD><P>It is easy to see why a reference to the variable must be passed to
<CODE>__is_initialized</CODE> and not the variable itself; otherwise, the
value of the variable would be passed and the variable may have no
value if it was not initialized.
<DT><B> See Also </B><DD><P><CODE>__get_reference, __uninitialize, is_defined, typeof, eval</CODE>
</DL>
<P>
<P>
<H2><A NAME="_apropos"></A> <A NAME="ss5.4">5.4 <B>_apropos</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Generate a list of functions and variables
<DT><B> Usage </B><DD><P><CODE>Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags)</CODE>
<DT><B> Description </B><DD><P>The <CODE>_apropos</CODE> function may be used to get a list of all defined
objects in the namespace <CODE>ns</CODE> whose name matches the regular
expression <CODE>s</CODE> and whose type matches those specified by
<CODE>flags</CODE>. It returns an array of strings representing the
matches.
<P>The second parameter <CODE>flags</CODE> is a bit mapped value whose bits
are defined according to the following table
<BLOCKQUOTE><CODE>
<PRE>
1 Intrinsic Function
2 User-defined Function
4 Intrinsic Variable
8 User-defined Variable
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
define apropos (s)
{
variable n, name, a;
a = _apropos ("Global", s, 0xF);
vmessage ("Found %d matches:", length (a));
foreach (a)
{
name = ();
message (name);
}
}
</PRE>
</CODE></BLOCKQUOTE>
prints a list of all matches.
<DT><B> Notes </B><DD><P>If the namespace specifier <CODE>ns</CODE> is the empty string <CODE>""</CODE>,
then the namespace will default to the static namespace of the
current compilation unit.
<DT><B> See Also </B><DD><P><CODE>is_defined, sprintf</CODE>
</DL>
<P>
<P>
<H2><A NAME="_function_name"></A> <A NAME="ss5.5">5.5 <B>_function_name</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Returns the name of the currently executing function
<DT><B> Usage </B><DD><P><CODE>String_Type _function_name ();</CODE>
<DT><B> Description </B><DD><P>This function returns the name of the currently executing function.
If called from top-level, it returns the empty string.
<DT><B> See Also </B><DD><P><CODE>_trace_function, is_defined</CODE>
</DL>
<P>
<P>
<H2><A NAME="_slang_doc_dir"></A> <A NAME="ss5.6">5.6 <B>_slang_doc_dir</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Installed documentation directory
<DT><B> Usage </B><DD><P><CODE>String_Type _slang_doc_dir;</CODE>
<DT><B> Description </B><DD><P>The <CODE>_slang_doc_dir</CODE> variable is a read-only whose value
specifies the installation location of the <B>S-lang</B> documentation.
<DT><B> See Also </B><DD><P><CODE>get_doc_string_from_file</CODE>
</DL>
<P>
<P>
<H2><A NAME="_slang_version"></A> <A NAME="ss5.7">5.7 <B>_slang_version</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>The S-Lang library version number
<DT><B> Usage </B><DD><P><CODE>Integer_Type _slang_version</CODE>
<DT><B> Description </B><DD><P>The <CODE>_slang_version</CODE> variable is read-only and and whose
value represents the number of the <B>S-lang</B> library.
<DT><B> See Also </B><DD><P><CODE>_slang_version_string</CODE>
</DL>
<P>
<P>
<H2><A NAME="_slang_version_string"></A> <A NAME="ss5.8">5.8 <B>_slang_version_string</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>The S-Lang library version number as a string
<DT><B> Usage </B><DD><P><CODE>String_Type _slang_version_string</CODE>
<DT><B> Description </B><DD><P>The <CODE>_slang_version_string</CODE> variable is read-only and whose
value represents the version number of the <B>S-lang</B> library.
<DT><B> See Also </B><DD><P><CODE>_slang_version</CODE>
</DL>
<P>
<P>
<H2><A NAME="get_doc_string_from_file"></A> <A NAME="ss5.9">5.9 <B>get_doc_string_from_file</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Read documentation from a file
<DT><B> Usage </B><DD><P><CODE>String_Type get_doc_string_from_file (String_Type f, String_Type t)</CODE>
<DT><B> Description </B><DD><P><CODE>get_doc_string_from_file</CODE> opens the documentation file <CODE>f</CODE>
and searches it for topic <CODE>t</CODE>. It returns the documentation for
<CODE>t</CODE> upon success, otherwise it returns <CODE>NULL</CODE> upon error.
It will fail if <CODE>f</CODE> could not be opened or does not contain
documentation for the topic.
<DT><B> See Also </B><DD><P><CODE>stat_file</CODE>
<DT><B> See Also </B><DD><P><CODE>_slang_doc_dir</CODE>
</DL>
<P>
<P>
<H2><A NAME="is_defined"></A> <A NAME="ss5.10">5.10 <B>is_defined</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Indicate whether a variable or function defined.
<DT><B> Usage </B><DD><P><CODE>Integer_Type is_defined (String_Type obj)</CODE>
<DT><B> Description </B><DD><P>This function is used to determine whether or not a function or
variable whose name is <CODE>obj</CODE> has been defined. If <CODE>obj</CODE> is not
defined, the function returns 0. Otherwise, it returns a non-zero
value that defpends on the type of object <CODE>obj</CODE> represents.
Specifically, it returns one of the following values:
<BLOCKQUOTE><CODE>
<PRE>
+1 if an intrinsic function
+2 if user defined function
-1 if intrinsic variable
-2 if user defined variable
0 if undefined
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Example </B><DD><P>For example, consider the function:
<BLOCKQUOTE><CODE>
<PRE>
define runhooks (hook)
{
if (2 == is_defined(hook)) eval(hook);
}
</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>typeof, eval, autoload, __get_reference, __is_initialized</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-6.html">Next</A>
<A HREF="slangfun-4.html">Previous</A>
<A HREF="slangfun.html#toc5">Contents</A>
</BODY>
</HTML>
