New documentation files

Rev: doc/lpc/functions:1.1
Rev: doc/lpc/inherit:1.1
Rev: doc/lpc/lambda:1.1
Rev: doc/lpc/variables:1.1

doc/lpc/functions

+NAME
+	functions - how to write a function
+
+SYNTAX
+	modifier type function_name (argument_specification)
+	{
+	  /* function body */
+	}
+
+DESCRIPTION
+	This defines a function called 'function_name' returning the type
+	'type'. The argument_specification is a comma separated list of
+	arguments. Each argument is specified with a type, whitespace and
+	the name of the argument. The last argument may have ... before
+	the name to indicate that that argument shall contain an array of
+	the rest of the arguments given by the caller. Note that using
+	... automatically makes an the variable an array, so writing
+
+		int foo(int * ... ints);
+
+	means that 'ints' is an array of arrays of integers. Which might not
+	be what you want.
+
+	The modifiers can be zero or more of: static, no_mask, varargs, inline
+	and private. Varargs means that it is ok to call the function with
+	less arguments that would otherwise be needed. Inline means that
+	the function may be inlined in other code. Inline also makes the
+	function no_mask. Static means that the function can not be called
+	from other objects. Private means that the function can not be accessed
+	from programs that inherits this program.
+
+	Some times you need to use a function before it is defined, then you
+	can write a 'forward declaration' of the function. This is done by
+	copying the function definition up until (but not including) the '{'
+	and putting a semicolon after it. The forward declaration should be
+	put before the use of the function of course.
+
+	Function definitions and forward declarations are toplevel constructs,
+	they can not be written inside functions or expressions.
+
+EXAMPLES
+	/* Forward declare foobar as taking an array of int as argument 
+	 *and returning an int
+	 */
+	static int foobar(int *a);
+
+	/* This function takes a format string and any number of integers
+         * as argument and returns a string
+         */
+	string dofobar(string format ,int ... rest)
+	{
+	  return sprintf(format, foobar(rest));
+	}
+
+	/* Define foobar */
+	static int foobar(int *a)
+	{
+	  int e, ret;
+	  ret=1;
+
+	  for(e=0;e<sizeof(a);e++)
+	    ret*=a[e];
+
+	  return ret;
+	}
+
+KEYWORDS
+	lpc
+
+SEE ALSO
+	lambda, return, modifier
\ No newline at end of file

doc/lpc/inherit

+NAME
+	inherit - use definitions from another program
+
+SYNTAX
+	inherit "<program name>";
+	or
+	inherit "<program name>" : local_name;
+
+DESCRIPTION
+	Inherit copies the global identifiers (functions and global variables)
+	from the named program. These functions and variables can then be 
+	used as	if they were defined in this program. All the inherited
+	identifiers that was no declared as no_mask in the inherited program
+	can be also be redefined. The redefinition will not only
+	affect functions following the redefinition, but all functions in
+	this program, including the inherited ones.
+
+	Even if an identifier is redefined you can still access the original
+	though. Prepending the identifier name with :: will return the original
+	identifier, OR an array of all inherited identifiers with that name.
+
+	You can also use the local_name to access a specific identifier, just
+	prepend it like 'local_name::identifier'. This will return the named
+	identifer in the program inherited with the given local_name. If no
+	local_name was given to inherit , the last part of the path in the
+	program name will be used as local_name.
+
+	Inherit calls master()->cast_to_program(<program name>) to get the
+	program to inherit. For this reason there can be no inherits in the
+	master object.
+
+	Inherit is not an expression or statement, it is a toplevel construct
+	and must not be written inside a function body.
+
+EXAMPLES
+	/* This is file hworld.lpc */
+	int hello_world() { write("Hello world.\n"); }
+
+	/* This is the file hello_world.lpc */
+	inherit "hworld.lpc";
+	
+	int main()
+	{
+	  hello_world();
+	  exit(0);
+	}
+
+KEYWORDS
+	lpc
+
+SEE ALSO
+	class

doc/lpc/lambda

+NAME
+	lambda - write nameless functions
+
+SYNTAX
+	lambda(<argument specifications>) { <code> }
+
+DESCRIPTION
+	Lambda let's you write a function as a value to a function call
+	or anywhere where you can enter an expression. Using lambda is
+	basically the same as defining the function before the current
+	function with a temporary name and then use the name instead.
+
+EXAMPLES
+	/* These two lettersort routines are equal */
+	string *lettersort(string *words)
+	{
+	  return sort_array(lettersort, lambda(string a,string b)
+	    {
+	      return a < b;
+	    });
+	}
+
+	int tmp_cmp_fun(string a, string b)
+	{
+	  return a < b;
+	}
+
+	string *lettersort(string *words)
+	{
+	  return sort_array(lettersort, tmp_cmp_fun);
+	}
+
+NOTA BENE
+	function_name() will return something for lambda functions,
+	what it returns is unspecified though.
+
+BUGS
+	confuses the hell out of C indent programs
+
+KEYWORDS
+	lpc
+
+SEE ALSO
+	class, function
+

doc/lpc/variables

+NAME
+	variables - how to declare a variable
+
+SYNTAX
+	modifier type variable_name_list;
+
+DESCRIPTION
+	This is how you declare a global variable. Local variables are defined
+	in the same way, but you may not use any modifiers for local variables.
+	The variable_name_list is a comma separated list of the variables
+	to declare as the type 'type'. Note that '*' binds to the variable
+	names, not the type. This means that:
+
+		int * i,j;
+
+	Declares i as an array of int, but j will be declared as int. To
+	declare both i and j as arrays of int you have to write.
+
+		int * i, * j;
+
+	or
+
+		array(int) i,j;
+
+	Modifiers can be zero or more of: static, no_mask and private.
+	Private means that the variable can not be accessed from programs
+	that inherit this program. Static means that it can not be accessed
+	from other objects with the index operator. No_mask means that it
+	can not be redefined in inheriting programs.
+
+KEYWORDS
+	lpc
+
+SEE ALSO
+	functions