Documentation of script functions and file types (work in progress)

doc/README

+doc/*
+
+This directory contains the Magic Set Editor technical documentation, as shown on the website.
+The files are converted to HTML using the 'autoformat' php script in tools/website/drupal.

doc/about/index.txt

+Magic Set Editor credits
+
+! Programming			<<<
+| [[user/1|Twan van Laarhoven]]	Main developer
+| [[user/430|coppro]]		Linux programmer
+	
+! Template development		<<<
+| [[user/14|Pichoro]]		Template maintainer, keywords and lots more
+| Artfreakwiu			Old style tokens, VS System, Pokemon, split cards
+| Guinea Pig			Hybrid blending masks, Non-creature flip cards
+| TheWarden			Collecting template images
+| Basilisk			Card frames
+| Jeff Torres (Wolfwood)	Vanguard, Flip cards, split cards
+| JrEye				Magic keyword list
+| Neko_Asakami			Multicolor blended flip cards, keywords
+	
+! Resources and libraries	<<<
+| [[http://boost.org|Boost]]				Boost C++ library
+| [[http://wxwidgets.org|wxWidgets]]			GUI library
+| [[http://famfamfam.com/lab/icons/silk/|Mark James]]	Icons for the program
+	
+! Alpha and beta testing	<<<
+| ''Too many people to mention!''	<<<

doc/function/index.txt

+Script functions by category
+
+These functions are built into the program, other [[type:function]]s can be defined using the scripting language.
+
+! Text manipulation		<<<
+| [[fun:to_upper]]		Convert a string to upper case, @"aBc" -> "ABC"@.
+| [[fun:to_lower]]		Convert a string to lower case, @"aBc" -> "abc"@.
+| [[fun:to_title]]		Convert a string to title case, @"aBc" -> "Abc"@.
+| [[fun:reverse]]		Reverse a string, @"aBc" -> "cBa"@.
+| [[fun:substring]]		Extract a part of a string.
+| [[fun:format]]		Format a number as a string (printf).
+| [[fun:format_rule]]		^^^
+| [[fun:curly_quotes]]		Make quotes curly.
+| [[fun:replace]]		Replace text matching a regular expression.
+| [[fun:replace_rule]]		^^^
+| [[fun:filter_text]]		Keep only the text matching a regular expression.
+| [[fun:filter_rule]]		^^^
+| [[fun:sort_text]]		Sort the letters in a string using a custom order.
+| [[fun:sort_rule]]		^^^
+| [[fun:contains]]		Does a string contain another one?
+| [[fun:match]]			Does a string match a regular expression?
+| [[fun:match_rule]]		^^^
+! [[type:tagged_string|Tags]]	<<<
+| [[fun:tag_contents]]		Change the contents of a specific tag.
+| [[fun:tag_contents_rule]]	^^^
+| [[fun:remove_tag]]		Remove a tag, keep the contents.
+| [[fun:tag_remove_rule]]	^^^
+! [[type:list|Lists]]		<<<
+| [[fun:position]]		Find the position of an element in a list.
+| [[fun:number_of_items]]	Find the number of items in a list.
+| [[fun:sort_list]]		Sort a list.
+| [[fun:filter_list]]		Filter a list, keeping only elements that match a predicate.
+	
+! Keywords			<<<
+| [[fun:expand_keywords]]	Expand the keywords in a piece of text.
+| [[fun:expand_keywords_rule]]	^^^
+| [[fun:keyword_usage]]		What keywords are used on a card, and how often are they used?
+	
+! English language			<<<
+| [[fun:english_number]]		Convert a number to text (@"one"@, @"two"@, ''etc.'')
+| [[fun:english_number_a]]		Convert a number to text (@"a"@, @"two"@, ''etc.'')
+| [[fun:english_number_multiple]]	Convert a number to text (@""@, @"two"@, ''etc.'')
+| [[fun:english_number_ordinal]]	Convert a number to text (@"first"@, @"second"@, ''etc.'')
+| [[fun:english_plural]]		Find the plural of a word, @"card" -> "cards"@.
+| [[fun:english_singular]]		Find the singular of a word, @"cards" -> "card"@.
+| [[fun:process_english_hints]]		Process the hints left by english_ functions in a keyword's reminder text.
+	
+! Fields and values			<<<
+| [[fun:combined_editor|forward_editor]]	Use one field to edit another.
+| [[fun:combined_editor]]		Use one field to edit multiple others.
+| [[fun:primary_choice]]		Return the top level choice chosen from a choice field.
+| [[fun:chosen]]			Is the given choice selected in a multiple choice value?
+| [[fun:require_choice]]		Require that at least one of the given choices is selected.
+| [[fun:exclusive_choice]]		Require that at most one of the given choices is selected.
+| [[fun:require_exclusive_choice]]	Require that exactly one of the given choices is selected.
+| [[fun:remove_choice]]			Remove the given choices from a multiple choice value.
+	
+! Images			<<<
+| [[fun:linear_blend]]		Blend two images together using a linear gradient.
+| [[fun:masked_blend]]		Blend two images together using a third mask image.
+| [[fun:combine_blend]]		Blend two images together using a given [[type:combine|combining mode]].
+| [[fun:set_mask]]		Set the transparancy mask of an image.
+| [[fun:set_alpha]]		Change the transparency of an image.
+| [[fun:set_combine]]		Chnage how the image should be combined with the background.
+| [[fun:enlarge]]		Enlarge an image by putting a border around it.
+| [[fun:drop_shadow]]		Add a drop shadow to an image.
+| [[fun:symbol_variation]]	Render a variation of a [[type:symbol]].
+| [[fun:built_in_image]]	Return an image built into the program.
+	
+! Other functions		<<<
+| [[fun:trace]]			Output a message for debugging purposes.

doc/function/position.txt

+Function: position
+
+--Usage--
+> position(of: some_item, in: some_list)
+
+Returns the position of an item in a list.
+The first position is @0@.
+If the item is not found in the list, returns @-1@.
+
+--Parameters--
+| @of@		''anything''			Item to look for.
+| @in@		[[type:list]] or [[type:set]]	List to look in.
+		  				Can be a [[type:set]] when looking for a card.
+| @order_by@	[[type:function]] (optional)	Find the position as if the list was [[fun:sort_list|sorted]] by this criterion.
+		  				Only when looking in a set.
+| @filter@	[[type:function]] (optional)	Find the position as if the list was [[fun:filter_list|filtered]] by this criterion.
+		  				Only when looking in a set.
+
+--Examples--
+> postion(of: "x", in: ["x", "y", "z"]) == 0
+> postion(of: "z", in: ["x", "y", "z"]) == 2
+> postion(of: "a", in: ["x", "y", "z"]) == -1
+>
+> # The position of the card in the list of red cards, ordered by name
+> postion(of: card, in: set, order_by: {card.name}, filter:{card.color == "red"})

doc/index.txt

+Documentation
+
+Welcome to the Magic Set Editor technical documentation.
+These documents describe the file formats and scirpting language used by the program.
+
+--Topics--
+* [[doc/tutorial|Templating tutorial]] (comming soon)
+* [[doc/file|File formats]]
+* [[doc/type|Data types used in the files]]
+* [[doc/script|Scripting language overview]]
+* [[doc/function|Script function reference]]
+
+--Other information--
+* [[doc/about|MSE credits]]
+* [[doc/about/license|License]]

doc/script/index.txt

+Scripting language
+

doc/type/color.txt

+==Data type: color==
+
+--Syntax--
+In files and scritps a color can be represented as
+<pre>rgb(<i>red_component</i>, <i>green_component</i>, <i>blue_component</i>)</pre>
+where red_component, green_component and blue_component are numbers between 0 and 255 (inclusive).
+
+--Examples--
+For example:
+! Code			Represents	
+| @rgb(255,255,255)@	white, <span style="border:1px solid black; background:white;width:20px;"> </span>
+| @rgb(0,0,0)@		black, <span style="border:1px solid black; background:white;width:20px;"> </span>
+| @rgb(255,0,0)@	red,   <span style="border:1px solid black; background:red;width:20px;"> </span>
+| @rgb(0,255,0)@	green, <span style="border:1px solid black; background:green;width:20px;"> </span>
+| @rgb(0,0,255)@	blue,  <span style="border:1px solid black; background:blue;width:20px;"> </span>

doc/type/combine.txt

+==Data type: image combine type==
+
+This specifies how an image is to be combined with the background.
+This is similair to the feature found in more advanced drawing programs.
+
+--Possible values--
+| overlay
\ No newline at end of file

doc/type/index.txt

+Data types
+
+Magic Set Editor uses many data types in the files and in scripting.
+There are for instance [[type:card]]s in [[type:set]]s, [[type:stylesheet]]s describing the layout of [[type:field]]s, etc.
+
+--Styling trinity--
+
+--File types--
+These are the 'major' data types that are written directly to [[file:package]]s.
+| [[type:game]]		What information is on each card?
+| [[type:stylesheets]]	What do cards look like?
+| [[type:set]]		Sets of cards.
+| [[type:symbol_font]]	Fonts consisting of symbols, for instance mana symbols.
+| [[type:export_template]]	How to export sets to HTML files?
+| [[type:locale]]	Translations of MSE.
+| [[type:include]]	Files to include in other templates.
+| [[type:installer]]	Installers containing several packages.
+| [[type:symbol]]	Expansion symbols.
+| [[type:settings]]	MSE settings.
+
+--Compound types--
+These contain several properties, similair to the file types. But they are part of some other file type.
+| [[type:field]]	A field description for cards.
+| [[type:style]]	The styling and positioning of a field.
+| [[type:value]]	The value in a field, for a particular card.
+| [[type:card]]		A card containing values.
+| [[type:keyword]]	A keyword.
+| [[type:font]]		Description of a font.
+| [[type:script]]	A script to execute to update a field, or for initialization.
+| [[type:symbol_part]]	Part of a [[type:symbol]].
+
+--Collection types--
+| [[type:list]]		Lists of items
+			* item
+			* item
+			* item
+| [[type:indexmap|'index' map]]	Lists indexed by field name
+			<table><tr><td>name:</td><td>someone</td></tr>
+			<tr><td>type:</td><td>something</td></tr></table>
+| [[type:map]]		Lists indexed by other text
+
+--Primitive types--
+| [[type:string]]	Text, @"abc"@
+| [[type:int]]		Integer numbers, @1, 2, 100@
+| [[type:double]]	Real numbers, @1, 0.5, 21.3@
+| [[type:color]]	Colors
+| [[type:scriptable]]	A primitive type whose value can depend on a script.
+| [[type:function]]	Functions in scripts. These have no direct representation in a file.

doc/type/list.txt

+Data type: Lists
+
+--File syntax--
+In files a list is represented as multiple keys, one for each element.
+The keys are all in the singular for of the name of the list,
+if the list is named for instance @symbols@ each key will be named @symbol@.
+] symbol:
+]	# first symbol here
+] symbol:
+]	# second symbol here
+] # etc.
+
+--Script syntax--
+In a script lists can be declared using square brackets.
+> []    # An empty list
+> [1]   # A list with a single element, the value 1
+> [1,2] # A list with two elements
+
+Lists can be accessed using either the bracket operator, or the dot operator.
+The first element of a list is numbered 0, the next 1, etc.
+> list.0  # The first element of the list 'list'
+> list[0] # The same thing
+
+There are several functions for working with lists:
+| [[fun:position]]		Find the position of an element in a list
+| [[fun:number_of_items]]	Find the number of items in a list
+| [[fun:sort_list]]		Sort a list
+| [[fun:filter_list]]		Filter a list, keeping only elements that match a predicate

doc/type/set.txt

+==Object type: Set==
+
+--Package--
+A set is described in a package with the <tt>.mse-set</tt> file extension,
+such a package contains a data file called <tt>set</tt>.
+
+--Properties--
+| game		Name of a [[type:game]]			The game this set is made for.
+| stylesheet	Name of a [[type:stylesheet]]		The default style for drawing cards in this set.
+| set info	[[type:indexmap]] of [[type:value]]s	The data for the [[prop:game:set fields]] defined in the game.
+| styling	[[type:indexmap]] of [[type:value]]s	
+| cards		[[type:list] of [[type:card]]s		The cards in the set.
+
+--Example--
+
+|-
+| <tt>set info:</tt>
+| Contains custom information about the set, corresponding to the <tt>set field</tt>s in the game.
+|-
+| <tt>extra set info:</tt>
+| Contains information about the set for a specific style, corresponding to the <tt>extra field</tt>s in the style. <br>
+  Stored with an index for the game, see the example below.
+|-
+| <tt>card:<br>card:<br><i>...</i></tt>
+| Contains information about each card, corresponding to the <tt>card field</tt>s in the game.
+|-
+| <tt>keyword:<br>keyword:<br><i>...</i></tt>
+| Extra keywords specific to this set, in addition to those defined in the game. 
+  For more information see the <a href="/extending/game">game file</a>
+|}
+
+The <tt>set info</tt> and <tt>card</tt>s contain a list of keys that correspond to the names fields in the game,
+For example if the game looks like:
+ name: my game
+ set field:
+ 	name: copyright
+ 	type: text
+ card field:
+ 	name: card name
+ 	type: text
+ card field:
+ 	name: power
+ 	type: text
+
+The the set file looks like:
+ game: my game
+ name: my set
+ set info:
+ 	copyright: something
+ extra set info:
+ 	name-of-style:
+ 		name-of-field: something
+ card:
+ 	card name: first card
+ 	power: 100
+ card:
+ 	card name: second card
+ 	power: 50
+
+
+The value that is stored depends on the type of field of course, in the above example the fields have <tt>type: text</tt>, so the value is just the text.
+For other types of fields the value is encoded as follows:
+{|
+! Attribute !! Description
+|-
+| <tt>text</tt>
+| The text that is stored in the field. This text can contain <a href="/extending/tags">tags</a>.
+|-
+| <tt>choice</tt>
+| One of the choices specified in the game.
+|-
+| <tt>boolean</tt>
+| One of <tt>yes</tt> or <tt>no</tt>.
+|-
+| <tt>color</tt>
+| The color is encoded as <tt>rgb(red,green,blue)</tt> where red, green and blue are numbers between 0 and 255 that indicate the color components.
+|-
+| <tt>image</tt>
+| The filename containing the image, this file must also be in the set package. It can be empty to indicate that no image is selected.
+|-
+| <tt>symbol</tt>
+| The filename containing the <a href="/extending/symbol">symbol specification</a>, this file must also be in the set package.
+  It can be empty to indicate that no symbol is selected.
+|}
+If a field has the default value (calculated by the default script), then the field name and value are ommited from the set file.

doc/type/string.txt

+==Data type: character string==
+
+--File syntax--
+
+--Script syntax--
\ No newline at end of file

doc/type/stylesheet.txt

+Object type: Stylesheet
+
+--Properties--
+| @game@		Name of a [[type:game]]			Game this stylesheet is made for
+| @init script@		[[type:script]]				
+| @card width@		[[type:double]]				Width of cards in pixels
+| @card height@		[[type:double]]				Height of cards in pixels
+| @card dpi@		[[type:double]]				Resoltion of cards in dots-per-inch
+| @card background@	[[type:color]]				Background color of cards
+| @card style@		[[type:indexmap] of [[type:style]]s	Styles for the [[property:game:card fields]] defined in the game
+| 
+

doc/type/tagged_string.txt

+==Data type: string with tags==
+
+--Syntax--
+&1;
+
+--Basic markup--
+! Tag		Description
+| <b>		The text inside the tag is bold.
+| <i>		The text inside the tag is italic.
+| <sym>		The text inside the tag is rendered as symbols, if a [[prop:style:symbol font]] is set for the text box.
+| <line>	Line breaks inside this tag use the [[prop:style:line height line]], and they show a horizontal line.
+| <soft-line>	Line breaks inside this tag use the [[prop:style:soft line height]].
+| <atom>	An atomic piece of text. The cursor can never be inside it; it is selected as a whole.
+		The program automatically inserts <atom-soft>
+| <code>	The text inside the text is rendered in a monospace font. This is used for syntax highlighting script code.
+| <code-kw>	The text inside the text is highlighted as a keyword in source code.
+| <code-str>	The text inside the text is highlighted as a string in source code.
+
+
+--Other tags--
+! Tag		Description
+| <kw-?>	Indicates that the text inside it is a keyword. This tag is automatically inserted by
+		The [[fun:expand_keywords] function. There are four versions, indicating whether or not reminder text is shown
+		| <kw-0>	Reminder text hidden, by default
+		| <kw-1>	Reminder text shown, by default
+		| <kw-a>	Remder hidden manually
+		| <kw-A>	Remder shown manually
+| <sep>		A separator between fields. This tag is automatically inserted by the [[fun:combined_editor]] function.
+		Inserting this tag manually will confuse that function!
+		This tag can never be selected, and its contents can not be edited.
+| <sep-soft>	Like &lt;sep>, only hidden. This is inserted by [[fun:combined_editor]]
+		...
+| any other tag	Other tags are ignored.
+
+--Related functions--
+The following script functions deal with tags:
+| [[fun:remove_tag]]

doc/type/value.txt

+== Object type: Field value ==