Automatic Python OLC

Extract the provided files so that the polc folder is in lib/pymodules. If
desired, you can place cmd_channels.py and cmd_examples.py in lib/pymodules as
well for some example functions.

New in v2.1 is the iedit command/example. It can be used to edit an instance
of a room, character, object, or exit. By default, it's only usable by wizards
and up. Check it out for a good general example of using this system.

If you don't want the editor, you can remove it by removing editor.py and
editing __init__.py to stop trying to import functions from it.

And now, some help.

===============================================================================
Functions
===============================================================================

OLC Entry Point
polc.do_olc(sock, object, saver = None, key = None, options = None, autosave = False)

do_olc starts the OLC system, automatically creating menus for you based on the
provided object and any options you give it. If a saver function is specified
(and autosave is disabled), that function will be called when the editing
process is complete with the arguments: sock, key, object

Options, if provided, should be a dictionary object. A list of all avaliable
keys is at the end of the document.

IEDIT Extender
polc.extend(editor, key, menu_func, chooser_func, parser_func = None)

extend is used to extend the iedit command added in v2.1. It works exactly like
the olc.extend() command, aside from the lack of arguments dealing with getting
and setting protos. As it deals with instances, protos don't really come into
things at all...

For compatibility reasons, you CAN specify the proto functions as well, making
this function exactly the same as olc.extend, only with a letter p in front. If
you do though, the values won't be used.

IEDIT Item Type Handler
polc.item_add_olc(itemtype, menu_func, chooser_func, parse_func)

Adds a new item type that can be edited to the iedit command. This, like the
polc.extend command, works just like olc.item_add_olc, aside from the lack of
proto functions at the end.

For compatibility reasons, you CAN specify the proto functions as well, making
this function exactly the same as olc.item_add_olc, only with a letter p in
front. If you do though, the values won't be used.

IEDIT Entry Point
polc.edit_room(sock, room)
polc.edit_object(sock, object)
polc.edit_exit(sock, exit)
polc.edit_character(sock, character)

Directly starts the editor for a room, object, exit, or character. Using this,
you can load the iedit editor from your own code to edit an object.

===============================================================================
Options for the do_olc Options Array
===============================================================================

Key            | Description
---------------+---------------------------------------------------------------
allow-commands | If present, the OLC system will allow a player to enter
               | commands by prefixing them with '- '. See cmd_examples.py for
               | an example.
               |
autosave       | If present and true, the OLC system will automatically save
               | changes to an object instead of asking the user if they wish
               | to save. Be warned, with this flag on, the saver function you
               | specified will NOT be called. This could also be set directly
               | when you call do_olc.
               |
hidden         | A list of keys to exclude from display on the menu. This isn't
               | necessary if you're using the order key, as only the items
               | specifically listed in order would be displayed.
               |
keys					 | A dictionary, with keys matching keys from the object, and single
               | characters to use as menu keys as values.
               |
name           | If present, the menu title text will be this string. Otherwise,
               | the system will attempt to dynamically generate a meaningful
               | name for the object to display.
               |
order          | A list of keys that tells the menu what order to display the
               | data in. To insert blank lines into the menu, include an empty
               | string in the list.
               |
readonly       | A list of keys that, while they will be displayed, will not
               | be editable using the menu system.

In addition, you can set specific options for an individual key by creating a
dict of those options inside the main options dict with a key formatted as:
'_key'. For example, for setting options on the key 'name', the options key
would be '_name'. This is to prevent any overlap with the main settings.

The following keys can be used with individual keys:

Key            | Description
---------------+---------------------------------------------------------------
choices        | A list of possible choices for a value. This is useful for
               | things such as a gender option, a race selector, or a list of
               | bits. If the value previously assigned to the key is a list,
               | a submenu will be opened to allow you to toggle individual
               | choices on or off. Otherwise, a simple selector will ask you
               | to pick a specific choice.
               |
