Merge pull request #1292 from HerculesWS/huld-improvements

HULD improvements

1 files changed, 87 insertions, 13 deletions

diff --git a/doc/script_commands.txt b/doc/script_commands.txt
index 05d075ac1..f0758de71 100644
--- a/doc/script_commands.txt
+++ b/doc/script_commands.txt
@@ -1188,7 +1188,7 @@ From here on, we will have the commands sorted as followed:
 //=====================================
 ---------------------------------------
 
-*mes "<string>"{,"<string>"..."<string>"};
+*mes "<string>";
 
 This command will displays a box on the screen for the invoking character, 
 if no such box is displayed already, and will print the string specified 
@@ -1220,14 +1220,6 @@ non-English characters, the color codes might get screwed if they stick to
 letters with no intervening space. Separating them with spaces from the 
 letters on either side solves the problem.
 
-To display multiple lines of message while only using a single mes; 
-command, use the script command in the following format:
-
-    mes "Line 1", "Line 2", "Line 3";
-
-This will display 3 different lines while only consuming a single line in
-the relevant script file.
-
 If you're using a client from 2011-10-10aRagexe.exe onwards, you can also 
 use automatic navigation and open URLs in browser by using some HTML-like
 labels. For example:
@@ -1243,6 +1235,23 @@ Clicking Google will open the browser and point to Google website.
 
 ---------------------------------------
 
+*mesf("<format>"{,<param>{, <param>{, ...}}})
+
+This command will display a box on the screen for the invoking character,
+if no such box is displayed already, and will print the string specified
+into that box, after applying the same format-string replacements as sprintf().
+
+Example:
+
+	mesf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class));
+	// is equivalent to:
+	mes(sprintf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class)));
+
+This command is a combination of mes() and sprintf(). See their documentation
+for more details.
+
+---------------------------------------
+
 *next;
 
 This command will display a 'next' button in the message window for the 
@@ -8067,10 +8076,75 @@ Example:
 
 *sprintf(<format>{,param{,param{,...}}})
 
-C style sprintf. The resulting string is returned same as in PHP. All C 
-format specifiers are supported except %n. For more info check sprintf 
-function at www.cplusplus.com 
-Number of params is only limited by Hercules' script engine.
+C style sprintf. The resulting string is returned.
+
+The format string can contain placeholders (format specifiers) using the
+following structure:
+
+  %[parameter][flags][width]type
+
+The following format specifier types are supported:
+
+%%: Prints a literal '%' (special case, doesn't support parameter, flag, width)
+%d, %i: Formats the specified value as a decimal signed number
+%u: Formats the specified value as a decimal unsigned number
+%x: Formats the specified value as a hexadecimal (lowercase) unsigned number
+%X: Formats the specified value as a hexadecimal (uppercase) unsigned number
+%o: Formats the specified value as an octal unsigned number
+%s: Formats the specified value as a string
+%c: Formats the specified value as a character (only uses the first character
+    of strings)
+
+The following format specifier types are not supported:
+
+%n (not implemented due to safety concerns)
+%f, %F, %e, %E, %g, %G (the script engine doesn't use floating point values)
+%p (the script engine doesn't use pointers)
+%a, %A (not supported, use 0x%x and 0x%X respectively instead)
+
+An ordinal parameter can be specified in the form 'x$' (where x is a number),
+to reorder the output (this may be useful in translated strings, where the
+sentence order may be different from the original order). Example:
+
+	// Name, level, job name
+	mes(sprintf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class)));
+
+When translating the sentence to other languages (for example Italian),
+swapping some arguments may be appropriate, and it may be desirable to keep the
+actual arguments in the same order (i.e. when translating through the HULD):
+
+	// Job name is printed before the level, although they're specified in the opposite order.
+	// Name, job name, level
+	mes(sprintf("Ciao, io sono %1$s, un %3$s di livello %2$d", strcharinfo(PC_NAME), BaseLevel, jobname(Class)));
+
+The supported format specifier flags are:
+
+- (minus): Left-align the output of this format specifier. (the default is to
+  right-align the output).
++ (plus): Prepends a plus for positive signed-numeric types. positive = '+',
+  negative = '-'.
+(space): Prepends a space for positive signed-numeric types. positive = ' ',
+  negative = '-'.  This flag is ignored if the '+' flag exists.
+0 (zero): When a field width option is specified, prepends zeros for numeric
+  types. (the default prepends spaces).
+A field width can be specified.
+
+	mes(sprintf("The temperature is %+d degrees Celsius", .@temperature)); // Keeps the '+' sign in front of positive values
+	.@map_name$ = sprintf("quiz_%02d", .@i); // Keeps the leading 0 in "quiz_00", etc
+
+A field width may be specified, to ensure that 'at least' that many characters
+are printed. If a star ('*') is specified as width, then the width is read as
+argument to the sprintf() function. This also supports positional arguments.
+
+	sprintf("%04d", 10) // Returns "0010"
+	sprintf("%0*d", 5, 10) // Returns "00010"
+	sprintf("%5d", 10) // Returns "   10"
+	sprintf("%-5d", 10) // Returns "10   "
+	sprintf("%10s", "Hello") // Returns "     Hello";
+	sprintf("%-10s", "Hello") // Returns "Hello    ";
+
+Precision ('.X') and length ('hh', 'h', 'l', 'll', 'L', 'z', 'j', 't')
+specifiers are not implemented (not necessary for the script engine purposes)
 
 Example:
 	.@format$ = "The %s contains %d monkeys";