UserAgent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.8) Gecko/20050517 Firefox/1.0.4 (Debian package 1.0.4-2) IP: 64.81.113.168 URI: http://wesnoth.slack.it/?PreprocessorRef - - - - - Index: PreprocessorRef =================================================================== RCS file: /home/wesnoth/cvsroot/wikiroot/PreprocessorRef,v retrieving revision 1.17 diff -u -r1.17 PreprocessorRef --- PreprocessorRef 8 May 2005 22:08:00 -0000 1.17 +++ PreprocessorRef 2 Jul 2005 17:24:29 -0000 @@ -1,77 +1,85 @@ +||the WML preprocessor|| + Wesnoth loads just one configuration file directly: ||data/game.cfg||. However the WML preprocessor allows game.cfg to load in more files. Whenever a WML file is read by Wesnoth, it is passed through a preprocessor. -The preprocessor is applied recursively, i.e included files will be parsed for macros, and macro expansion will be -reparsed for macros, etc. As a result, you cannot write a recursive macro, because it will cause an infinite loop. +The preprocessor is applied recursively, i.e included files will be parsed for macros, +and macro expansion will be reparsed for macros, etc. +As a result, you should not write a recursive macro, +because it will cause an infinite loop and crash Wesnoth. +<a href="http://www.wesnoth.org/forum/viewtopic.php?t=5838";>Changes to the preprocessor in 0.9.2</a> +allow recursively nested #ifdefs, but recursively nested macro definitions ('#define') +will still cause errors (but not necessarily error messages). + +The following directives are used to create and use //macros//, +i.e. shortcuts which reduce repetition of information. +See UtilWML, UsefulWMLFragments for examples. +* ||#define //symbol// [//parameters//] //newline// //substitution// #enddef|| +all subsequent occurences of ||{//symbol// [//arguments//]}|| (see below) +will be replaced by //substitution// with all occurences of any parameter +{//parameter//} within //substitution// replaced by the parameter's corresponding value in //arguments//. +For example, the UNIT macro used below would be defined: -These instructions tell the preprocessor how to expand the file: + #define UNIT TYPE X Y## the ordering is important here; since WML does not distinguish data into different types, + ## only the ordering is used to determine which arguments apply to which parameters. + [unit] + type={TYPE}## the unit will be of type TYPE, so different instantiations of this macro can create different units. + x={X} + y={Y} + side=2## the unit will be an enemy, regardless of the parameter values. This reduces "repetition of information", + ## since it is no longer necessary to specify each created unit as enemy. + [/unit] + #enddef +(See SingleUnitWML for information on creating units using WML.) * ||{//symbol// [//arguments//]}|| if //symbol// is defined, the preprocessor will replace this instruction by the expression //symbol// is defined as, using //arguments// as parameters. -You can use multiple words arguments with ||(//multiple word argument//)|| inside the macro call as in {CREATE_UNIT (Wolf -Rider) 18 24} -(||CREATE_UNIT|| is assumed to be a predefined symbol). -See the //#define// preprocessor instruction for defining symbols, including symbols with arguments. -Several symbols are defined in the normal game code; these are known as //ids//. -* ||{//filename//}|| if the content of the bracket isn't a known symbol, -Wesnoth will assume it's a file in the main data/ -subdirectory of Wesnoth and include it here "as is", unless it starts with //./ //, in which case it is -assumed to be a relative path. -If //filename// is a directory, -then all config (//.cfg//) files in the directory (non-recursively), in alphabetical order, will be included. -* ||{~//filename//}|| similar to above, but Wesnoth assumes the filename is relative to the user data directory -||~/.wesnoth/data/|| -(||userdata/|| on Windows). -* ||{@//filename//}|| is a convenient way to make Wesnoth look for a file by that name in both the main and the user -data directory. -* ||#define //symbol// [//parameters//] //newline// //substitution// #enddef|| all occurences of -{//symbol// [//arguments//]} -will be replaced by //substitution// with all occurences of any parameter -{//parameter//} within //substitution// replaced by the parameter's corresponding value in //arguments//. +You can create multiple words arguments by using parentheses to restrain the argument. +For example, while ||{UNIT Wolf Rider 18 24}|| will attempt to create a "Wolf" at (Rider,18), causing Wesnoth to crash, +the macro ||{UNIT (Wolf Rider) 18 24}|| will create a "Wolf Rider" at (18,24) as it should. +(||UNIT|| is defined above). +See the //#define// preprocessor instruction above for information on defining symbols, +including symbols with arguments. +Several symbols are defined in the normal game code; for reference they are listed in UtilWML. + +Unlike the other preprocessor directives, #ifdef is not used for convenience. +It is necessary to distinguish between differen modes of play. * ||#ifdef //symbol// //substitution-if-stored// [#else //substitution-if-not-stored//] #endif|| if //symbol// has been stored, the whole block will be replaced by //substitution-if-stored//. if not, it will be replaced by //substitution-if-not-stored// if it is available. -In a normal campaign, one of the symbols ||EASY||, ||NORMAL||, or ||HARD|| -will be stored depending on the difficulty level (See CampaignWML). -This can be used to change the way a scenario works depending on the difficulty level. +Each campaign stores both a difficulty level (usually ||EASY||, ||NORMAL||, or ||HARD||), +and a campaign ID. See CampaignWML for information on how and why to store symbols. -Example: +These directives expand a file by including other files: +* ||{//filename//}|| if //filename// isn't a predefined symbol (see above), +Wesnoth will assume it's a path to a file in the main data/ +subdirectory of Wesnoth and include the file it points to here "as is". +Forward slashes('||/||') should be used to separate directories from their elements, +even if your platform uses a different symbol such as arrow('||>||') or backslash('||\||'). +If //filename// points to a directory, +the preprocessor will include all files in the directory //filename//, +non-recursively and in alphabetical order. +* ||{~//filename//}|| similar to above, but the preprocessor assumes +that the filename is relative to the user data directory. +The //user data directory// varies depending on platform: + + Platform| User Data Directory + ----------------------------- + UNIX | ~/.wesnoth/data/ + Mac OSX | user home folder>Library>Preferences>Wesnoth + Windows | main Wesnoth directory/userdata/ +* ||{@//filename//}|| is a convenient way +to make Wesnoth look for a file by that name in both the main and the user data directory. +It is equivalent to writing ||{//filename//}{~//filename//}||. +* ||{./<i>filename</i>}|| similar to the ||{//filename//}|| directive, +but is assumed to be relative to the directory which contains the file which contains it. +For example, if used in game.cfg, it is equivalent to ||{//filename//}||. -in data/game.cfg: - #define ENEMY TYPE X Y - [unit] - side=2 - type={TYPE} - x={X} - y={Y} - [/unit] - #enddef - {scenarios} -in data/scenarios/scenario1.cfg - #ifdef HARD - {ENEMY (Wolf Rider) 2 4} - {ENEMY Troll 3 3} - #endif - -When the scenario is played on hard, then the file will be expanded into: - [unit] - side=2 - type=Wolf Rider - x=2 - y=4 - [/unit] - [unit] - side=2 - type=Troll - x=3 - y=3 - [/unit] ||See Also|| * SyntaxWML -* UtilWML * ReferenceWML -* <a href="http://www.wesnoth.org/forum/viewtopic.php?t=5838";>forum thread about new preprocessor in 0.9.2</a> +
_______________________________________________ Wesnoth-wiki-changes mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/wesnoth-wiki-changes
