A
          / \      _             Play Now                         Nemesis on 
          | |     | |  _______   _        _   _______    _______   _    _______
          | |\    | | |   ____| |  \    /  | |   ____|  /   ____| | |  /   ____|
 /-------/-------------------------------------------------------------------,
O= Home <=XX|  About  News  Pics  Adventurers  Wizards  Download  Connect     >
 \-------\-------------------------------------------------------------------'
          | |   \   | |  |____  | |      | | |  |____   ___ \  \  | |  ___ \  \
          | |     \_| |_______| |_|      |_| |_______| |_______/  |_| |_______/
          \ /
           V  

Documentation Area

Document Path: /doc/lib/more

Lfun:	more - use more to display text

Synopsis:
	#include <player.h>
	object MORE_OBJ->more(string(*) text, string title,
	  object|string call_object, string function, string options);

Description:
	This will start more to display a given text to this_player().
	It is not intended for direct cloning!

	The given text can be one of the following:
		- a filename, indicated by a slash / at the beginning
		- a text, lines separated by newslines "\n"
		- an array of lines, lines mustn't contain newlines

	The title is used when the file was completely displayed and also,
	if the 't' option is specified (see below: Options), always when
	prompting for new input.
	If the title is not specified, "file" is taken. If you don't want
	a message after displaying the full file, use "" (empty string).

	The call_object is used for changing text in the file (calling the
	function argument) and if the user stopped reading the file (calling
	end_more()).
	It can either be an object pointer or a string containing a filename.

	The function argument is a string containing a function name. It is
	called in the call_object for every line.
	The line is passed as first, the line number as second argument.
	The function should return one of the following:
		- 0, indicating that nothing is changed in the line
		- a string, lines separated by "\n", to replace the original
		  line
		- an array of lines, each line without any "\n", to replace
		  the original line (also ({}) (empty array) possible, then
		  the line is removed)

Options:
	The fifth and last argument should be a string containing
	single-character options, which are:
		- 'h' or '?': (help)
			The "More:" prompt will contain information how to
			view a short help on more.
		- 's': (stay)
			After displaying the last lines, we will stay in more.
			Here the user can enter another more command or just
			press enter to stop reading.
		- 't': (title)
			Show the given title in the "More:" prompt, works only
			if the given title is not "" (see above).
	So, you could use the option string "hs" to activate the help and stay
	options.

Return value:
	0, if there was something wrong about the arguments.
	The more object if the text was short enough to be displayed at once.
	The clone of the more object used for this more if the prompt had to
	be printed at least once.

Note:
	It is not intended for direct cloning!

	Please note that the more is not done after the call: It was only
	started. If you need to do something after the more, use end_more().

Example:
	MORE_OBJ->more("/text/init_text", "scroll");

See also:
w/more
player/more
efun/input_to
efun/in_input
efun/this_player