This is an introduction to verbs in Lima.

There's more extensive technical details in "help parser".

Details of the implementation of verbs have changed many times,
and will no doubt change again, so don't be surprised if there are small
differences between what is written here and what actually happens
in your mud.

Verbs should generally be used instead of commands for "in character" ("IC")
actions, ie actions which the character should have access to, rather than 
the player - eg "look" (IC) should be a verb, while "help" should not.
Lima does not support add_actions.

Reasons for this - 
verbs have a central "condition checking" (is the character dead ? etc),
other checking for whether the action is possible is well-supported
multiple syntaxes can easily be defined for each verb
aliases can be defined for each syntax within each verb
sensible default error messages, easily tailored as required

Basics
======
Verbs are defined in individual files within /cmds/verbs/

They inherit VERB_OB

The syntaxes (rules) and aliases allowed for the verb are defined using the 
add_rules() function within create()

Each rule for the verb has a corresponding do_ function.

Optional can_ function for each syntax - if it doesn't evaluate to 1,
the action is prevented, using default error message if 0 is returned, 
whilst returning a string causes that to be used as the error message.

Verbs using any OBJ rule (ie the rule involves an object) require a
direct_ function, similar to the optional can_ function

Verbs involving a second object require a similar indirect_ function
for that second object.

Details
=======

Flags are used to signify which of the following checks are to be applied
in the verb :
NEED_TO_SEE
NEED_TO_BE_ALIVE
NEED_TO_THINK
TRY_TO_ACQUIRE
The first three are self-explanatory, and are included by default.
TRY_TO_ACQUIRE is excluded by default, and adding it signifies that the verb
requires the object to be in the player's possession, and will try to acquire
it first.

Use add_flag() and clear_flag() to add/remove these condition checks,
and include verbs.h which is where they are defined.

Most objects will inherit /std/obj/vsupport.c, which contains various 
default verb support functions (generally direct_).

When evaluating direct_ and indirect_ functions, any such functions in 
either the verb or the object concerned will be checked, followed by the
generic "direct_verb_rule()" and indirect_verb_rule() functions.

A default version of direct_verb_rule() is included in /std/obj/vsupport.c,
normally returning 1 for containers (rooms) and exits (provided the object 
passes the default checks, such as being visible).

Similarly a default version of indirect_verb_rule() was included in CONTAINER
(/std/container.c), allowing moving things to/from containers by default
(put, get etc) - this has now been moved to /std/container/vsupport.c and
replaced by specific indirect_ functions for the appropriate verbs.

Default implementations for various rules are included in VERB_OB.
For example, the implementation of the OBJ rule calls do_verb() in the object,
after having made various checks.

Problems
========
Use the "parse" command (in front of the normal verb syntax) to see the 
results of can/direct/indirect checks, and hence which rule(if any) is
used.

In order for the parse command to function, the driver should be compiled
in debug mode - ie "./build.MudOS debug"

SIMPLE EXAMPLE
==============
A verb for kicking things

inherit VEB_OB;

void do_kick_obj(object ob)
{
  ob->do_kick();
}

void create()
{
  add_rules( ({ "OBJ" }) ({ }) );
}

In any object which can successfully be kicked :
have a direct_kick_obj() function returning 1
have a do_kick() function which implements the effects of kicking it

eg a ball to kick:
inherit OBJ;

void setup()
{
  set_id("ball");
  set_long("It's a ball, sitting waiting to be kicked....");
}

mixed dirct_kick_obj() { return 1; }

void do_kick()
{
  this_body()->simple_action("$N $vkick $o.", this_object();
// ADD SOME CODE TO MOVE IT TO A NEW ROOM
// AND MESSAGE ON ENTERING THE ROOM
}

It's usually worth abstracting such code into a module, so that similar
items can inherit the module, instead of cut/pasting the support code.