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

Documentation Area

Document Path: /doc/lib/curse_string

Simul efun: curse_string - colour a string

Synopsis:
	string curse_string(string replace, object player, status ignore_end)

Description:
	This function helps you to use ANSI-colours. It also checks if the
	player should get the codes, that means it checks the settings.

	DO NOT use ANSI escape sequences directly! See Note: below.

	The first argument is a string with codes starting with a dollar-sign
	('$'), a bit like (s)printf() or format_date(). Valid interpreted
	sequences are:

	$$	a literal '$'
	$b	bold
	$u	underlined
	$f	flashing/blinking
	$i	inverse
	$B<colour-char>
		background colour
	$C<colour-char>
		foreground colour
	$a	alert colour (set by player)
	$e	exit colour (set by player)
	$n	back to normal
	
	<colour-char> can be the following:
	
	B	black
	r	red
	g	green
	y	yellow (on some terminals brown)
	b	blue
	p	purple
	c	cyan
	w	white (on some terminals light grey)

	The optional second argument is the living which will be asked for
	settings. NPCs get no ANSI-codes. The default is this_player().

	If the optional third argument is zero (default), the function checks
	if you forgot to set back to normal. You can turn this feature off,
	for example if you need an ANSI-code more than once and with different
	text in it, by passing a non-zero third argument.

Return value:
	The replaced string with ANSI-codes.

Examples:
	write(curse_string("There are some $Cggreen leaves$n on the $CBdark "+
	  "branch$n.\n"));
	"There are some", "on the" and the "." at the end will be normal,
	"green leaves" will be green and "dark branch" will be black.

	write(curse_string("$aThe sand in your hourglass has run out "+
	  "completely.$n\n"));
	The full message will be in alert colour.

Note:
	Please don't use colours too often and only if it makes sense, for
	example in ASCII-art.

	Please don't '#include <ansi.h>' and do not use the '#defines' of
	ANSI-codes directly! ALWAYS use the simulated efun curse_string!

See also:
helpdir/ansi