doc/LPC/closure_guide

Closure Guide for LPC

Table of Contents

        1 Indroduction, Overview and Efun-Closures

        2 Lfun-, Inline and Lambda-Closures
        2.1 Lfun-Closures
        2.2 Inline-Closures
        2.3 Lambda-Closures
        2.3.1 Advantages of Lambda-Closures
        2.3.2 Free Variables in Lambda-Closure Constructs
        2.3.3 Special Efun-Closures and Operator-Closures for Lambdas
        2.4 Closures with Strange Names
        2.5 Operator-Closures
        2.6 Variable-Closures

        3 Examples
        3.1 Lfun-Closure
        3.2 Lambda-Closure

1 Introduction, Overview and Efun-Closures

  A closure is a pointer to a function. That means that it is data like an
  int or a string are. It may be assigned to a variable or given to anoth-
  er function as argument.

  To create a closure that points to an efun like write() you can write
  the name of the efun prepended with "hash-tick": #'. #'write is a clo-
  sure that points to the efun write().

  I very often put parentheses around such a closure-notation because
  otherwise my editor gets confused by the hashmark: (#'write). This is
  especially of interest within lambda-closures (see below).

  A closure can be evaluated (which means that the function it points to
  is called) using the efuns funcall() or apply(), which also allow to
  give arguments to the function. Example:

    funcall(#'write,"hello");

  This will result in the same as write("hello"); alone. The string
  "hello" is given as first (and only) argument to the function the clo-
  sure #'write points to.

  The return value of the function the closure points to is returned by
  the efun funcall() or apply(). (Since write() always returns 0 the re-
  turn value of the example above will be 0.)

  What are closures good for? With closures you can make much more univer-
  sally usable functions. A good example is the function filter().
  It gets an array and a closure as arguments. Then it calls the function
  the closure points to for each element of the array:

    filter(({ "bla","foo","bar" }),#'write);

  This will call write("bla"), write("foo") and write("bar") in any order;
  the order is undefined.
  (In the current implementation the given closure is evaluated for all
  elements from the first to the last, so the output will be "blafoobar".)

  Furthermore the efun filter() examines the return value of each
  call of the function the closure points to (the return value of the
  write()s). If the value is true (not 0) then this element is put into
  another array which filter() builds up. If the return value is
  false (== 0) then this element is _not_ put into this array. When all
  calls are done the slowly built up array is returned. Thus,
  filter() filters from the given array all elements that the given
  closure evaluates "true" for and returns an array of those. (The array
  given to filter() itself is _not_ changed!)

  A more sensical example for filterwould be this:

    x = filter(users(),#'query_is_wizard);

  users() is an efun that gets no arguments and returns an array of all
  logged in players (wizards and players). query_is_wizard() is a
  simul_efun that gets an object as first (and only) argument and returns
  true (1) if this object is a wizard and 0 otherwise.

  So, for each element of the array returned by users() the function
  query_is_wizard() is called and only those for which 1 was returned are
  collected into the result and then put into the variable x.

  We now have all logged in wizards stored as array in the variable x.

  Another example: We want to filter out all numbers that are greater than
  42 from the array a of integers:

    x = filter(({ 10,50,30,70 }),#'>,42);

  (x will now be ({ 50,70 }).)

  Here two things are new: first: we create a closure that points to an
  operator; second: we use the possibility to give extra arguments to
  filter().

  Like all efuns the usual operators can be pointed to with a closure by
  prepending #' to them. funcall(#'>,4,5) is exactly the same as (4>5).

  The extra arguments given as third to last argument (as many as you
  like) to filter() are given as second to last argument to the
  function pointed to by the closure each time it is called.

  Thus we now call (({ 10,50,30,70 })[0]>42), (({ 10,50,30,70 })[1]>42) ...
  (which is (10>42), (50>42) ...) and return an array of all elements this
  returns true for and store it into x.

  If you want to create a closure to an efun of which you have the name
  stored in a string you can create such an efun-closure with the efun
  symbol_function():

    symbol_function("write") // this will return #'write

    funcall(symbol_function("write"),"foobar");  // == write("foobar");

  This function does not very often occur in normal code but it is very
  useful for tool-programming (eg the robe uses symbol_function() to allow
  you call any efun you give).

2 Lfun- and Lambda-Closures

  Very often the possibilities closures to efuns offer are not sufficient
  for the purpose one has. In nearly all cases three possibilities exist in
  such cases: use an lfun- or inline-closure, or a lambda-closure.

2.1 Lfun-Closures

    The first possibility is rather easy: like with the efun-closures you
    can create a pointer to a function in the same object you are by using
    the #' to prepend it to a function name of a function declared above.
    Example:

      status foo(int x) {
        return ((x*2) > 42);
      }

      int *bar() {
        return filter(({ 10,50,30,70 }),#'foo);
      }

    Thus, #'foo is used like there was an efun of this name and doing the
    job that is done in foo().

2.2 Inline Closure

    Inline closures are a variant of lfun closures, the difference being
    that the function text is written right where the closure is used,
    enclosed in a pair of '(:' and ':)'. The compiler will then take care
    of creating a proper lfun and lfun-closure. The arguments passed to
    such an inline closure are accessible by position: $1 would be the
    first argument, $2 the second, and so on. With this, the
    above example would read:

      int * bar() {
        return filter(({ 10,50,30,70 }), (: ($1 * 2) > 42 :));
      }

    or alternatively:

      int * bar() {
        return filter(({ 10,50,30,70 }), (: return ($1 * 2) > 42; :));
      }

    The difference between the two versions is that in the first form the text
    of the inline closure must be an expression only, whereas in the second
    form any legal statement is allowed. The compiler distinguishes the two
    forms by the last character before the ':)': if it's a ';' or '}', the
    compiler treats the closure as statement(s), otherwise as expression.

    Inline closures may also nested, so that the following (not very useful)
    example is legal, too:

      return filter( ({ 10, 50, 30, 70 })
                         , (: string *s;
                              s = map(users(), (: $1->query_name() :));
                              return s[random(sizeof(s))] + ($1 * 2);
                            :));

    The notation of inline closures is modelled after the MudOS functionals,
    but there are a few important differences in behaviour.


2.3 Lambda-Closures

    Lambda-Closures take the idea of 'define it where you use it' one step
    further. On first glance they may look like inline closures with an uglier
    notation, but they offer a few increased possibilities. But first things
    first.

    The efun lambda() creates a function temporarily and returns a closure
    pointing to this function. lambda() therefor gets two arrays as
    arguments, the first is a list of all arguments the function shall expect
    and the second array is the code of the function (in a more or less
    complicated form; at least not in C- or LPC-syntax). The closure #'foo
    from the example above could be notated as lambda-closure:

      lambda(({ 'x }),({ (#'>),
                         ({ (#'*),'x,2 }),
                         42
                      }))

    Now, the first argument is ({ 'x }), an array of all arguments the
    function shall expect: 1 argument (called 'x) is expected. Notice the
    strange notation for this argument with one single leading tick. Like
    The hash-tick to denote closures the leading tick is used to denote
    things called "symbols". They do not differ much from strings and if
    you do not want to have a deeper look into closures you can leave it
    this way.

    The second argument is an array. The first element of such an array
    must be an efun- or an lfun-closure, the further elements are the
    arguments for the function this closure points to. If such an argu-
    ment is an array, it is treated alike; the first element must be a
    closure and the remaining elements are arguments (which of course
    also might be arrays ...).

    This leads to a problem: sometimes you want to give an array as an
    argument to a function. But arrays in an array given to lambda() are
    interpreted as code-arrays. To allow you to give an array as an argu-
    ment within an array given to lambda(), you can use the function
    quote() to make your array to a quoted array (a quoted array is for
    an array what a symbol is for a string):

      lambda(0,({ (#'sizeof),
                  quote(({ 10,50,30,70 }))
               }))

    For array constants, you can also use a single quote to the same
    effect:

      lambda(0,({ (#'sizeof),
                  '({ 10,50,30,70 })
               }))

    This lambda-closure points to a function that will return 4 (it will
    call sizeof() for the array ({ 10,50,30,70 })). Another thing: if
    we want to create a function that expects no arguments, we can give
    an empty array as first argument to lambda() but we can give 0 as
    well to attain this. This is just an abbreviation.

    Lambda-closure constructs can become quite large and hard to read. The
    larger they become the harder the code is to read and you should avoid
    extreme cases. Very often the possibility to use an lfun or an inline
    instead of a large lambda shortens the code dramatically. Example:

      status foo(object o) {
        return environment(o)->query_level()>WL_APPRENTICE;
      }

      x=filter(a,#'foo);

    does the same as

      x=filter(a,lambda(({ 'o }),
                              ({ (#'>),
                                 ({ (#'call_other),
                                    ({ (#'environment),'o }),
                                    "query_level"
                                 }),
                                 WL_APPRENTICE
                              })));

    (Note that the syntax with the arrow "->" for call_other()s cannot be
    used, #'-> does not exist. You have to use #'call_other for this and
    give the name of the lfun to be called as a string.)

    This example also demonstrates the two disadvantages of lambda closures.
    First, they are very difficult to read, even for a simple example like
    this. Second, the lambda closure is re-created everytime the
    filter() is executed, even though the created code is always the
    same.

    'Why use lambdas at all then?' you may ask now. Well, read on.


2.3.1 Advantages of Lambda Closures

    The advantages of lambdas stem from the fact that they are created
    at runtime from normal arrays.

    This means that the behaviour of a lambda can be made dependant on data
    available only at runtime. For example:

      closure c;
      c = lambda(0, ({#'-, ({ #'time }), time() }) );

    Whenever you now call this closure ('funcall(c)') it will return the
    elapsed time since the closure was created.

    The second advantage of lambdas is that the arrays from which they
    are compiled can be constructed at runtime. Imagine a customizable prompt
    which can be configured to display the time, the environment, or both:

      mixed code;

      code = ({ "> " });
      if (user_wants_time)
        code = ({ #'+, ({ #'ctime }), code });
      if (user_wants_environment)
        code = ({ #'+, ({#'to_string, ({#'environment, ({#'this_player }) }) })
                     , code });
      set_prompt(lambda(0, code));


2.3.2 Free Variables in Lambda-Closure Constructs

      You can use local variables in lambda constructs without declaring
      them, just use them. The only limitation is that you at first have
      to assign something to them. Give them as symbols like you do with
      the arguments. This feature does not make much sense without the use
      of complexer flow controlling features described below.

      The closure #'= is used to assign a value to something (like the
      LPC-operator = is).

2.3.3 Special Efun-Closures and Operator-Closures for Lambdas

      There are some special closures that are supposed to be used only
      within a lambda construct. With them you can create nearly all code
      you can with regular LPC-code like loops and conditions.

      #'? acts like the "if" statement in LPC. The first argument is the
          condition, the second is the code to be executed if the condition
          returns true. The following arguments can also be such couples of
          code-arrays that state a condition and a possible result. If at
          the end there is a single argument, it is used as the else-case
          if no condition returned true.

          lambda(({ 'x }),({ (#'?),             // if
                             ({ (#'>),'x,5 }),  //    (x > 5)
                             ({ (#'*),'x,2 }),  //       result is x * 2;
                             ({ (#'<),'x,-5 }), // else if (x < -5)
                             ({ (#'/),'x,2 }),  //    result is x/2;
                             'x                 // else result is x;
                          }))

      #'?! is like the #'? but it negates all conditions after evaluation
           and thus is like an ifnot in LPC (if there were one).

      #', (which looks a bit strange) is the equivalent of the comma-operator
          in LPC and says: evaluate all arguments and return the value of
          the last. It is used to do several things inside a lambda-closure.

          lambda(({ 'x }),({ (#',),  // two commas necessary!
                                     // one for the closure and one as
                                     // delimiter in the array
                             ({ (#'write),"hello world!" }),
                             ({ (#'say),"Foobar." })
                          }))

      #'while acts like the LPC statement "while" and repeats executing one
              code-array while another returns true.
              #'while expects two or more arguments: the condition as first
              argument, then the result the whole expression shall have after
              the condition turns false (this is in many cases of no interest)
              and as third to last argument the body of the loop.

              lambda(0,({ (#',),            // several things to do ...
                          ({ (#'=),'i,0 }),    // i is a local variable of this
                                               // lambda-closure and is
                                               // initialized with 0 now.
                          ({ (#'while),
                             ({ (#'<),'i,10 }),   // condition: i < 10
                             42,                  // result is not interesting,
                                                  // but we must give one
                             ({ (#'write),'i }),  // give out i
                             ({ (#'+=),'i,1 })    // increase i
                          })
                       }))

               The function this closure points to will give out the
               numbers from 0 to 9 and then return 42.

      #'do is like the do-while statement in LPC and is very much like the
           #'while. The difference is that #'while tests the condition al-
           ready before the body is evaluated for the first time, this means
           that the body might not be evaluated even once. #'do evaluates
           the body first and then the condition, thus the body is evaluated
           at least one time.
           Furthermore, the arguments for #'do are changed in order. #'do
           expects as first to last but two the body of the loop, then the
           condition (as last-but-one'th argument) and the result value as
           last argument. So #'do must have at least two arguments: the
           condition and the result.

           lambda(0,({ (#',),          // several things to do ...
                       ({ (#'=),'i,0 }),  // i is a local variable of this
                                          // lambda-closure and is initialized
                                          // with 0 now.
                       ({ (#'do),
                          ({ (#'write),'i }),  // give out i
                          ({ (#'+=),'i,1 })    // increase i
                          ({ (#'<),'i,10 }),   // condition: i < 10
                          42                   // result is not interesting
                       })
                    }))

      NOTE: There is no #'for in LPC, you should use #'while for this.

      #'foreach is like the foreach() statement in LPC. It evaluates one or
           more bodies repeatedly for every value in a giving string, array
           or mapping. The result of the closure is 0.

           #'foreach expects two or more arguments:
            - a single variable symbol, or an array with several variable
              symbols
            - the value to iterate over
            - zero or more bodes to evaluate in each iteration.

           The single values retrieved from the given value are assigned
           one after another to the variable(s), then the bodies are executed
           for each assignment.

           lambda(0, ({#'foreach, 'o, ({#'users})
                                    , ({#'call_other, 'o, "die" })
                     }));

           lambda(0, ({#'foreach, ({'k, 'v}), ({ ...mapping...})
                                    , ({#'printf, "%O:%O\n", 'k, 'v })
                     }));

      #'return gets one argument and acts like the "return" statement in LPC
               in the function that is created by lambda(). It aborts the
               execution of this function and returns the argument.

               lambda(0,({ (#'while),// loop
                           1,        // condition is 1 ==> endles loop
                           42,       // return value (which will never be used)
                           ({ (#'write),"grin" })
                           ({ (#'?!),               // ifnot
                              ({ (#'random),10 }),  //       (random(10))
                              ({ (#'return),100 })  //   return 100;
                           })
                        }))

                This function will enter an endles loop that will in each
                turn give out "grin" and if random(10) returns 0 (which will
                of course happen very soon) it will leave the function with
                "return 100". The value 42 that is given as result of the
                loop would be returned if the condition would evaluate to 0
                which cannot be. (1 is never 0 ;-)

      #'break is used like the "break" statement in LPC and aborts the exe-
              cution of loops and switches.
              It must not appear outside a loop or switch of the lambda
              closure itself, it cannot abort the execution of the function
              the closure points to!

                lambda(0,({ (#'?),
                            ({ (#'random),2 }),
                            ({ (#'break) }), // this will cause the error
                                             // "Unimplemented operator break
                                             // for lambda()"
                            "random was false!"
                         }));

              You can use ({ #'return,0 }) instead of ({ #'break }) in such
              cases.

      #'continue is used like the "continue" statement in LPC and jumps to
                 the end of the current loop and continues with the loop
                 condition.

      #'default may be used within a #'switch-construct but be careful!
                To call symbol_function("default") (which is done usually
                by tools that allow closure-creation) might crash the
                driver! So please do only use it within your LPC-files.
                (NOTE: This driver bug is fixed somewhere below 3.2.1@131.)

      #'.. may be used within a #'switch-construct but is not implemented
           yet (3.2.1@131). But #'[..] works well instead of it.

      #'switch is used to create closures which behave very much like the
               switch-construct in LPC. To understand the following you
               should already know the syntax and possibilities of the
               latter one (which is mightier than the C-version of switch).

               I will confront some LPC versions and the corresponding clo-
               sure versions below.

               LPC:                  Closure:
                 switch (x) {          lambda(0,({ (#'switch), x,
                 case 5:                           ({ 5 }),
                   return "five";                  ({ (#'return),"five" }),
                                                   (#',),
                 case 6..9:                        ({ 6, (#'[..]), 9 }),
                   return "six to nine";           ({ (#'return),
                                                      "six to nine" }),
                                                   (#',),
                 case 1:                           ({ 1 }),
                   write("one");                   ({ (#'write),"one" }),
                   // fall through                 (#',),
                 case 2:                           ({ 2,
                 case 10:                             10 }),
                   return "two or ten";            ({ (#'return),
                                                      "two or ten" }),
                                                   (#',),
                 case 3..4:                        ({ 3, (#'[..]), 4 }),
                   write("three to four");         ({ (#'write),
                                                      "three to four" }),
                   break;  // leave switch         (#'break),
                 default:                          ({ (#'default) }),
                   write("something else");        ({ (#'write),
                                                      "something else" }),
                   break;                          (#'break)
                 }                              }))

      #'&& evaluates the arguments from the first on and stops if one evalu-
           ates to 0 and returns 0. If none evaluates to 0 it returns the
           result of the last argument.

      #'|| evaluates the arguments from the first on and stops if one evalu-
           ates to true (not 0) and returns it. If all evaluate to 0 it
           returns 0.

      #'catch executes the closure given as argument, but catches any
           runtime error (see catch(E)). Optionally the symbols 'nolog,
           'publish and 'reserve may be given as additional arguments to
           modify the behaviour of the catch.

      #'sscanf acts similar to how a funcall would, but passes the third
           and following arguments as lvalues, that is, values which can
           be assigned to.

      #'= and the #'<op>= variants are also special because the first
           argument has to be an lvalue.

2.4 Closures with Strange Names

    #'negate is the unary minus that returns -x for the argument x.

             map(({ 1,2,3 }),#'negate)

             This returns ({ -1,-2,-3 }).

    #'[ is used for the things that in LPC are done with
             the []-operator (it indexes an array or a mapping).

             lambda(0,({ #'[,quote(({ 10,50,30,70 })),2 })) ==> 30
             lambda(0,({ #'[,([ "x":10;50, "y":30;70 ]),"x",1 })) ==> 50

    #'[< is the same as #'[ but counts the elements from the
               end (like indexing with [] and the "<").

    #'[..] returns a subarray of the argument from the one
             given index to the other given index, both counted from the
             beginning of the array.

    #'[..<]
    #'[<..]
    #'[<..<] same as above, but the indexes are counted from the end,

                lambda(0,({ #'[..<],
                            quote(({ 0,1,2,3,4,5,6,7 })),2,3
                         }))

                This will return ({ 2,3,4,5 }).
    #'[..
    #'[<.. same as above, but only the first index is given, the
               subarray will go till the end of the original (like with
               [x..]).

    #'({ is used to create arrays (as with ({ }) in LPC). All arguments
             become the elements of the array.

             lambda(0,({ #'({,
                         ({ (#'random),10 }),
                         ({ (#'random),50 }),
                         ({ (#'random),30 }),
                         ({ (#'random),70 })
                      }))

             This returns ({ random(10),random(50),random(30),random(70) }).

    #'([ is used to create mappings out of single entries (with seve-
               ral values) like the ([ ]) in LPC. Very unusual is the fact
               that this closure gets arrays as argument that are not eval-
               uated, although they are not quoted.

               lambda(0,({ #'([,
                           ({ "x",1,2,3 }),
                           ({ "y",4,5,6 })
                        }));

               This returns ([ "x": 1;2;3,
                               "y": 4;5;6 ]).

               However, the elements of the arrays are evaluated as lambda
               expressions, so if you want to create a mapping from values
               evaluated at call time, write them as lambda closures:

               lambda(0, ({ #'([, ({ 1, ({ #'ctime }) }) }) )

               will return ([ 1: <result of ctime() at call time ]).

               Arrays can be put into the mapping by quoting:

               lambda(0, ({ #'([, ({ 1, '({ 2 }) }) }) )

               will return ([ 1: ({ 2 }) ])


    #'[,] is nearly the same as #'[. The only difference
                     shows up if you want to index a mapping with a width
                     greater than 1 (with more than just one value per
                     key) directly with funcall(). Example:
                     funcall(#'[,([ 0:1;2, 3:4;5 ]),0,1)
                     This will not work. Use #'[,] and it will
                     work. If you want to use it in a lambda closure you
                     do not have to use #'[,] and #'[ will
                     do fine. On the other hand, #'[,] cannot
                     work with arrays, so in nearly all cases use #'[
                     and just in the described special case, use
                     #'[,].
                     This is a strange thing and I deem it a bug, so it
                     might change in the future.

2.5 Operator-Closures

    Most of the closures that are used for things which are done by opera-
    tors are in fact not operator-closures but efun-closures. But there are
    a few which do not have the state of efun-closures but are called
    "operator-closures". #'return is an example, a complete list of them is
    given below.

    These closures cannot be called directly using funcall() or apply() (or
    other efuns like filter()), but must appear only in lambda-con-
    structs.

      funcall(#'return,4);  // does not work! This will raise an
                            // Uncallable-closure error.
      funcall(lambda(0,     // this is a correct example
                     ({ (#'return),4 })
                    ));

    All operator-closures:
    #'&&
    #'||
    #',
    #'?
    #'?!
    #'=
    #'<op>=
    #'++
    #'--
    #'break
    #'catch
    #'continue
    #'default
    #'do
    #'foreach
    #'return
    #'sscanf
    #'switch
    #'while
    #'({
    #'([

    #'.. is very likely to be an operator closure too, but since it is
    not implemented yet, I cannot say for sure.

2.6 Variable-Closures

    All object-global variables might be "closured" by prepending a #' to
    them to allow access and/or manipulation of them. So if your object has
    a global variable x you can use #'x within a closure.

    Normally you will treat those expressions like lfun-closures: put them
    into an array to get the value:

    object.c:
              int x;
              int foo() {
                return lambda(0,({ (#'write),({ (#'x) }) }));
              }

    Anybody who now calls object->foo() will get a closure which will, when
    evaluated, write the actual value of object's global variable x.

    Variable closures do not accept arguments.

3 Examples

  In this section I will give and explain some examples coming out of
  praxis. If the explanation seems to be in some cases too detailed this
  can be explained by the trial to allow the reader to read the examples
  section first ;-)

3.1 Lfun-Closure

    An item with a complex long-description like a watch that shall always
    show the actual time will usually base upon the complex/item-class and
    give an lfun-closure as argument to the set_long()-method.

    watch.c:
             inherit "complex/item";

             string my_long() {
               return ("The watch is small and has a strange otherworldly"
                       " aura about it.\n"
                       "The current time is: "+ctime()+".\n");
             }

             void create() {
               set_short("a little watch");
               set_id(({ "watch","little watch" }));
               set_long(#'my_long);  // the lfun-closure to the lfun my_long()
             }

3.2 Lambda-Closure

    The example from 3.1 can also be written using a lambda-closure.

    watch.c:
             inherit "complex/item";

             void create() {
               set_short("a little watch");
               set_id(({ "watch","little watch" }));
               set_long(lambda(0,({ (#'+),
                                    "The watch is small and has a strange"
                                    " otherworldly aura about it.\n"
                                    "The current time is: ",
                                    ({ (#'+),
                                       ({ (#'ctime) }),
                                       ".\n"
                                    })
                                 })));
             }