;;; sec2.01.mhtml: -*- Meta-HTML -*- 

;;;  Copyright (c) 1996 Universal Access Inc.
;;;  Author: Henry Minsky (hqm@ua.com) Sun Sep 15 11:04:57 1996.
<set-var title="Return Values">
<include header.mhtml>

<plain-text>
  <h2>Return Values</h2>

  When you write a normal html file, nearly everything you write into
  the file will be transmitted verbatim to the user's browser to be
  rendered into the final page which the user sees. For example, if you
  write

  <example-table>
  <strong>Hello, world!</strong>
  </example-table>

  The string <verbatim quote><strong>Hello, world!</strong></verbatim quote>
  will be sent to the client browser, which will turn it into something
  like this:

  <strong>Hello, world!</strong>

  This is not the case with <meta-html>. A <meta-html> tag is actually a
  <em>function</em>. This means that the tag computes some
  <em>result</em>.  The result is called the function's <em>return
  value</em>. This return value is then left on the page. From there,
  depending on the <meta-html> program you have written, it is either
  subject to further <meta-html> processing, or it is sent directly to the
  client browser to be displayed.

  All <meta-html> functions have return values. These values can be
  numbers, strings, arrays, or any other <meta-html> data types. If the
  return value is a string, the string can have any number of characters
  Often, the string will have no characters at all; this special string
  is called the <em>empty string</em>.

  The empty string is special for one very important reason. When used
  as the test value of a conditional statement, the empty string means
  "false". Users familiar with the Lisp programming language will 
  immediately recognise a similarity to Lisp's use of the empty list to 
  represent a logical value of "false". We'll see how empty strings are 
  used in mata-html programs later on in the <em>conditional functions</em> 
  section. Right now, let's have a look at a very simple use of
  return values.

  The <funref set-var> function is an example of a function which returns
  the <em>empty string</em>. For example, suppose your <meta-html> file
  contains a function which looks like:

  <example-table>
  <set-var foo="Hello, world!">
  </example-table>

  Since the return value of <code>set-var</code> is the empty string,
  after processing by the <meta-html> server there will be no text
  remnants on the final output; browsers will never know it was there.


  This is not to say that the <code>set-var</code> functionis
  useless. Quite the opposite. In this case, it has stored the string
  "hello world" into the variable <code>foo</code> (in techno-speak, it
  has <em>side effected</em> the variable), which as we're about to see
  has had a great effect on the return value of a related function:
  <code>get-var</code>

  The <funref get-var> function is used to retrieve a value which
  has been stored into a variable. The <em>return value</em> of 
  a call to <code>get-var</code> is whatever was stored in the
  variable. So if we've stored the string "Hello, world!" into
  the variable <code>foo</code> as we did above, then when we 
  call the <code>get-var</code> function:

  <example-table>
  <get-var foo>
  </example-table>

  We end up with the following left on the page:

  Hello, world!

  <pagelist-control-panel>
</plain-text>

<include footer.mhtml>