                     The Mayor Inheritable
                     written by Zaxan@Haven
                    Last Updated: 07-Aug-2000

This document details the different functions in the Haven
Library's Mayor inheritable. This document is divided into
many sections. Each section explains a different type of 
function in the lib inheritable.

Note that functions makred with /* REQUIRED */ must be used in
all mayors. Examples of mayors can be found in /std/npc.

The following is the header of the mayor inheritable with what
it includes, inherits, and its definitions:

***************************************************************
#include <lib.h>
#include <daemons.h>

inherit LIB_SENTIENT;

static void EvaluateCitizenshipRequest();
static void eventTitle();
***************************************************************

       ************************************************
                    Part 1: Events Section
       ************************************************

mixed eventRequestCitizenship(object who);
     After a player requests citizenship from a mayor and the
  EvaluateRequestCitizenship function returns a success, this function
  is executed. It sets the town of the player to the town of the
  mayor, sets the player's rank to citizen and removes all of
  the player's titles. Also, if a town has a tax to become a
  citizen, that tax will be deducted from the money they are
  carrying.
     When this has been done, the player is told that they are
  now a citizen of the new town and a message is sent over the 
  reports channel. The 'object who' should be the player object
  of the person wanting to change his/her town.

static void EvaluateCitizenshipRequest();
     Even though it does not start with event, EvaluateCitizenshipRequest
  still carries out an event action. It is responsible for executing
  CanRequestCitizenship() and responding depending on what that
  function returns. If CanRequestCitizenship() returns a success,
  then eventRequestCitizenship(this_player()) is executed. Otherwise,
  the player is given a message indicating why the request has been
  denied.

static void eventTitle();
     This function is responsible for giving the town's title to
  a player that requests one. This title is basically "the citizen
  of TownName". The title will only be given out if the player is
  a resident of that town.

       ************************************************
                 Part 2: Modal Methods Section
       ************************************************

mixed CanRequestCitizenship(object who);
     A player's first request for new citizenship is first approved
  by being evaluated by this function. First, if the town has a tax,
  it makes sure that the player has the money to pay this tax. If
  not, the mayor denies the request and mentions how much money the
  tax is. Another check makes sure the player isn't a citizen
  of the town already. The 'object who' should be the player object
  of the person wanting to change his/her town.

       ************************************************
              Part 3: Data Manipulation Functions
       ************************************************

static string SetLocalCurrency(string str); /* REQUIRED */
     This sets the local currency for the mayor. All taxes (if any)
  for the town will be evaluated with the currency provided here. All
  mayors must have this function set, otherwise it will default to
  "imperials".

string GetLocalCurrency();
     Returns the currency that the mayor uses. This currency that this
  function returns can be set with SetLocalCurrency().

string SetTown(string town); /* REQUIRED */
     Although not defined in /lib/mayor.c, the SetTown function is
  still required for a mayor to work properly. This should be set
  to whatever town the mayor controls. It will also determine what
  town a player's citizenship will be changed to. This must be set,
  otherwise it would default to "the Heavens".

string GetTown();
     Returns the town that the mayor controls. This can be set with
  SetTown().

static int SetTax(int x);
     Sets the amount of money that it costs for a player to become
  a citizen of the mayor's town. The amount will be multiplied by
  the value of the currency as compared to imperials. So, if the
  local currency is "rupies" and the tax is set to 1, then the
  total cost is 5 rupies, because there's 5 rupies to every 1
  imperial.

int GetTax();
     Returns the tax amount (in imperials) that will be charged to
  a player if he/she wants to become a citizen of the town.
