Updates /doc/hook/ aus Driversourcen.
Change-Id: I039ae8b3cfcaadb859e8e10037b9fa9f6d120fba
diff --git a/doc/hook/auto_include_block b/doc/hook/auto_include_block
new file mode 100644
index 0000000..822aa58
--- /dev/null
+++ b/doc/hook/auto_include_block
@@ -0,0 +1,37 @@
+SYNOPSIS
+ #include <sys/driver_hooks.h>
+
+ set_driver_hook(H_AUTO_INCLUDE_BLOCK, value)
+
+ <value> being:
+
+ string <text>
+ string <closure>(object current_object, string current_file
+ , int sys_include)
+
+DESCRIPTION
+ Optional hook specifying a string to be included before the
+ code of a compile_string() call for an LPC block.
+ Hook setting can be a string or a closure.
+
+ If the setting is a string, it will be automatically included
+ in the compilation for every compile_string() call.
+
+ If the setting is a closure, it is called for the original
+ string and for every file opened by the compiler.
+ <current_object> is the object the string is compiled for.
+ <base_file> will be zero for the string itself and the name
+ of a file included directly or indirectly by the string.
+ For an included file, <sys_include> will be TRUE if it is
+ a <>-type include.
+
+ If the result from the call is a string, it will be included
+ before the actual text.
+
+ In both cases, the string will be included as-is; in
+ particular no terminating '\n' will be added.
+
+HISTORY
+
+SEE ALSO
+ hooks(C), include_dirs(H), auto_include_expression(H), compile_string(E)
diff --git a/doc/hook/auto_include_expression b/doc/hook/auto_include_expression
new file mode 100644
index 0000000..65715ca
--- /dev/null
+++ b/doc/hook/auto_include_expression
@@ -0,0 +1,37 @@
+SYNOPSIS
+ #include <sys/driver_hooks.h>
+
+ set_driver_hook(H_AUTO_INCLUDE_EXPRESSION, value)
+
+ <value> being:
+
+ string <text>
+ string <closure>(object current_object, string current_file
+ , int sys_include)
+
+DESCRIPTION
+ Optional hook specifying a string to be included before the
+ code of a compile_string() call for an LPC expression.
+ Hook setting can be a string or a closure.
+
+ If the setting is a string, it will be automatically included
+ in the compilation for every compile_string() call.
+
+ If the setting is a closure, it is called for the original
+ string and for every file opened by the compiler.
+ <current_object> is the object the string is compiled for.
+ <base_file> will be zero for the string itself and the name
+ of a file included directly or indirectly by the string.
+ For an included file, <sys_include> will be TRUE if it is
+ a <>-type include.
+
+ If the result from the call is a string, it will be included
+ before the actual text.
+
+ In both cases, the string will be included as-is; in
+ particular no terminating '\n' will be added.
+
+HISTORY
+
+SEE ALSO
+ hooks(C), include_dirs(H), auto_include_block(H), compile_string(E)
diff --git a/doc/hook/create_clone b/doc/hook/create_clone
index e8dac03..f111e19 100644
--- a/doc/hook/create_clone
+++ b/doc/hook/create_clone
@@ -11,14 +11,17 @@
DESCRIPTION
Optional hooks to initialize a cloned object after creation.
- Hook setting can be unbound lambda closures, or the name of
- the function (static or public) to call in the object.
+ Hook setting can any closure, or the name of the function
+ (static or public) to call in the object.
- If the hook is a closure expecting arguments, it is bound to the
- current object and called with the created object as the first
- argument and any further arguments from the clone_object() call.
- If the hook is a closure without arguments, it is bound to
- the object to be initalized and called.
+ If the hook is an unbound lambda closure expecting arguments,
+ it is bound to the current object and called with the created
+ object as the first argument and any further arguments from
+ the clone_object() call. If the hook is an unbound lambda
+ closure without arguments, it is bound to the object to be
+ initalized and called. If the hook is any other type of closure,
+ it is called with the created object as the first argument and
+ any further arguments from the clone_object() call.
If the result of the closure call is a non-zero number, it is used
as the interval to wait before the first reset(), else the default
diff --git a/doc/hook/create_lwobject b/doc/hook/create_lwobject
index 8872e73..0a1e023 100644
--- a/doc/hook/create_lwobject
+++ b/doc/hook/create_lwobject
@@ -11,14 +11,17 @@
DESCRIPTION
Optional hooks to initialize a lightweight object after creation.
- Hook setting can be unbound lambda closures, or the name of the
- function (static or public) to call in the object.
+ Hook setting can be any closure, or the name of the function
+ (static or public) to call in the object.
- If the hook is a closure expecting arguments, it is bound to the
- current object and called with the created object as the first
- argument and any further arguments from the new_lwobject() call.
- If the hook is a closure without arguments, it is bound to
- the object to be initalized and called.
+ If the hook is an unbound lambda closure expecting arguments,
+ it is bound to the current object and called with the created
+ object as the first argument and any further arguments from the
+ new_lwobject() call. If the hook is an unbound lambda closure
+ without arguments, it is bound to the object to be initalized and
+ called. If the hook is any other type of closure, it is called
+ with the created object as the first argument and any further
+ arguments from the new_lwobject() call.
If the hook is defined as the name of an lfun in the lightweight
object, it is called in the new lwobject with any further arguments
@@ -28,4 +31,5 @@
LDMud 3.6.5 introduced lightweight objects.
SEE ALSO
- hooks(C), create_ob(H), create_super(H), create_clone(H)
+ hooks(C), create_lwobject_copy(H), create_lwobject_restore(H),
+ create_ob(H), create_super(H), create_clone(H)
diff --git a/doc/hook/create_lwobject_copy b/doc/hook/create_lwobject_copy
new file mode 100644
index 0000000..b1b21eb
--- /dev/null
+++ b/doc/hook/create_lwobject_copy
@@ -0,0 +1,31 @@
+SYNOPSIS
+ #include <sys/driver_hooks.h>
+
+ set_driver_hook(H_CREATE_LWOBJECT_COPY, value)
+
+ <value> being:
+
+ void <name> ()
+ void <closure> ()
+ void <closure> (lwobject obj_to_init)
+
+DESCRIPTION
+ Optional hook to finish initialization of a copy of a lightweight
+ object. Hook setting can be any closure, or the name of the
+ function (static or public) to call in the object.
+
+ If the hook is an unbound lambda closure expecting arguments, it is
+ bound to the current object and called with the created object as
+ the first argument. If the hook is an unbound lambda closure without
+ arguments, it is bound to the object to be initalized and called.
+ If the hook is any other type of closure, it is called with the
+ created object as the first argument.
+
+ If the hook is defined as the name of an lfun in the lightweight
+ object, it is called in the new lwobject.
+
+HISTORY
+ Introduced in LDMud 3.6.6.
+
+SEE ALSO
+ hooks(C), create_lwobject(H), copy(E), deep_copy(E)
diff --git a/doc/hook/create_lwobject_restore b/doc/hook/create_lwobject_restore
new file mode 100644
index 0000000..b108019
--- /dev/null
+++ b/doc/hook/create_lwobject_restore
@@ -0,0 +1,31 @@
+SYNOPSIS
+ #include <sys/driver_hooks.h>
+
+ set_driver_hook(H_CREATE_LWOBJECT_RESTORE, value)
+
+ <value> being:
+
+ void <name> ()
+ void <closure> ()
+ void <closure> (lwobject obj_to_init)
+
+DESCRIPTION
+ Optional hook to finish initialization of a restored lightweight
+ object. Hook setting can be any closure, or the name of the
+ function (static or public) to call in the object.
+
+ If the hook is an unbound lambda closure expecting arguments, it is
+ bound to the current object and called with the created object as
+ the first argument. If the hook is an unbound lambda closure without
+ arguments, it is bound to the object to be initalized and called.
+ If the hook is any other type of closure, it is called with the
+ created object as the first argument.
+
+ If the hook is defined as the name of an lfun in the lightweight
+ object, it is called in the new lwobject.
+
+HISTORY
+ Introduced in LDMud 3.6.6.
+
+SEE ALSO
+ hooks(C), create_lwobject(H), restore_value(E), restore_object(E)
diff --git a/doc/hook/create_ob b/doc/hook/create_ob
index 204a1f9..52a4605 100644
--- a/doc/hook/create_ob
+++ b/doc/hook/create_ob
@@ -10,15 +10,16 @@
int <closure> (object obj_to_init)
DESCRIPTION
- Optional hooks to initialize an explicitly loaded
- object/blueprint after creation. Hook setting can be unbound
- lambda closures or the name of the function (static or public) to
- call in the object.
+ Optional hooks to initialize an explicitly loaded object/blueprint
+ after creation. Hook setting can be any closure, or the name of
+ the function (static or public) to call in the object.
- If the hook is a closure expecting an argument, it is bound
- to the current object and called with the created object as
- argument. If the hook is a closure without arguments, it is bound to
- the object to be initalized and called.
+ If the hook is an unbound lambda closure expecting an argument,
+ it is bound to the current object and called with the created
+ object as argument. If the hook is an unbound lambda closure
+ without arguments, it is bound to the object to be initalized
+ and called. If the hook is any other type of closure, it is called
+ with the created object as argument.
If the result of the closure call is a non-zero number, it is used
as the interval to wait before the first reset(), else the default
diff --git a/doc/hook/create_super b/doc/hook/create_super
index 0f05542..9b2dc8b 100644
--- a/doc/hook/create_super
+++ b/doc/hook/create_super
@@ -13,13 +13,15 @@
Optional hooks to initialize a blueprint which is loaded by
inheritance after creation.
- Hook setting can be unbound lambda closures, or the name of
- the function (static or public) to call in the object.
+ Hook setting can be any closure, or the name of the function
+ (static or public) to call in the object.
- If the hook is a closure expecting an argument, it is bound
- to the current object and called with the created object as
- argument. If the hook is a closure without arguments, it is bound to
- the object to be initialized and called.
+ If the hook is an unbound lambda closure expecting an argument,
+ it is bound to the current object and called with the created
+ object as argument. If the hook is an unbound lambda closure
+ without arguments, it is bound to the object to be initialized
+ and called. If the hook is any other type of closure, it is
+ called with the created object as argument.
If the result of the closure call is a non-zero number, it is used
as the interval to wait before the first reset(), else the default
diff --git a/doc/hook/hook b/doc/hook/hook
index 7e66879..02c96f3 100644
--- a/doc/hook/hook
+++ b/doc/hook/hook
@@ -9,8 +9,8 @@
The hooks are set with the privileged efun set_driver_hook().
Some of the hooks are mandatory, some not. Most hooks accept
- unbound lambda closures as values, some also lfun closures or
- even strings.
+ unbound lambda closures as values, some also other types of
+ closures or even strings.
The hooks are identified by an ordinal number, for which
symbolic names are defined in /sys/driverhooks.h.
diff --git a/doc/hook/include_dirs b/doc/hook/include_dirs
index 9ee2fb6..630cc33 100644
--- a/doc/hook/include_dirs
+++ b/doc/hook/include_dirs
@@ -29,8 +29,8 @@
desired include file as first, and the name of the compiled
LPC file as second argument. Result has to be the complete
path name of the include file to use. Leading slashes may be
- omitted. If the closure is a lambda closure, it is bound to
- this_object() prior to execution.
+ omitted. If the closure is an unbound lambda closure, it is
+ bound to this_object() prior to execution.
HISTORY
diff --git a/doc/hook/modify_command b/doc/hook/modify_command
index f478312..1e7e808 100644
--- a/doc/hook/modify_command
+++ b/doc/hook/modify_command
@@ -11,8 +11,7 @@
DESCRIPTION
Optional hook to modify commands (both entered or given by a
- call to command()) before the parser sees them (this includes
- special commands like 'status').
+ call to command()) before the parser sees them.
Hook setting can be any closure, the name of the function to
call in the object, or a mapping.
@@ -23,8 +22,8 @@
If the hook is a closure, it is called with the entered
command as first, and the command giving player as second
- argument. Lambda closures are bound to the command giving player,
- unbound-lambda closures remain unbound.
+ argument. Unbound lambda closures are bound to the command
+ giving player.
If the hook is a string, it is used as the name of an lfun
in the command giving player, which is called with the command
diff --git a/doc/hook/msg_discarded b/doc/hook/msg_discarded
index 5360dfe..5dfb0d1 100644
--- a/doc/hook/msg_discarded
+++ b/doc/hook/msg_discarded
@@ -18,8 +18,8 @@
possible to the player informing about the lost transmission.
If the hook is a closure, it is the function to be called
- and the result is used as the message to be sent. Lambda
- closures are bound to the interactive <user> first.
+ and the result is used as the message to be sent. Unbound
+ lambda closures are bound to the interactive <user> first.
HISTORY
Introduced in LDMud 3.3.719
diff --git a/doc/hook/notify_fail b/doc/hook/notify_fail
index d229a55..2ea9697 100644
--- a/doc/hook/notify_fail
+++ b/doc/hook/notify_fail
@@ -18,8 +18,8 @@
If set to a closure, it is called with the command and the
command giver as arguments, and the result is used as failure
- message. Lambda closures are bound to this_player() prior to
- execution.
+ message. Unbound lambda closures are bound to this_player()
+ prior to execution.
<cmd_giver> is the object which received the command in the
first place. It is usually identical with this_player(),
diff --git a/doc/hook/reset b/doc/hook/reset
index 5021991..f1ba78a 100644
--- a/doc/hook/reset
+++ b/doc/hook/reset
@@ -5,16 +5,19 @@
<value> being:
- void|int <closure> ( void )
void <name>( void )
+ void|int <closure> ( void )
+ void|int <closure> (object obj_to_reset)
DESCRIPTION
- Optional hook to reset an object. Hook setting can be unbound
- lambda closures, or the name of the function (static or public)
- to call in the object.
+ Optional hook to reset an object. Hook setting can be any
+ closure, or the name of the function (static or public) to
+ call in the object.
- If the hook is a closure, it is bound to the object to be
- reset and called with no argument.
+ If the hook is an unbound lambda closure, it is bound to the
+ object to be reset and called with no argument. If the hook
+ is any other type of closure, it is called with the target
+ object as argument.
If the result of this call is a positive number, it is used as
the interval to wait before the next reset(). If the result
diff --git a/doc/hook/send_notify_fail b/doc/hook/send_notify_fail
index 7f61bb4..36222b3 100644
--- a/doc/hook/send_notify_fail
+++ b/doc/hook/send_notify_fail
@@ -16,8 +16,8 @@
If the hook is a string, it is the name of a (possibly static)
function to call in the current command giver. If the hook
- is a closure, it is the function to be called. Lambda closures
- are bound to the current command giver first.
+ is a closure, it is the function to be called. Unbound lambda
+ closures are bound to the current command giver first.
The arguments to the call are:
- <msg> is the notify fail message to be delivered.