empty          | A string that, if set, will be output instead of <NONE> by
               | the string renderer.
               |
extend_handler | A function to call when the key is selected in the menu. The
               | extend_handler function, unlike the normal handler function,
               | is compatible with the chooser_func from olc.extend
               |
extend_parser  | A function to call to parse the value for the key. Unlike the
               | normal parser function, this option is compatible with the
               | parse_func from olc.extend
               |
extend_renderer| A function to call to display the value for the key in the
               | menu. Unlike the normal renderer functions, this function is
               | compatible with the display functions used by olc.extend
               |
force					 | Forcibly attempt to treat the value as the given type, even
               | if it's detected as some other type. Mainly, this is useful
               | for processing comma-separated strings that have choices
               | specified.
               |
handler        | A function to call when the key is selected in the menu. This
               | can be used to enter a custom system for data that cannot be
               | edited well with the default system. Should accept three args:
               | 'sock, data, key' and return one of:
               | olc.MENU_CHOICE_INVALID or olc.MENU_NOCHOICE
               |
min            | If present and the value assigned to the key is a number, the
               | system will ensure that any new value is at least this number.
               | If the previous value is a string, it will ensure that the new
               | string is at least this many characters in length.
               |
max            | Like min, but makes sure numbers are smaller and strings are
               | shorter.
               |
multi          | If present, instead of a normal simple prompt for entering a
               | new value, the text editor interface will be started with
               | the previous value as the default text.
               |
name           | If present, this name will be displayed for the key. Otherwise,
               | the system will attempt to find the key name in a list of
               | common replacements. If the key does not have a suitable
               | replacement, it will have any underscores converted to spaces
               | and will be formatted with title casing.
               |
nocolor        | If present, the system will escape color codes when displaying
               | the string assigned to the key. Depreciated in favor of:
               | process: 'no-color'
               |
parser         | A function to call to parse the value for the key. This can be
               | used to edit custom data types with the editor, such as a date.
               | See cmd_examples.py for an example. Should accept four args:
               | 'sock, data, key, val' and return either the parsed value or
               | a boolean False, indicating that the value is invalid.
               |
places         | A number, used by the number renderer to tell how many digits
               | to round a floating-point number to for display.
               |
process        | A function that, if specified, will be used to process string
               | values when they're rendered. If set to 'no-color', color codes
               | will be escaped.
               |
prompt         | A string that, if present, will be displayed as the prompt for
               | editing the key's value. Otherwise, a default prompt will be
               | displayed based on the type.
               |
range          | A shortcut for entering both min and max. This should be a
               | comma-separated string of 'min,max'.
               |
raw_renderer   | Only differs from renderer in that it's added directly to the
               | key's name instead of being spaced and prefixed with a colon.
               |
renderer       | A function to call to display the value for the key in the
               | menu. This can be used to display custom data types in the
               | editor. See cmd_examples.py for an example. Should take
               | four arguments 'sock,data,key,val' and return a string.
               |
same-line      | If present, the menu will feature the value of the key on the
               | same line as the key itself. This is only useful for values
               | that are strings.
               |
single-line    | Alias for same-line
               |
type           | This key serves two purposes. If used together with multi, it
               | will be passed to the text editor as the mode. Specify that:
               | type = 'script' to use a Python script editor.
               |
               | If not used with multi, this allows you to perform some basic
               | string checking. If type is 'alnum', only alpha-numeric
               | strings are allowed. If type is 'alpha', only strings of
               | letters are allowed. If type is 'digit', only strings of
               | numbers are allowed.
               |
validate       | A function to call to check a new value being assigned to the
               | key to ensure that it's valid. Should take one argument, value,
               | and return True or False.
               |
value          | Force the system to assume a specific value for a key and not
               | attempt to read the key from the object. This is useful for
               | creating extra menu options. For an example, see the room
               | editor's exit editing commands in editor.py

~Stendec~
stendec365@gmail.com

Last updated: 9/3/2009