diff --git a/.clang-format b/.clang-format index 54c71806..9db3c7cf 100644 --- a/.clang-format +++ b/.clang-format @@ -1,10 +1,2 @@ -{ - 'TabWidth': 4, - 'ColumnLimit': 80, - 'UseTab': 'Always', - 'IndentWidth': 4, - 'AlwaysBreakTemplateDeclarations': 'true', - 'BasedOnStyle': 'LLVM', - 'PenaltyBreakString': 9000 -} +{'TabWidth': 4, 'ColumnLimit': 80, 'IndentWidth': 4, 'AlwaysBreakTemplateDeclarations': 'true', 'BasedOnStyle': 'LLVM', 'PenaltyBreakString': 9000} diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..84b96d82 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,11 @@ +# top-most EditorConfig file +root = true + +# Matches multiple files with brace expansion notation +# Set default charset +[*.{c,h,cpp,hpp}] +charset = utf-8 +indent_style = space +indent_size = 4 +trim_trailing_whitespace = true +max_line_length = 80 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..a9280e72 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,15 @@ +# Set the default behavior, in case people don't have core.autocrlf set. +* text=auto + +# Explicitly declare text files you want to always be normalized and converted +# to native line endings on checkout. +*.c text +*.cpp text +*.h text + +# Declare files that will always have CRLF line endings on checkout. +*.sln text eol=crlf + +# Denote all files that are truly binary and should not be modified. +*.png binary +*.jpg binary diff --git a/CMakeLists.txt b/CMakeLists.txt index 728b62f2..ae16cb1e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,4 +1,4 @@ -cmake_minimum_required(VERSION 3.1) +cmake_minimum_required(VERSION 3.3 FATAL_ERROR) project(MagicSetEditor) @@ -589,6 +589,16 @@ set_target_properties(magicseteditor ) # }}} +# Include what you use {{{ +find_program(iwyu_path NAMES include-what-you-use iwyu) +if(NOT iwyu_path) + message(FATAL_ERROR "Could not find the program include-what-you-use") +endif() + +set_property(TARGET magicseteditor PROPERTY + CXX_INCLUDE_WHAT_YOU_USE ${iwyu_path}) +# }}} + # Install data and executable {{{ set(WX_DATA_DIR share/magicseteditor) diff --git a/TODO b/TODO deleted file mode 100644 index e69de29b..00000000 diff --git a/data/magic-new-common.mse-include/include b/data/magic-new-common.mse-include/include index 340d96dc..e3828d37 100644 --- a/data/magic-new-common.mse-include/include +++ b/data/magic-new-common.mse-include/include @@ -1,3 +1,3 @@ -mse version: 2.0.0 -full name: Icons/symbols for Modern Magic The Gathering templates -version: 2011-09-11 +mse version: 2.0.0 +full name: Icons/symbols for Modern Magic The Gathering templates +version: 2011-09-11 diff --git a/data/magic-new-transform.mse-style/style b/data/magic-new-transform.mse-style/style index e07fbb33..3bff2d33 100644 --- a/data/magic-new-transform.mse-style/style +++ b/data/magic-new-transform.mse-style/style @@ -1,742 +1,742 @@ -mse version: 2.0.0 -game: magic -short name: Modern Transformer -full name: Innistrad Transformers -icon: card-sample.png -position hint: 002 -installer group: magic/new style/transformer - -version: 2011-09-15 -depends on: magic.mse-game 2011-09-10 -depends on: magic-new-common.mse-include 2011-09-11 -depends on: magic-default-image.mse-include 2007-09-23 -depends on: magic-watermarks.mse-include 2007-09-23 -depends on: magic-mana-large.mse-symbol-font 2011-04-10 -depends on: magic-mana-small.mse-symbol-font 2011-04-10 - -card background: white -card width: 375 -card height: 523 -card dpi: 150 - -############################################################## Extra scripts - -init script: - # Load scripts for image box - include file: /magic-default-image.mse-include/scripts - - # Should hybrids have a grey name? - mask_hybrid_with_land := { styling.grey_hybrid_name } - - #Should multicolor lands with basic land types have a colored name? - mask_multi_land_with_color := { styling.colored_multicolor_land_name } - - # Which artifact template should be used? - alternate_template := { - if input == "a" then ( - if styling.artifact_style == "brown" then "ba" - else "a" - ) else if input == "m" then ( - if styling.saturated_multicolor then "m" - else "om" - ) else input - } - template := { (if type=="identity" then "/magic-new-common.mse-include/" else (if is_night() then "n" else "d")) + alternate_template() + "{type}." + (if type=="identity" then "png" else "jpg") } - land_template := { (if type=="identity" then "/magic-new-common.mse-include/" else (if is_night() then "n" else "d")) + (if input == "a" then "c" else alternate_template()) + (if type=="identity" then "" else "l") + "{type}." +(if type=="identity" then "png" else "jpg") } - # Use land templates for previews because they show more contrast - hybrid_previews := "land,hybrid" - - # Use the normal tap symbol - mana_t := { - if styling.tap_symbol == "old" then "old" - else if styling.tap_symbol == "diagonal T" then "older" - else "new" - } - - # Use guild mana symbols? - guild_mana := { styling.use_guild_mana_symbols } - - # Replacing the section of the blends file relevant to masking due to day and night having different masks - color_combination := { - # The base hybrid, without the outer frame blended over it - base := base_hybrid[shape][color_count]() - - # Put a frame around it? - if land and not colored_lands then - masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "multicolor_blend_{type}.png", - dark: land_template("c"), - light: base, - ) - else if land and multi and mask_multi_land_with_color() then - masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + "hybrid_blend_{type}.png", - dark: base, - light: land_template("m"), - ) - else if multi and artifact then - masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "artifact_blend_{type}.png", - dark: template("a"), - light: masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "multicolor_blend_{type}.png", - dark: template("m"), - light: base - ) - ) - else if multi then - masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "multicolor_blend_{type}.png", - dark: template("m"), - light: base, - ) - else if artifact and color_count > 1 and mask_hybrid_with_land() then - masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "artifact_blend_{type}.png", - dark: template("a"), - light: masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "multicolor_blend_{type}.png", - dark: template("c"), - light: base - ) - ) - else if artifact then - masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "artifact_blend_{type}.png", - dark: template("a"), - light: base, - ) - else if color_count > 1 and mask_hybrid_with_land() then - masked_blend( - mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + "hybrid_blend_{type}.png", - dark: land_template("c"), - light: base, - ) - else base - } - -############################################################## Set info fields -set info style: - symbol: - variation: - name: invertedcommon - border radius: 0.10 - fill type: solid - fill color: rgb(255,255,255) - border color: rgb(0,0,0) - -############################################################## Extra style options - -styling field: - type: choice - name: color identity - choice: always - choice: sometimes - choice: never - description: Do you want to always, sometimes, or never use color indicators? - initial: sometimes -styling field: - type: choice - name: artifact style - description: Choose the style of artifacts: light = before Fifth Dawn, dark = used since Fifth Dawn, brown = old rust style. - initial: dark - choice: dark - choice: brown -styling field: - type: boolean - name: saturated multicolor - description: Should multicolor cards be more saturated? This is done on real cards. - initial: yes -styling field: - type: boolean - name: grey hybrid name - description: Use a grey background for the name and type line on hybrid cards. This is done on real cards. -styling field: - type: boolean - name: colored multicolor land name - description: Use a colored background for the name and type on multicolor land cards with a basic land type. This is done on real cards. -styling field: - type: boolean - name: use guild mana symbols - description: Use the Ravnica guild symbols instead of the official half/half circles for hybrid mana. - initial: no -styling field: - type: choice - name: tap symbol - description: What tap and untap symbols should be used on cards? - initial: modern - choice: modern - choice: old - choice: diagonal T -styling field: - type: package choice - name: text box mana symbols - match: magic-mana-*.mse-symbol-font - initial: magic-mana-small.mse-symbol-font -styling field: - type: choice - name: center text - description: When to center text (short text only means only on one-line cards with no flavor text) - choice: always - choice: short text only - choice: never - initial: never -styling field: - type: boolean - name: inverted common symbol - description: Should the common rarity symbol be inverted, like in Coldsnap? - initial: no -styling field: - type: choice - name: image size - description: Should the art extend into a transparent textbox? - initial: standard - choice: standard - choice: extended -styling style: - artifact style: - render style: both - choice images: - dark: dacard.jpg - brown: dbacard.jpg - saturated multicolor: - choice images: - yes: dmcard.jpg - no: domcard.jpg - use guild mana symbols: - choice images: - yes: /magic-mana-small.mse-symbol-font/mana_guild_rg.png - no: /magic-mana-small.mse-symbol-font/mana_rg.png - tap symbol: - render style: both - choice images: - modern: /magic-mana-large.mse-symbol-font/mana_t.png - old: /magic-mana-large.mse-symbol-font/mana_t_old.png - diagonal T: /magic-mana-large.mse-symbol-font/mana_t_older.png - center text: - render style: both - choice images: - always: /magic.mse-game/icons/center-all-text.png - short text only: /magic.mse-game/icons/center-short-text.png - never: /magic.mse-game/icons/center-no-text.png - inverted common symbol: - choice images: - no: { symbol_variation(symbol: set.symbol, variation: "common") } - yes: { symbol_variation(symbol: set.symbol, variation: "invertedcommon") } - image size: - render style: both - choice images: - standard: /magic.mse-game/icons/small-image.png - extended: /magic.mse-game/icons/large-image.png - -############################################################## Card fields -card style: - ############################# Background stuff - border color: - left: 0 - top : 0 - width: 375 - height: 523 - radius: 18 - left width: 17 - right width: 17 - top width: 17 - bottom width: 18 - #mask: border-mask.png - z index: -1 - card color: - left: 0 - top: 0 - width: { if is_day() then 375 else 0 } - height: 523 - z index: -2 - render style: image - popup style: in place - image: { card_background() } - visible: { is_day() } - - ############################# Name line - name: - left: { if card.card_symbol=="none" then 60 else 76 } - top : 30 - right: { if has_no_cost() then 341 else (341 - card_style.casting_cost.content_width) } - height: { if is_day() then 23 else 0 } - alignment: bottom shrink-overflow - padding bottom: 0 - z index: 1 - font: - name: Matrix - size: 17 - weight: bold - color: { if is_day() then rgb(0,0,0) else rgb(255,255,255) } - visible: { is_day() } - casting cost: - right: 343 - top : 31 - width: { max(30, card_style.casting_cost.content_width) + 5 } - height: { if is_day() then 23 else 0 } - alignment: middle right - font: - name: MPlantin - size: 15 - symbol font: - name: magic-mana-large - size: 15 - alignment: middle right - always symbol: true - z index: 2 - padding top: 0 - visible: { is_day() } - card symbol: - left: {if card.card_symbol=="none" then 55 else 60} - top : 31 - height: 20 - width: { if is_day() then 14 else 0 } - render style: image - choice images: - tombstone: tombstone.png - visible: { is_day() } - transformation: - left: 21 - top : 26 - height: 31 - width: 31 - render style: image - choice images: - day: sun_circle.png - night: night_circle.png - - ############################# Image - image: - left: 32 - top: 62 - width: { if is_day() then 311 else 0 } - height: { if styling.image_size == "extended" then 408 else 228 } - z index: 1 - mask: - script: if styling.image_size == "extended" then "imagemask_extended.png" else "imagemask_standard.png" - default: {default_image(card.card_color)} - visible: { is_day() } - - ############################# Card type - type: - left: { if contains(card.card_color, match:"land") then 35 else (if styling.color_identity=="always" then 55 else if (styling.color_identity=="sometimes" and has_no_cost()) then 55 else 35) } - top : 298 - width: { if contains(card.card_color, match:"land") then (308 - max(22,card_style.rarity.content_width)) else (if styling.color_identity=="always" then (288 - max(22,card_style.rarity.content_width)) else if (styling.color_identity=="sometimes" and has_no_cost()) then (288 - max(22,card_style.rarity.content_width)) else (308 - max(22,card_style.rarity.content_width))) } - height: { if is_day() then 20 else 0 } - alignment: top shrink-overflow - z index: 2 - padding top: 2 - font: - name: Matrix - size: 14 - color: { if is_day() then rgb(0,0,0) else rgb(255,255,255) } - separator color: rgb(128,128,128) - visible: { is_day() } - - rarity: - right: 342 - top : 297 - width: 44 - height: 22 - z index: 1 - render style: image - alignment: middle right - choice images: - # Images based on the set symbol - basic land: - script: - if styling.inverted_common_symbol then symbol_variation(symbol: set.symbol, variation: "invertedcommon") - else symbol_variation(symbol: set.symbol, variation: "common") - common: - script: - if styling.inverted_common_symbol then symbol_variation(symbol: set.symbol, variation: "invertedcommon") - else symbol_variation(symbol: set.symbol, variation: "common") - uncommon: script: symbol_variation(symbol: set.symbol, variation: "uncommon") - rare: script: symbol_variation(symbol: set.symbol, variation: "rare") - mythic rare: script: symbol_variation(symbol: set.symbol, variation: "mythic rare") - special: script: symbol_variation(symbol: set.symbol, variation: "special") - - identity: - left: 41 - top : 297 - width: { if contains(card.card_color, match:"land") then 0 else (if styling.color_identity=="always" then 17 else if (styling.color_identity=="sometimes" and has_no_cost()) then 17 else 0) } - height: 17 - angle: -45 - z index: 2 - render style: image - image: { card_identity() } - mask: /magic-new-common.mse-include/dmulticolor_blend_identity.png - visible: { styling.color_identity=="always" or (styling.color_identity=="sometimes" and has_no_cost()) or (has_no_cost() and is_day()) } - - idframe: - left: 34 - top : 301 - width: { if contains(card.card_color, match:"land") then 0 else (if styling.color_identity=="always" then 17 else if (styling.color_identity=="sometimes" and has_no_cost()) then 17 else 0) } - height: 17 - z index: 1 - render style: image - choice images: - frame: /magic-new-common.mse-include/cidentity.png - mask: /magic-new-common.mse-include/inverse_blend_identity.png - visible: { styling.color_identity=="always" or (styling.color_identity=="sometimes" and has_no_cost()) or (has_no_cost() and is_day()) } - - ############################# Text box - text: - left: 31 - top : 328 - width: { if is_day() then 311 else 0 } - height: 142 - font: - name: MPlantin - italic name: MPlantin-Italic - size: 14 - scale down to: 6 - color: rgb(0,0,0) - symbol font: - name: { styling.text_box_mana_symbols } - size: 14 - alignment: - script: - if (styling.center_text == "short text only" and - not contains(match:"\n", card.rule_text) and - card.flavor_text == "" and - card_style.text.content_lines <= 2) or - styling.center_text == "always" - then "middle center" - else "middle left" - z index: 2 - padding left: 6 -# padding top: 2 - padding right: 4 -# padding bottom: 2 - line height hard: 1.2 - line height line: 1.5 - line height soft: 0.9 - line height hard max: 1.3 - line height line max: 1.6 - visible: { is_day() } - - watermark: - left: 117 - top : 321 - width: { if is_day() then 138 else 0 } - height: 156 - z index: 1 - render style: image - alignment: middle center - include file: /magic-watermarks.mse-include/watermarks - visible: { is_day() } - - ############################# PT - pt: - z index: 4 - left: 284 - top: 466 - width: { if is_day() then 60 else 0 } - height: 28 - alignment: center middle shrink-overflow - font: - name: ModMatrix - size: 17 - weight: bold - color: { if is_day() then rgb(0,0,0) else rgb(255,255,255) } - separator color: rgb(200,0,0) - visible: { is_day() } - - ############################# Card sorting / numbering - ############################# Copyright stuff - - illustrator: - left: 56 - top : 478 - width: { if is_day() then 217 else 0 } - height: 16 - z index: 1 - font: - name: Matrix - size: 10 - weight: bold - color: { font_color(card.card_color) } - visible: { is_day() } - - ############################# Day side extra - pt 3: - z index: 4 - left: 311 - top: 451 - width: { if is_day() then 30 else 0 } - height: 12 - alignment: bottom right - font: - name: ModMatrix - size: 12 - weight: bold - color: rgb(35,35,35) - separator color: rgb(200,0,0) - visible: { is_day() } - - ############################# Night side - ############################# Background stuff - card color 2: - left: 0 - top: 0 - width: { if is_night() then 375 else 0 } - height: 523 - z index: -2 - render style: image - popup style: in place - image: { card_background() } - visible: { is_night() } - - ############################# Name line - name 2: - left: { if card.card_symbol=="none" then 60 else 76 } - top : 30 - right: { if has_no_cost() then 341 else (341 - card_style.casting_cost.content_width) } - height: { if is_night() then 23 else 0 } - alignment: bottom shrink-overflow - padding bottom: 0 - z index: 1 - font: - name: Matrix - size: 17 - weight: bold - color: rgb(255,255,255) - visible: { is_night() } - casting cost 2: - right: 343 - top : 31 - width: { max(30, card_style.casting_cost.content_width) + 5 } - height: { if is_night() then 23 else 0 } - alignment: middle right - font: - name: MPlantin - size: 15 - symbol font: - name: magic-mana-large - size: 15 - alignment: middle right - always symbol: true - z index: 2 - padding top: 0 - visible: { is_night() } - card symbol 2: - left: {if card.card_symbol=="none" then 55 else 60} - top : 31 - height: 20 - width: { if is_night() then 14 else 0 } - render style: image - choice images: - tombstone: tombstone.png - visible: { is_night() } - - ############################# Image - image 2: - left: 32 - top: 62 - width: { if is_night() then 311 else 0 } - height: { if styling.image_size == "extended" then 408 else 228 } - z index: 1 - mask: - script: if styling.image_size == "extended" then "imagemask_extended.png" else "imagemask_standard.png" - default: {default_image(card.card_color)} - visible: { is_night() } - - ############################# Card type - type 2: - left: { if has_no_cost() then 55 else 35 } - top : 298 - width: { if has_no_cost() then (288 - max(22,card_style.rarity.content_width)) else (308 - max(22,card_style.rarity.content_width)) } - height: { if is_night() then 20 else 0 } - alignment: top shrink-overflow - z index: 2 - padding top: 2 - font: - name: Matrix - size: 14 - color: rgb(255,255,255) - separator color: rgb(128,128,128) - visible: { is_night() } - - identity 2: - left: 41 - top : 297 - width: { if (contains(card.card_color, match:"land") or is_day()) then 0 else (if styling.color_identity=="always" then 17 else if (styling.color_identity=="sometimes" and has_no_cost()) then 17 else 0) } - height: 17 - angle: -45 - z index: 2 - render style: image - image: { card_identity() } - mask: /magic-new-common.mse-include/dmulticolor_blend_identity.png - visible: { styling.color_identity=="always" or (styling.color_identity=="sometimes" and has_no_cost()) or (has_no_cost() and is_night()) } - - idframe 2: - left: 34 - top : 301 - width: { if (contains(card.card_color, match:"land") or is_day()) then 0 else (if styling.color_identity=="always" then 17 else if (styling.color_identity=="sometimes" and has_no_cost()) then 17 else 0) } - height: 17 - z index: 1 - render style: image - choice images: - frame: /magic-new-common.mse-include/cidentity.png - mask: /magic-new-common.mse-include/inverse_blend_identity.png - visible: { styling.color_identity=="always" or (styling.color_identity=="sometimes" and has_no_cost()) or (has_no_cost() and is_night()) } - - ############################# Text box - text 2: - left: 31 - top : 328 - width: { if is_night() then 311 else 0 } - height: 142 - font: - name: MPlantin - italic name: MPlantin-Italic - size: 14 - scale down to: 6 - color: rgb(0,0,0) - symbol font: - name: { styling.text_box_mana_symbols } - size: 14 - alignment: - script: - if (styling.center_text == "short text only" and - not contains(match:"\n", card.rule_text) and - card.flavor_text == "" and - card_style.text.content_lines <= 2) or - styling.center_text == "always" - then "middle center" - else "middle left" - z index: 2 - padding left: 6 -# padding top: 2 - padding right: 4 -# padding bottom: 2 - line height hard: 1.2 - line height line: 1.5 - line height soft: 0.9 - line height hard max: 1.3 - line height line max: 1.6 - visible: { is_night() } - - watermark 2: - left: 117 - top : 321 - width: { if is_night() then 138 else 0 } - height: 156 - z index: 1 - render style: image - alignment: middle center - include file: /magic-watermarks.mse-include/watermarks - visible: { is_night() } - - ############################# PT - pt 2: - z index: 4 - left: 284 - top: 466 - width: { if is_night() then 60 else 0 } - height: 28 - alignment: center middle shrink-overflow - font: - name: ModMatrix - size: 17 - weight: bold - color: { if is_day() then rgb(0,0,0) else rgb(255,255,255) } - separator color: rgb(200,0,0) - visible: { is_night() } - - ############################# Card sorting / numbering - ############################# Copyright stuff - - illustrator 2: - left: 56 - top : 478 - width: { if is_night() then 217 else 0 } - height: 16 - z index: 1 - font: - name: Matrix - size: 10 - weight: bold - color: { font_color(card.card_color_2) } - visible: { is_night() } - - -############################################################## Extra card fields - -extra card field: - type: choice - name: pt box - script: card.card_color - editable: false -extra card field: - type: choice - name: pt box 2 - script: card.card_color_2 - editable: false -extra card field: - type: text - name: copyright line a - save value: false - show statistics: false - script: - if set.automatic_card_numbers then - combined_editor(field1: card.copyright, separator: " ", field2: card.card_number_a_or_b) - else - forward_editor(field: card.copyright) - description: Copyright of this card and cardnumber, the default value can be changed on the 'set info' tab -extra card field: - type: text - name: copyright line b - save value: false - show statistics: false - script: - if set.automatic_card_numbers then - combined_editor(field1: card.copyright, separator: " ", field2: card.card_number_a_or_b) - else - forward_editor(field: card.copyright) - description: Copyright of this card and cardnumber, the default value can be changed on the 'set info' tab -extra card style: - pt box: - left: 271 - top: 461 - width: { if is_day() then 81 else 0 } - height: 42 - z index: 1 - mask: ptmask.png - visible: { card.pt != "" and is_day() } - render style: image - image: { card_ptbox() } - pt box 2: - left: 271 - top: 461 - width: { if is_night() then 81 else 0 } - height: 42 - z index: 1 - mask: ptmask.png - visible: { card.pt_2 != "" and is_night() } - render style: image - image: { card_ptbox() } - copyright line a: - left: 30 - top : 493 - width: { if is_day() then 247 else 0 } - height: 12 - z index: 1 - font: - name: MPlantin - size: 6.5 - color: { font_color(card.card_color) } - visible: { is_day() } - copyright line b: - left: 30 - top : 493 - width: {if is_night() then 247 else 0 } - height: 12 - z index: 1 - font: - name: MPlantin - size: 6.5 - color: { font_color(card.card_color_2) } +mse version: 2.0.0 +game: magic +short name: Modern Transformer +full name: Innistrad Transformers +icon: card-sample.png +position hint: 002 +installer group: magic/new style/transformer + +version: 2011-09-15 +depends on: magic.mse-game 2011-09-10 +depends on: magic-new-common.mse-include 2011-09-11 +depends on: magic-default-image.mse-include 2007-09-23 +depends on: magic-watermarks.mse-include 2007-09-23 +depends on: magic-mana-large.mse-symbol-font 2011-04-10 +depends on: magic-mana-small.mse-symbol-font 2011-04-10 + +card background: white +card width: 375 +card height: 523 +card dpi: 150 + +############################################################## Extra scripts + +init script: + # Load scripts for image box + include file: /magic-default-image.mse-include/scripts + + # Should hybrids have a grey name? + mask_hybrid_with_land := { styling.grey_hybrid_name } + + #Should multicolor lands with basic land types have a colored name? + mask_multi_land_with_color := { styling.colored_multicolor_land_name } + + # Which artifact template should be used? + alternate_template := { + if input == "a" then ( + if styling.artifact_style == "brown" then "ba" + else "a" + ) else if input == "m" then ( + if styling.saturated_multicolor then "m" + else "om" + ) else input + } + template := { (if type=="identity" then "/magic-new-common.mse-include/" else (if is_night() then "n" else "d")) + alternate_template() + "{type}." + (if type=="identity" then "png" else "jpg") } + land_template := { (if type=="identity" then "/magic-new-common.mse-include/" else (if is_night() then "n" else "d")) + (if input == "a" then "c" else alternate_template()) + (if type=="identity" then "" else "l") + "{type}." +(if type=="identity" then "png" else "jpg") } + # Use land templates for previews because they show more contrast + hybrid_previews := "land,hybrid" + + # Use the normal tap symbol + mana_t := { + if styling.tap_symbol == "old" then "old" + else if styling.tap_symbol == "diagonal T" then "older" + else "new" + } + + # Use guild mana symbols? + guild_mana := { styling.use_guild_mana_symbols } + + # Replacing the section of the blends file relevant to masking due to day and night having different masks + color_combination := { + # The base hybrid, without the outer frame blended over it + base := base_hybrid[shape][color_count]() + + # Put a frame around it? + if land and not colored_lands then + masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "multicolor_blend_{type}.png", + dark: land_template("c"), + light: base, + ) + else if land and multi and mask_multi_land_with_color() then + masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + "hybrid_blend_{type}.png", + dark: base, + light: land_template("m"), + ) + else if multi and artifact then + masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "artifact_blend_{type}.png", + dark: template("a"), + light: masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "multicolor_blend_{type}.png", + dark: template("m"), + light: base + ) + ) + else if multi then + masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "multicolor_blend_{type}.png", + dark: template("m"), + light: base, + ) + else if artifact and color_count > 1 and mask_hybrid_with_land() then + masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "artifact_blend_{type}.png", + dark: template("a"), + light: masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "multicolor_blend_{type}.png", + dark: template("c"), + light: base + ) + ) + else if artifact then + masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + (if type=="pt" then "" else (if has_no_cost() then "n" else "d")) + "artifact_blend_{type}.png", + dark: template("a"), + light: base, + ) + else if color_count > 1 and mask_hybrid_with_land() then + masked_blend( + mask: (if type=="identity" then "/magic-new-common.mse-include/" else "") + "hybrid_blend_{type}.png", + dark: land_template("c"), + light: base, + ) + else base + } + +############################################################## Set info fields +set info style: + symbol: + variation: + name: invertedcommon + border radius: 0.10 + fill type: solid + fill color: rgb(255,255,255) + border color: rgb(0,0,0) + +############################################################## Extra style options + +styling field: + type: choice + name: color identity + choice: always + choice: sometimes + choice: never + description: Do you want to always, sometimes, or never use color indicators? + initial: sometimes +styling field: + type: choice + name: artifact style + description: Choose the style of artifacts: light = before Fifth Dawn, dark = used since Fifth Dawn, brown = old rust style. + initial: dark + choice: dark + choice: brown +styling field: + type: boolean + name: saturated multicolor + description: Should multicolor cards be more saturated? This is done on real cards. + initial: yes +styling field: + type: boolean + name: grey hybrid name + description: Use a grey background for the name and type line on hybrid cards. This is done on real cards. +styling field: + type: boolean + name: colored multicolor land name + description: Use a colored background for the name and type on multicolor land cards with a basic land type. This is done on real cards. +styling field: + type: boolean + name: use guild mana symbols + description: Use the Ravnica guild symbols instead of the official half/half circles for hybrid mana. + initial: no +styling field: + type: choice + name: tap symbol + description: What tap and untap symbols should be used on cards? + initial: modern + choice: modern + choice: old + choice: diagonal T +styling field: + type: package choice + name: text box mana symbols + match: magic-mana-*.mse-symbol-font + initial: magic-mana-small.mse-symbol-font +styling field: + type: choice + name: center text + description: When to center text (short text only means only on one-line cards with no flavor text) + choice: always + choice: short text only + choice: never + initial: never +styling field: + type: boolean + name: inverted common symbol + description: Should the common rarity symbol be inverted, like in Coldsnap? + initial: no +styling field: + type: choice + name: image size + description: Should the art extend into a transparent textbox? + initial: standard + choice: standard + choice: extended +styling style: + artifact style: + render style: both + choice images: + dark: dacard.jpg + brown: dbacard.jpg + saturated multicolor: + choice images: + yes: dmcard.jpg + no: domcard.jpg + use guild mana symbols: + choice images: + yes: /magic-mana-small.mse-symbol-font/mana_guild_rg.png + no: /magic-mana-small.mse-symbol-font/mana_rg.png + tap symbol: + render style: both + choice images: + modern: /magic-mana-large.mse-symbol-font/mana_t.png + old: /magic-mana-large.mse-symbol-font/mana_t_old.png + diagonal T: /magic-mana-large.mse-symbol-font/mana_t_older.png + center text: + render style: both + choice images: + always: /magic.mse-game/icons/center-all-text.png + short text only: /magic.mse-game/icons/center-short-text.png + never: /magic.mse-game/icons/center-no-text.png + inverted common symbol: + choice images: + no: { symbol_variation(symbol: set.symbol, variation: "common") } + yes: { symbol_variation(symbol: set.symbol, variation: "invertedcommon") } + image size: + render style: both + choice images: + standard: /magic.mse-game/icons/small-image.png + extended: /magic.mse-game/icons/large-image.png + +############################################################## Card fields +card style: + ############################# Background stuff + border color: + left: 0 + top : 0 + width: 375 + height: 523 + radius: 18 + left width: 17 + right width: 17 + top width: 17 + bottom width: 18 + #mask: border-mask.png + z index: -1 + card color: + left: 0 + top: 0 + width: { if is_day() then 375 else 0 } + height: 523 + z index: -2 + render style: image + popup style: in place + image: { card_background() } + visible: { is_day() } + + ############################# Name line + name: + left: { if card.card_symbol=="none" then 60 else 76 } + top : 30 + right: { if has_no_cost() then 341 else (341 - card_style.casting_cost.content_width) } + height: { if is_day() then 23 else 0 } + alignment: bottom shrink-overflow + padding bottom: 0 + z index: 1 + font: + name: Matrix + size: 17 + weight: bold + color: { if is_day() then rgb(0,0,0) else rgb(255,255,255) } + visible: { is_day() } + casting cost: + right: 343 + top : 31 + width: { max(30, card_style.casting_cost.content_width) + 5 } + height: { if is_day() then 23 else 0 } + alignment: middle right + font: + name: MPlantin + size: 15 + symbol font: + name: magic-mana-large + size: 15 + alignment: middle right + always symbol: true + z index: 2 + padding top: 0 + visible: { is_day() } + card symbol: + left: {if card.card_symbol=="none" then 55 else 60} + top : 31 + height: 20 + width: { if is_day() then 14 else 0 } + render style: image + choice images: + tombstone: tombstone.png + visible: { is_day() } + transformation: + left: 21 + top : 26 + height: 31 + width: 31 + render style: image + choice images: + day: sun_circle.png + night: night_circle.png + + ############################# Image + image: + left: 32 + top: 62 + width: { if is_day() then 311 else 0 } + height: { if styling.image_size == "extended" then 408 else 228 } + z index: 1 + mask: + script: if styling.image_size == "extended" then "imagemask_extended.png" else "imagemask_standard.png" + default: {default_image(card.card_color)} + visible: { is_day() } + + ############################# Card type + type: + left: { if contains(card.card_color, match:"land") then 35 else (if styling.color_identity=="always" then 55 else if (styling.color_identity=="sometimes" and has_no_cost()) then 55 else 35) } + top : 298 + width: { if contains(card.card_color, match:"land") then (308 - max(22,card_style.rarity.content_width)) else (if styling.color_identity=="always" then (288 - max(22,card_style.rarity.content_width)) else if (styling.color_identity=="sometimes" and has_no_cost()) then (288 - max(22,card_style.rarity.content_width)) else (308 - max(22,card_style.rarity.content_width))) } + height: { if is_day() then 20 else 0 } + alignment: top shrink-overflow + z index: 2 + padding top: 2 + font: + name: Matrix + size: 14 + color: { if is_day() then rgb(0,0,0) else rgb(255,255,255) } + separator color: rgb(128,128,128) + visible: { is_day() } + + rarity: + right: 342 + top : 297 + width: 44 + height: 22 + z index: 1 + render style: image + alignment: middle right + choice images: + # Images based on the set symbol + basic land: + script: + if styling.inverted_common_symbol then symbol_variation(symbol: set.symbol, variation: "invertedcommon") + else symbol_variation(symbol: set.symbol, variation: "common") + common: + script: + if styling.inverted_common_symbol then symbol_variation(symbol: set.symbol, variation: "invertedcommon") + else symbol_variation(symbol: set.symbol, variation: "common") + uncommon: script: symbol_variation(symbol: set.symbol, variation: "uncommon") + rare: script: symbol_variation(symbol: set.symbol, variation: "rare") + mythic rare: script: symbol_variation(symbol: set.symbol, variation: "mythic rare") + special: script: symbol_variation(symbol: set.symbol, variation: "special") + + identity: + left: 41 + top : 297 + width: { if contains(card.card_color, match:"land") then 0 else (if styling.color_identity=="always" then 17 else if (styling.color_identity=="sometimes" and has_no_cost()) then 17 else 0) } + height: 17 + angle: -45 + z index: 2 + render style: image + image: { card_identity() } + mask: /magic-new-common.mse-include/dmulticolor_blend_identity.png + visible: { styling.color_identity=="always" or (styling.color_identity=="sometimes" and has_no_cost()) or (has_no_cost() and is_day()) } + + idframe: + left: 34 + top : 301 + width: { if contains(card.card_color, match:"land") then 0 else (if styling.color_identity=="always" then 17 else if (styling.color_identity=="sometimes" and has_no_cost()) then 17 else 0) } + height: 17 + z index: 1 + render style: image + choice images: + frame: /magic-new-common.mse-include/cidentity.png + mask: /magic-new-common.mse-include/inverse_blend_identity.png + visible: { styling.color_identity=="always" or (styling.color_identity=="sometimes" and has_no_cost()) or (has_no_cost() and is_day()) } + + ############################# Text box + text: + left: 31 + top : 328 + width: { if is_day() then 311 else 0 } + height: 142 + font: + name: MPlantin + italic name: MPlantin-Italic + size: 14 + scale down to: 6 + color: rgb(0,0,0) + symbol font: + name: { styling.text_box_mana_symbols } + size: 14 + alignment: + script: + if (styling.center_text == "short text only" and + not contains(match:"\n", card.rule_text) and + card.flavor_text == "" and + card_style.text.content_lines <= 2) or + styling.center_text == "always" + then "middle center" + else "middle left" + z index: 2 + padding left: 6 +# padding top: 2 + padding right: 4 +# padding bottom: 2 + line height hard: 1.2 + line height line: 1.5 + line height soft: 0.9 + line height hard max: 1.3 + line height line max: 1.6 + visible: { is_day() } + + watermark: + left: 117 + top : 321 + width: { if is_day() then 138 else 0 } + height: 156 + z index: 1 + render style: image + alignment: middle center + include file: /magic-watermarks.mse-include/watermarks + visible: { is_day() } + + ############################# PT + pt: + z index: 4 + left: 284 + top: 466 + width: { if is_day() then 60 else 0 } + height: 28 + alignment: center middle shrink-overflow + font: + name: ModMatrix + size: 17 + weight: bold + color: { if is_day() then rgb(0,0,0) else rgb(255,255,255) } + separator color: rgb(200,0,0) + visible: { is_day() } + + ############################# Card sorting / numbering + ############################# Copyright stuff + + illustrator: + left: 56 + top : 478 + width: { if is_day() then 217 else 0 } + height: 16 + z index: 1 + font: + name: Matrix + size: 10 + weight: bold + color: { font_color(card.card_color) } + visible: { is_day() } + + ############################# Day side extra + pt 3: + z index: 4 + left: 311 + top: 451 + width: { if is_day() then 30 else 0 } + height: 12 + alignment: bottom right + font: + name: ModMatrix + size: 12 + weight: bold + color: rgb(35,35,35) + separator color: rgb(200,0,0) + visible: { is_day() } + + ############################# Night side + ############################# Background stuff + card color 2: + left: 0 + top: 0 + width: { if is_night() then 375 else 0 } + height: 523 + z index: -2 + render style: image + popup style: in place + image: { card_background() } + visible: { is_night() } + + ############################# Name line + name 2: + left: { if card.card_symbol=="none" then 60 else 76 } + top : 30 + right: { if has_no_cost() then 341 else (341 - card_style.casting_cost.content_width) } + height: { if is_night() then 23 else 0 } + alignment: bottom shrink-overflow + padding bottom: 0 + z index: 1 + font: + name: Matrix + size: 17 + weight: bold + color: rgb(255,255,255) + visible: { is_night() } + casting cost 2: + right: 343 + top : 31 + width: { max(30, card_style.casting_cost.content_width) + 5 } + height: { if is_night() then 23 else 0 } + alignment: middle right + font: + name: MPlantin + size: 15 + symbol font: + name: magic-mana-large + size: 15 + alignment: middle right + always symbol: true + z index: 2 + padding top: 0 + visible: { is_night() } + card symbol 2: + left: {if card.card_symbol=="none" then 55 else 60} + top : 31 + height: 20 + width: { if is_night() then 14 else 0 } + render style: image + choice images: + tombstone: tombstone.png + visible: { is_night() } + + ############################# Image + image 2: + left: 32 + top: 62 + width: { if is_night() then 311 else 0 } + height: { if styling.image_size == "extended" then 408 else 228 } + z index: 1 + mask: + script: if styling.image_size == "extended" then "imagemask_extended.png" else "imagemask_standard.png" + default: {default_image(card.card_color)} + visible: { is_night() } + + ############################# Card type + type 2: + left: { if has_no_cost() then 55 else 35 } + top : 298 + width: { if has_no_cost() then (288 - max(22,card_style.rarity.content_width)) else (308 - max(22,card_style.rarity.content_width)) } + height: { if is_night() then 20 else 0 } + alignment: top shrink-overflow + z index: 2 + padding top: 2 + font: + name: Matrix + size: 14 + color: rgb(255,255,255) + separator color: rgb(128,128,128) + visible: { is_night() } + + identity 2: + left: 41 + top : 297 + width: { if (contains(card.card_color, match:"land") or is_day()) then 0 else (if styling.color_identity=="always" then 17 else if (styling.color_identity=="sometimes" and has_no_cost()) then 17 else 0) } + height: 17 + angle: -45 + z index: 2 + render style: image + image: { card_identity() } + mask: /magic-new-common.mse-include/dmulticolor_blend_identity.png + visible: { styling.color_identity=="always" or (styling.color_identity=="sometimes" and has_no_cost()) or (has_no_cost() and is_night()) } + + idframe 2: + left: 34 + top : 301 + width: { if (contains(card.card_color, match:"land") or is_day()) then 0 else (if styling.color_identity=="always" then 17 else if (styling.color_identity=="sometimes" and has_no_cost()) then 17 else 0) } + height: 17 + z index: 1 + render style: image + choice images: + frame: /magic-new-common.mse-include/cidentity.png + mask: /magic-new-common.mse-include/inverse_blend_identity.png + visible: { styling.color_identity=="always" or (styling.color_identity=="sometimes" and has_no_cost()) or (has_no_cost() and is_night()) } + + ############################# Text box + text 2: + left: 31 + top : 328 + width: { if is_night() then 311 else 0 } + height: 142 + font: + name: MPlantin + italic name: MPlantin-Italic + size: 14 + scale down to: 6 + color: rgb(0,0,0) + symbol font: + name: { styling.text_box_mana_symbols } + size: 14 + alignment: + script: + if (styling.center_text == "short text only" and + not contains(match:"\n", card.rule_text) and + card.flavor_text == "" and + card_style.text.content_lines <= 2) or + styling.center_text == "always" + then "middle center" + else "middle left" + z index: 2 + padding left: 6 +# padding top: 2 + padding right: 4 +# padding bottom: 2 + line height hard: 1.2 + line height line: 1.5 + line height soft: 0.9 + line height hard max: 1.3 + line height line max: 1.6 + visible: { is_night() } + + watermark 2: + left: 117 + top : 321 + width: { if is_night() then 138 else 0 } + height: 156 + z index: 1 + render style: image + alignment: middle center + include file: /magic-watermarks.mse-include/watermarks + visible: { is_night() } + + ############################# PT + pt 2: + z index: 4 + left: 284 + top: 466 + width: { if is_night() then 60 else 0 } + height: 28 + alignment: center middle shrink-overflow + font: + name: ModMatrix + size: 17 + weight: bold + color: { if is_day() then rgb(0,0,0) else rgb(255,255,255) } + separator color: rgb(200,0,0) + visible: { is_night() } + + ############################# Card sorting / numbering + ############################# Copyright stuff + + illustrator 2: + left: 56 + top : 478 + width: { if is_night() then 217 else 0 } + height: 16 + z index: 1 + font: + name: Matrix + size: 10 + weight: bold + color: { font_color(card.card_color_2) } + visible: { is_night() } + + +############################################################## Extra card fields + +extra card field: + type: choice + name: pt box + script: card.card_color + editable: false +extra card field: + type: choice + name: pt box 2 + script: card.card_color_2 + editable: false +extra card field: + type: text + name: copyright line a + save value: false + show statistics: false + script: + if set.automatic_card_numbers then + combined_editor(field1: card.copyright, separator: " ", field2: card.card_number_a_or_b) + else + forward_editor(field: card.copyright) + description: Copyright of this card and cardnumber, the default value can be changed on the 'set info' tab +extra card field: + type: text + name: copyright line b + save value: false + show statistics: false + script: + if set.automatic_card_numbers then + combined_editor(field1: card.copyright, separator: " ", field2: card.card_number_a_or_b) + else + forward_editor(field: card.copyright) + description: Copyright of this card and cardnumber, the default value can be changed on the 'set info' tab +extra card style: + pt box: + left: 271 + top: 461 + width: { if is_day() then 81 else 0 } + height: 42 + z index: 1 + mask: ptmask.png + visible: { card.pt != "" and is_day() } + render style: image + image: { card_ptbox() } + pt box 2: + left: 271 + top: 461 + width: { if is_night() then 81 else 0 } + height: 42 + z index: 1 + mask: ptmask.png + visible: { card.pt_2 != "" and is_night() } + render style: image + image: { card_ptbox() } + copyright line a: + left: 30 + top : 493 + width: { if is_day() then 247 else 0 } + height: 12 + z index: 1 + font: + name: MPlantin + size: 6.5 + color: { font_color(card.card_color) } + visible: { is_day() } + copyright line b: + left: 30 + top : 493 + width: {if is_night() then 247 else 0 } + height: 12 + z index: 1 + font: + name: MPlantin + size: 6.5 + color: { font_color(card.card_color_2) } visible: { is_night() } \ No newline at end of file diff --git a/data/magic.mse-game/unit_tests b/data/magic.mse-game/unit_tests index eb19db8f..af273fcb 100644 --- a/data/magic.mse-game/unit_tests +++ b/data/magic.mse-game/unit_tests @@ -1,27 +1,27 @@ -# This script contains tests of the functions defined in other script files. -# These are not used during normal execution, they are only used for development. -# When everything is right, all these tests pass. - -############################################################## -# card_color_color_count -############################################################## - -assert(card_color_color_count("") == 0) -assert(card_color_color_count("asdf") == 0) -assert(card_color_color_count("white") == 1) -assert(card_color_color_count("artifact,white") == 2) - -############################################################## -# converted mana cost -############################################################## - -assert(cmc("") == 0) -assert(cmc("0") == 0) -assert(cmc("1/2") == 0.5) -assert(cmc("2/R3/W") == 5) -assert(cmc("W/UW") == 2) -assert(cmc("RRR") == 3) -assert(cmc("2X") == 2) -assert(cmc("22") == 22) -assert(cmc("20WUBRG") == 25) - +# This script contains tests of the functions defined in other script files. +# These are not used during normal execution, they are only used for development. +# When everything is right, all these tests pass. + +############################################################## +# card_color_color_count +############################################################## + +assert(card_color_color_count("") == 0) +assert(card_color_color_count("asdf") == 0) +assert(card_color_color_count("white") == 1) +assert(card_color_color_count("artifact,white") == 2) + +############################################################## +# converted mana cost +############################################################## + +assert(cmc("") == 0) +assert(cmc("0") == 0) +assert(cmc("1/2") == 0.5) +assert(cmc("2/R3/W") == 5) +assert(cmc("W/UW") == 2) +assert(cmc("RRR") == 3) +assert(cmc("2X") == 2) +assert(cmc("22") == 22) +assert(cmc("20WUBRG") == 25) + diff --git a/data/magic.mse-game/word_lists_fr b/data/magic.mse-game/word_lists_fr index 9b260981..935a6d63 100644 --- a/data/magic.mse-game/word_lists_fr +++ b/data/magic.mse-game/word_lists_fr @@ -1,412 +1,412 @@ - -############################################################## Magic word lists - -word list: - name: type - word: - name: de base - is prefix: true - word: - name: légendaire - is prefix: true - word: - name: tribaux - is prefix: true - word: - name: de neige - is prefix: true - word: - name: monde - is prefix: true - line below: true - word: Créature - word: Artefact - word: Artefact Créature - word: Enchantement - word: Instant - word: Rituel - word: Terrain - word: Planeswalker - -word list: - name: race - word: - script: all_races() - line below: true - word: Angel - word: Beast - word: Bird - word: Construct - word: Demon - word: Dragon - word: Drake - word: Elemental - word: Elf - word: Faerie - word: Giant - word: Goblin - word: Golem - word: Human - word: Illusion - word: Merfolk - word: Treefolk - word: Zombie - word: - name: All Races - word: - name: A - word: Angel - word: Anteater - word: Antelope - word: Ape - word: Archon - word: Assembly-Worker - word: Atog - word: Aurochs - word: Avatar - word: - name: B - word: Badger - word: Basilisk - word: Bat - word: Bear - word: Beast - word: Beeble - word: Bird - word: Blinkmoth - word: Boar - word: Bringer - word: Brushwagg - word: - name: C - word: Camarid - word: Camel - word: Caribou - word: Cat - word: Centaur - word: Cephalid - word: Chimera - word: Cockatrice - word: Construct - word: Crab - word: Crocodile - word: Cyclops - word: - name: D - word: Dauthi - word: Demon - word: Devil - word: Djinn - word: Dragon - word: Drake - word: Dreadnought - word: Dryad - word: Dwarf - word: - name: E - word: Efreet - word: Egg - word: Elemental - word: Elephant - word: Elf - word: Elk - word: Eye - word: - name: F - word: Faerie - word: Ferret - word: Fish - word: Fox - word: Frog - word: Fungus - word: - name: G - word: Gargoyle - word: Giant - word: Gnome - word: Goat - word: Goblin - word: Golem - word: Gorgon - word: Graveborn - word: Griffin - word: - name: H - word: Hag - word: Harpy - word: Hellion - word: Hippo - word: Homarid - word: Homunculus - word: Horror - word: Horse - word: Hound - word: Human - word: Hydra - word: Hyena - word: - name: I - word: Illusion - word: Imp - word: Incarnation - word: Insect - word: - name: J - word: Jellyfish - word: Juggernaut - word: - name: K - word: Kavu - word: Kirin - word: Kithkin - word: Kobold - word: Kor - word: Kraken - word: - name: L - word: Lammasu - word: Leech - word: Leviathan - word: Lhurgoyf - word: Licid - word: Lizard - word: - name: M - word: Manticore - word: Masticore - word: Merfolk - word: Metathran - word: Minotaur - word: Mongoose - word: Moonfolk - word: Mutant - word: Myr - word: - name: N - word: Nautilus - word: Nephilim - word: Nightmare - word: Nightstalker - word: Noggle - word: - name: O - word: Octopus - word: Ogre - word: Ooze - word: Orb - word: Orc - word: Orgg - word: Ouphe - word: Ox - word: Oyster - word: - name: P - word: Pegasus - word: Pentavite - word: Pest - word: Phelddagrif - word: Phoenix - word: Pincher - word: Plant - word: Prism - word: - name: R - word: Rabbit - word: Rat - word: Reflection - word: Rhino - word: - name: S - word: - name: Sa-Sl - word: Salamander - word: Sand - word: Saproling - word: Satyr - word: Scarecrow - word: Scorpion - word: Serpent - word: Shade - word: Shapeshifter - word: Sheep - word: Skeleton - word: Slith - word: Sliver - word: Slug - word: - name: Sn-Sz - word: Snake - word: Soltari - word: Spawn - word: Specter - word: Sphinx - word: Spider - word: Spike - word: Spirit - word: Splinter - word: Sponge - word: Squid - word: Squirrel - word: Starfish - word: - name: T - word: Tetravite - word: Thalakos - word: Thopter - word: Thrull - word: Treefolk - word: Triskelavite - word: Troll - word: Turtle - word: - name: U - word: Unicorn - word: - name: V - word: Vampire - word: Vedalken - word: Viashino - word: Volver - word: - name: W - word: Wall - word: Weird - word: Whale - word: Wolf - word: Wolverine - word: Wombat - word: Worm - word: Wraith - word: Wurm - word: - name: Y - word: Yeti - word: - name: Z - word: Zombie - word: Zubera - -word list: - name: class - word: - script: all_classes() - line below: true - word: Advisor - word: Archer - word: Artificer - word: Assassin - word: Beast - word: Cleric - word: Druid - word: Knight - word: Mutant - word: Rogue - word: Scout - word: Shaman - word: Soldier - word: Warrior - word: Wizard - word: Zombie - word: - name: All Classes - word: - name: A-C - word: Advisor - word: Archer - word: Archon - word: Artificer - word: Assassin - word: Barbarian - word: Beast - word: Berserker - word: Bringer - word: Carrier - word: Citizen - word: Cleric - word: Coward - word: - name: D-I - word: Deserter - word: Dreadnought - word: Drone - word: Druid - word: Elder - word: Flagbearer - word: Horror - word: Incarnation - word: - name: J-P - word: Juggernaut - word: Knight - word: Leviathan - word: Mercenary - word: Minion - word: Monger - word: Monk - word: Mutant - word: Mystic - word: Ninja - word: Nomad - word: Pirate - word: - name: R-S - word: Rebel - word: Reflection - word: Rigger - word: Rogue - word: Samurai - word: Scout - word: Serf - word: Shaman - word: Soldier - word: Spellshaper - word: Survivor - word: - name: T-Z - word: Thopter - word: Vampire - word: Warrior - word: Wizard - word: Zombie - -word list: - name: artifact - word: - name: - line below: true - word: Contraption - word: Equipment - word: Fortification - -word list: - name: land - word: - script: all_sub_types(match: "Land") - line below: true - word: Plains - word: Island - word: Swamp - word: Mountain - word: Forest - word: Desert - word: Lair - word: Locus - word: Mine - word: Power-Plant - word: Tower - word: Urza's - -word list: - name: enchantment - word: - name: - line below: true - word: Aura - word: Shrine - -word list: - name: spell - word: - name: - line below: true - word: Arcane + +############################################################## Magic word lists + +word list: + name: type + word: + name: de base + is prefix: true + word: + name: légendaire + is prefix: true + word: + name: tribaux + is prefix: true + word: + name: de neige + is prefix: true + word: + name: monde + is prefix: true + line below: true + word: Créature + word: Artefact + word: Artefact Créature + word: Enchantement + word: Instant + word: Rituel + word: Terrain + word: Planeswalker + +word list: + name: race + word: + script: all_races() + line below: true + word: Angel + word: Beast + word: Bird + word: Construct + word: Demon + word: Dragon + word: Drake + word: Elemental + word: Elf + word: Faerie + word: Giant + word: Goblin + word: Golem + word: Human + word: Illusion + word: Merfolk + word: Treefolk + word: Zombie + word: + name: All Races + word: + name: A + word: Angel + word: Anteater + word: Antelope + word: Ape + word: Archon + word: Assembly-Worker + word: Atog + word: Aurochs + word: Avatar + word: + name: B + word: Badger + word: Basilisk + word: Bat + word: Bear + word: Beast + word: Beeble + word: Bird + word: Blinkmoth + word: Boar + word: Bringer + word: Brushwagg + word: + name: C + word: Camarid + word: Camel + word: Caribou + word: Cat + word: Centaur + word: Cephalid + word: Chimera + word: Cockatrice + word: Construct + word: Crab + word: Crocodile + word: Cyclops + word: + name: D + word: Dauthi + word: Demon + word: Devil + word: Djinn + word: Dragon + word: Drake + word: Dreadnought + word: Dryad + word: Dwarf + word: + name: E + word: Efreet + word: Egg + word: Elemental + word: Elephant + word: Elf + word: Elk + word: Eye + word: + name: F + word: Faerie + word: Ferret + word: Fish + word: Fox + word: Frog + word: Fungus + word: + name: G + word: Gargoyle + word: Giant + word: Gnome + word: Goat + word: Goblin + word: Golem + word: Gorgon + word: Graveborn + word: Griffin + word: + name: H + word: Hag + word: Harpy + word: Hellion + word: Hippo + word: Homarid + word: Homunculus + word: Horror + word: Horse + word: Hound + word: Human + word: Hydra + word: Hyena + word: + name: I + word: Illusion + word: Imp + word: Incarnation + word: Insect + word: + name: J + word: Jellyfish + word: Juggernaut + word: + name: K + word: Kavu + word: Kirin + word: Kithkin + word: Kobold + word: Kor + word: Kraken + word: + name: L + word: Lammasu + word: Leech + word: Leviathan + word: Lhurgoyf + word: Licid + word: Lizard + word: + name: M + word: Manticore + word: Masticore + word: Merfolk + word: Metathran + word: Minotaur + word: Mongoose + word: Moonfolk + word: Mutant + word: Myr + word: + name: N + word: Nautilus + word: Nephilim + word: Nightmare + word: Nightstalker + word: Noggle + word: + name: O + word: Octopus + word: Ogre + word: Ooze + word: Orb + word: Orc + word: Orgg + word: Ouphe + word: Ox + word: Oyster + word: + name: P + word: Pegasus + word: Pentavite + word: Pest + word: Phelddagrif + word: Phoenix + word: Pincher + word: Plant + word: Prism + word: + name: R + word: Rabbit + word: Rat + word: Reflection + word: Rhino + word: + name: S + word: + name: Sa-Sl + word: Salamander + word: Sand + word: Saproling + word: Satyr + word: Scarecrow + word: Scorpion + word: Serpent + word: Shade + word: Shapeshifter + word: Sheep + word: Skeleton + word: Slith + word: Sliver + word: Slug + word: + name: Sn-Sz + word: Snake + word: Soltari + word: Spawn + word: Specter + word: Sphinx + word: Spider + word: Spike + word: Spirit + word: Splinter + word: Sponge + word: Squid + word: Squirrel + word: Starfish + word: + name: T + word: Tetravite + word: Thalakos + word: Thopter + word: Thrull + word: Treefolk + word: Triskelavite + word: Troll + word: Turtle + word: + name: U + word: Unicorn + word: + name: V + word: Vampire + word: Vedalken + word: Viashino + word: Volver + word: + name: W + word: Wall + word: Weird + word: Whale + word: Wolf + word: Wolverine + word: Wombat + word: Worm + word: Wraith + word: Wurm + word: + name: Y + word: Yeti + word: + name: Z + word: Zombie + word: Zubera + +word list: + name: class + word: + script: all_classes() + line below: true + word: Advisor + word: Archer + word: Artificer + word: Assassin + word: Beast + word: Cleric + word: Druid + word: Knight + word: Mutant + word: Rogue + word: Scout + word: Shaman + word: Soldier + word: Warrior + word: Wizard + word: Zombie + word: + name: All Classes + word: + name: A-C + word: Advisor + word: Archer + word: Archon + word: Artificer + word: Assassin + word: Barbarian + word: Beast + word: Berserker + word: Bringer + word: Carrier + word: Citizen + word: Cleric + word: Coward + word: + name: D-I + word: Deserter + word: Dreadnought + word: Drone + word: Druid + word: Elder + word: Flagbearer + word: Horror + word: Incarnation + word: + name: J-P + word: Juggernaut + word: Knight + word: Leviathan + word: Mercenary + word: Minion + word: Monger + word: Monk + word: Mutant + word: Mystic + word: Ninja + word: Nomad + word: Pirate + word: + name: R-S + word: Rebel + word: Reflection + word: Rigger + word: Rogue + word: Samurai + word: Scout + word: Serf + word: Shaman + word: Soldier + word: Spellshaper + word: Survivor + word: + name: T-Z + word: Thopter + word: Vampire + word: Warrior + word: Wizard + word: Zombie + +word list: + name: artifact + word: + name: + line below: true + word: Contraption + word: Equipment + word: Fortification + +word list: + name: land + word: + script: all_sub_types(match: "Land") + line below: true + word: Plains + word: Island + word: Swamp + word: Mountain + word: Forest + word: Desert + word: Lair + word: Locus + word: Mine + word: Power-Plant + word: Tower + word: Urza's + +word list: + name: enchantment + word: + name: + line below: true + word: Aura + word: Shrine + +word list: + name: spell + word: + name: + line below: true + word: Arcane diff --git a/doc/README b/doc/README index 61c7b8df..4fad33cc 100644 --- a/doc/README +++ b/doc/README @@ -1,4 +1,4 @@ -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/* + +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. diff --git a/doc/about/index.txt b/doc/about/index.txt index cd44af75..da5b278a 100644 --- a/doc/about/index.txt +++ b/doc/about/index.txt @@ -1,23 +1,23 @@ -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!'' <<< +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!'' <<< diff --git a/doc/about/license.txt b/doc/about/license.txt index 3557979b..ab9464f8 100644 --- a/doc/about/license.txt +++ b/doc/about/license.txt @@ -1,327 +1,327 @@ -GNU General Public License - -Magic Set Editor is licensed under the GNU General Public License version 2 or later - - -==Table of Contents== -* GNU GENERAL PUBLIC LICENSE - * Preamble - * TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - * How to Apply These Terms to Your New Programs - -
- -Version 2, June 1991 - -]Copyright (C) 1989, 1991 Free Software Foundation, Inc. -]51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA -] -]Everyone is permitted to copy and distribute verbatim copies -]of this license document, but changing it is not allowed. - -==Preamble== - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - -==TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION== - -0. - This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - -1. - You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - -2. - You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - -;a) -; You must cause the modified files to carry prominent notices -; stating that you changed the files and the date of any change. - - -;b) -; You must cause any work that you distribute or publish, that in -; whole or in part contains or is derived from the Program or any -; part thereof, to be licensed as a whole at no charge to all third -; parties under the terms of this License. - - -;c) -; If the modified program normally reads commands interactively -; when run, you must cause it, when started running for such -; interactive use in the most ordinary way, to print or display an -; announcement including an appropriate copyright notice and a -; notice that there is no warranty (or else, saying that you provide -; a warranty) and that users may redistribute the program under -; these conditions, and telling the user how to view a copy of this -; License. (Exception: if the Program itself is interactive but -; does not normally print such an announcement, your work based on -; the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - -3. - You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - -;a) -; Accompany it with the complete corresponding machine-readable -; source code, which must be distributed under the terms of Sections -; 1 and 2 above on a medium customarily used for software interchange; or, - - -;b) -; Accompany it with a written offer, valid for at least three -; years, to give any third party, for a charge no more than your -; cost of physically performing source distribution, a complete -; machine-readable copy of the corresponding source code, to be -; distributed under the terms of Sections 1 and 2 above on a medium -; customarily used for software interchange; or, - - -;c) -; Accompany it with the information you received as to the offer -; to distribute corresponding source code. (This alternative is -; allowed only for noncommercial distribution and only if you -; received the program in object code or executable form with such -; an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - -4. - You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - -5. - You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - -6. - Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - -7. - If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - -8. - If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - -9. - The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - -10. - If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - -NO WARRANTY - - -11. - BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - -12. - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - -==END OF TERMS AND CONDITIONS== - +GNU General Public License + +Magic Set Editor is licensed under the GNU General Public License version 2 or later + + +==Table of Contents== +* GNU GENERAL PUBLIC LICENSE + * Preamble + * TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + * How to Apply These Terms to Your New Programs + +
+ +Version 2, June 1991 + +]Copyright (C) 1989, 1991 Free Software Foundation, Inc. +]51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA +] +]Everyone is permitted to copy and distribute verbatim copies +]of this license document, but changing it is not allowed. + +==Preamble== + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + +==TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION== + +0. + This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +1. + You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +2. + You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +;a) +; You must cause the modified files to carry prominent notices +; stating that you changed the files and the date of any change. + + +;b) +; You must cause any work that you distribute or publish, that in +; whole or in part contains or is derived from the Program or any +; part thereof, to be licensed as a whole at no charge to all third +; parties under the terms of this License. + + +;c) +; If the modified program normally reads commands interactively +; when run, you must cause it, when started running for such +; interactive use in the most ordinary way, to print or display an +; announcement including an appropriate copyright notice and a +; notice that there is no warranty (or else, saying that you provide +; a warranty) and that users may redistribute the program under +; these conditions, and telling the user how to view a copy of this +; License. (Exception: if the Program itself is interactive but +; does not normally print such an announcement, your work based on +; the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +3. + You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + +;a) +; Accompany it with the complete corresponding machine-readable +; source code, which must be distributed under the terms of Sections +; 1 and 2 above on a medium customarily used for software interchange; or, + + +;b) +; Accompany it with a written offer, valid for at least three +; years, to give any third party, for a charge no more than your +; cost of physically performing source distribution, a complete +; machine-readable copy of the corresponding source code, to be +; distributed under the terms of Sections 1 and 2 above on a medium +; customarily used for software interchange; or, + + +;c) +; Accompany it with the information you received as to the offer +; to distribute corresponding source code. (This alternative is +; allowed only for noncommercial distribution and only if you +; received the program in object code or executable form with such +; an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +4. + You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +5. + You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +6. + Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +7. + If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + +8. + If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + +9. + The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + +10. + If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + +NO WARRANTY + + +11. + BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + +12. + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + +==END OF TERMS AND CONDITIONS== + ==How to Apply These Terms to Your New Programs== diff --git a/doc/cli/cli.txt b/doc/cli/cli.txt index c945361e..7660424e 100644 --- a/doc/cli/cli.txt +++ b/doc/cli/cli.txt @@ -1,74 +1,74 @@ -Interactive command line interface - -DOC_MSE_VERSION: since 0.3.7 - ---Description-- - -]]mse --cli [my-set.mse-set] - -The MSE interactive command line interface provides a way to work with set files without a graphical environment. -The CLI shows a prompt where commands can be entered, which are then executed by MSE. - ---Commands-- - -! Command Short version Description -| @:help@ @:?@ Show a help screen describing the available commands. -| @:quit@ @:q@ Exit the MSE command line interface. -| @:load@ @:l@ Load a set file. The current set will be unloaded. - For example: - ]:load my-set.mse-set -| @:reset@ @:r@ Clear all variable definitions. -| @:cd@ @:c@ Change the working directory. -| @:pwd@ @:p@ Print the current working directory. -| @:!@ Perform a shell command. For example @:! dir@ shows a directory listing. -| ''other'' Execute the command as a line of [[type:script]] code. - The script has access to the loaded set and all [[fun:index|built in functions]]. - ---Raw mode-- - -]mse.exe --cli --raw - -For interfacing MSE with other programs the raw mode is most convenient. - -In the raw mode the only output is in response to commands. -For each command a single ''record'' is written to the standard output. -The records consists of: - * A line with an integer status code, @0@ for ok, @1@ for warnings, @2@ for errors. - * A line containing an integer ''k'', the number of lines to follow. - * ''k'' lines, each containing UTF-8 encoded string data. - -Strings are not further encoded or escaped. - -In this mode multi line strings can be transfered from MSE without much encoding/parsing hassle. - -The behaviour of the raw mode is guaranteed not to change between versions of MSE (subject to bugs and changes in the scripting language), -for the normal mode no such guarantee is made. - ---Example-- - -Here is an example session, the text entered by the user is shown in blue. - -]]$ mse --cli -] ___ -] __ __ _ ___ _ ___ _ _ _ |__ \ -] | \/ |__ _ __ _(_)__ / __|___| |_ | __|__| (_) |_ ___ _ _ ) | -] | |\/| / _` / _` | / _| \__ | -_) _| | _|/ _` | | _/ _ \ '_| / / -] |_| |_\__,_\__, |_\__| |___|___|\__| |___\__,_|_|\__\___/_| / /_ -] |___/ |____| -] -]]> :load myset.mse-set -]]> first_card := set.cards.0 # the first card -][[card]] ->>>>> first_card.name -]"Pineapple of Doom" ->>>>> write_image_file(first_card, file: "firstcard.jpg") -]]> # the image file "firstcard.jpg" is now saved -]]> :! dir -]2008-08-04 22:57 92 891 firstcard.jpg -] 1 File(s) 92 891 bytes -] 0 Dir(s) 986 562 560 bytes free -]]> :reset -]]> first_card.name # variable was cleared -]]ERROR: Variable not set: first_card -]]> :quit -]Goodbye +Interactive command line interface + +DOC_MSE_VERSION: since 0.3.7 + +--Description-- + +]]mse --cli [my-set.mse-set] + +The MSE interactive command line interface provides a way to work with set files without a graphical environment. +The CLI shows a prompt where commands can be entered, which are then executed by MSE. + +--Commands-- + +! Command Short version Description +| @:help@ @:?@ Show a help screen describing the available commands. +| @:quit@ @:q@ Exit the MSE command line interface. +| @:load@ @:l@ Load a set file. The current set will be unloaded. + For example: + ]:load my-set.mse-set +| @:reset@ @:r@ Clear all variable definitions. +| @:cd@ @:c@ Change the working directory. +| @:pwd@ @:p@ Print the current working directory. +| @:!@ Perform a shell command. For example @:! dir@ shows a directory listing. +| ''other'' Execute the command as a line of [[type:script]] code. + The script has access to the loaded set and all [[fun:index|built in functions]]. + +--Raw mode-- + +]mse.exe --cli --raw + +For interfacing MSE with other programs the raw mode is most convenient. + +In the raw mode the only output is in response to commands. +For each command a single ''record'' is written to the standard output. +The records consists of: + * A line with an integer status code, @0@ for ok, @1@ for warnings, @2@ for errors. + * A line containing an integer ''k'', the number of lines to follow. + * ''k'' lines, each containing UTF-8 encoded string data. + +Strings are not further encoded or escaped. + +In this mode multi line strings can be transfered from MSE without much encoding/parsing hassle. + +The behaviour of the raw mode is guaranteed not to change between versions of MSE (subject to bugs and changes in the scripting language), +for the normal mode no such guarantee is made. + +--Example-- + +Here is an example session, the text entered by the user is shown in blue. + +]]$ mse --cli +] ___ +] __ __ _ ___ _ ___ _ _ _ |__ \ +] | \/ |__ _ __ _(_)__ / __|___| |_ | __|__| (_) |_ ___ _ _ ) | +] | |\/| / _` / _` | / _| \__ | -_) _| | _|/ _` | | _/ _ \ '_| / / +] |_| |_\__,_\__, |_\__| |___|___|\__| |___\__,_|_|\__\___/_| / /_ +] |___/ |____| +] +]]> :load myset.mse-set +]]> first_card := set.cards.0 # the first card +][[card]] +>>>>> first_card.name +]"Pineapple of Doom" +>>>>> write_image_file(first_card, file: "firstcard.jpg") +]]> # the image file "firstcard.jpg" is now saved +]]> :! dir +]2008-08-04 22:57 92 891 firstcard.jpg +] 1 File(s) 92 891 bytes +] 0 Dir(s) 986 562 560 bytes free +]]> :reset +]]> first_card.name # variable was cleared +]]ERROR: Variable not set: first_card +]]> :quit +]Goodbye diff --git a/doc/cli/index.txt b/doc/cli/index.txt index 3c02ef05..3060826c 100644 --- a/doc/cli/index.txt +++ b/doc/cli/index.txt @@ -1,53 +1,53 @@ -MSE Command line - -Magic set editor can be started from the command prompt by typing: - -]mse -in Windows, or -]magicseteditor -on other platforms. - -The MSE program has several flags for choosing different behaviour. - ---Starting the GUI-- - -]mse -Invoking MSE with no arguments shows the welcome window. - -]]mse my-set.mse-set -Invoking MSE with the filename of a [[type:set]] shows the main window with that set loaded. -This command is automatically invoked when you double click on a set file in a file manager. - -]mse my-symbol.mse-symbol -Invoking MSE with the filename of a [[type:symbol]] shows the symbol editor window with that symbol loaded. - -]mse --symbol-editor -With the --symbol-editor flag the symbol editor is started with a blank symbol. - ---Information about MSE-- - -]mse --version -The --version flag (abbreviate as -v) writes the version number of MSE to the standard output, - or in a message box if MSE was not started from the command prompt. - -]mse --help -The --help flag (abbreviate as -?) displays a list of available flags to the standard output, - or in a message box if MSE was not started from the command prompt. - ---Installers-- - -]]mse my-installer.mse-installer -Invoking MSE with the filename of an [[type:installer]] shows the package window, from where the packages in that installer can be installed. -By passing the --local or --global flag you can change where the package will be installed. -Global installation is for all users, local installation is for the current user only (see [[file:index|data directories]]). - -]mse --create-installer output.mse-installer package1.mse-game package2.mse-game ... -Creates an installer package containing one or more packages from the mse [[file:index|data directory]]. -The installer will be written to output.mse-installer. This name can be omitted, in which case the name of the first package will be used (in this case package1.mse-installer). - ---Interactive cli interface-- - -]mse --cli -Starts the [[cli:cli|Interactive command line interface]]. -Optionally the filename of a set can be passed which will then be loaded. - +MSE Command line + +Magic set editor can be started from the command prompt by typing: + +]mse +in Windows, or +]magicseteditor +on other platforms. + +The MSE program has several flags for choosing different behaviour. + +--Starting the GUI-- + +]mse +Invoking MSE with no arguments shows the welcome window. + +]]mse my-set.mse-set +Invoking MSE with the filename of a [[type:set]] shows the main window with that set loaded. +This command is automatically invoked when you double click on a set file in a file manager. + +]mse my-symbol.mse-symbol +Invoking MSE with the filename of a [[type:symbol]] shows the symbol editor window with that symbol loaded. + +]mse --symbol-editor +With the --symbol-editor flag the symbol editor is started with a blank symbol. + +--Information about MSE-- + +]mse --version +The --version flag (abbreviate as -v) writes the version number of MSE to the standard output, + or in a message box if MSE was not started from the command prompt. + +]mse --help +The --help flag (abbreviate as -?) displays a list of available flags to the standard output, + or in a message box if MSE was not started from the command prompt. + +--Installers-- + +]]mse my-installer.mse-installer +Invoking MSE with the filename of an [[type:installer]] shows the package window, from where the packages in that installer can be installed. +By passing the --local or --global flag you can change where the package will be installed. +Global installation is for all users, local installation is for the current user only (see [[file:index|data directories]]). + +]mse --create-installer output.mse-installer package1.mse-game package2.mse-game ... +Creates an installer package containing one or more packages from the mse [[file:index|data directory]]. +The installer will be written to output.mse-installer. This name can be omitted, in which case the name of the first package will be used (in this case package1.mse-installer). + +--Interactive cli interface-- + +]mse --cli +Starts the [[cli:cli|Interactive command line interface]]. +Optionally the filename of a set can be passed which will then be loaded. + diff --git a/doc/file/format.txt b/doc/file/format.txt index 27354b06..c794754c 100644 --- a/doc/file/format.txt +++ b/doc/file/format.txt @@ -1,45 +1,45 @@ -Heirarchical files - -The actual MSE data is stored in heirarchical data files, these are usually files with no extension. -For example set or locale. -These are just ordinary text files, but they use an UTF-8 encoding, that means you need to use an editor that supports UTF-8. -Most modern editors support UTF-8, Notepad does on Windows XP. - ---Syntax-- -The files use a heirarchical structure and are made up of keys and values. -A value can be either a simple text string: ->game: magic -Or a block containing more keys and values: ->card: -> name: My Card -> type: Creature - -Indentation is used to find out what belongs to what block. Indentation must be exactly one TAB per level, spaces are not allowed. - -When the value is longer then a single line it can be written indented on the following lines: ->text: -> T: Draw a card -> WW: Gain 1 life - ---Order-- - -Usually the order in which keys appear in a file doesn't matter. -However some keys, like @mse version@ and @type@ must come first because they influence how the following keys are interpreted. - ---Includes-- - -A heirachical file can contain a reference to another file: ->>>include file: filename -Where filename must be an absolute or relative [[type:filename]]. - -That file is included literally into the current one; except for indentation, the included file never escapes from the level the 'include file' line is on. - ---Example-- -For example, a [[type:set]] might look like this: ->game: magic ->style: new ->card: -> name: My Card -> type: Creature ->card: -> name: Another card +Heirarchical files + +The actual MSE data is stored in heirarchical data files, these are usually files with no extension. +For example set or locale. +These are just ordinary text files, but they use an UTF-8 encoding, that means you need to use an editor that supports UTF-8. +Most modern editors support UTF-8, Notepad does on Windows XP. + +--Syntax-- +The files use a heirarchical structure and are made up of keys and values. +A value can be either a simple text string: +>game: magic +Or a block containing more keys and values: +>card: +> name: My Card +> type: Creature + +Indentation is used to find out what belongs to what block. Indentation must be exactly one TAB per level, spaces are not allowed. + +When the value is longer then a single line it can be written indented on the following lines: +>text: +> T: Draw a card +> WW: Gain 1 life + +--Order-- + +Usually the order in which keys appear in a file doesn't matter. +However some keys, like @mse version@ and @type@ must come first because they influence how the following keys are interpreted. + +--Includes-- + +A heirachical file can contain a reference to another file: +>>>include file: filename +Where filename must be an absolute or relative [[type:filename]]. + +That file is included literally into the current one; except for indentation, the included file never escapes from the level the 'include file' line is on. + +--Example-- +For example, a [[type:set]] might look like this: +>game: magic +>style: new +>card: +> name: My Card +> type: Creature +>card: +> name: Another card diff --git a/doc/file/index.txt b/doc/file/index.txt index dd773ae1..7ae6c0f6 100644 --- a/doc/file/index.txt +++ b/doc/file/index.txt @@ -1,39 +1,39 @@ -Data files - -MSE uses several different types of [[file:format|data files]], usually organized into [[file:package]]s. - ---File types-- -The following types are stored in [[file:package]]s in the: -* [[type:game]] -* [[type:stylesheet]] -* [[type:symbol font]] -* [[type:export template]] -* [[type:locale]] -* [[type:include]] - -The following types are stored in [[file:package]]s that can be located anywhere: -* [[type:set]] -* [[type:installer]] - -The following types are stored diractly in [[file:format|heirarchical files]], they can be located anywhere: -* [[type:symbol]] - ---Data directories-- -The data files that come with Magic Set Editor are stored in [[file:package]]s in the ''data directory'', -these are usually subdirectories of that directory. - -There are two data directories, a ''global'' one with data files installed with the program, -and a ''local'' data directory for the current logged in user. -The latter is used for installing packages if the user doesn't have administrator priviliges. - -The location of the global data directory is -! On windows <<< -| Location %MSE_DIR%\data -| Usually C:\Program Files\Magic Set Editor 2\data -! On linux/unix <<< -| Location ??? - -The location of the local data directory is -! On windows <<< -| Location %USER_APPLICATION_DATA%\Magic Set Editor\data -| Usually C:\Documents and Settings\%USERNAME%\Application Data\Magic Set Editor\data +Data files + +MSE uses several different types of [[file:format|data files]], usually organized into [[file:package]]s. + +--File types-- +The following types are stored in [[file:package]]s in the: +* [[type:game]] +* [[type:stylesheet]] +* [[type:symbol font]] +* [[type:export template]] +* [[type:locale]] +* [[type:include]] + +The following types are stored in [[file:package]]s that can be located anywhere: +* [[type:set]] +* [[type:installer]] + +The following types are stored diractly in [[file:format|heirarchical files]], they can be located anywhere: +* [[type:symbol]] + +--Data directories-- +The data files that come with Magic Set Editor are stored in [[file:package]]s in the ''data directory'', +these are usually subdirectories of that directory. + +There are two data directories, a ''global'' one with data files installed with the program, +and a ''local'' data directory for the current logged in user. +The latter is used for installing packages if the user doesn't have administrator priviliges. + +The location of the global data directory is +! On windows <<< +| Location %MSE_DIR%\data +| Usually C:\Program Files\Magic Set Editor 2\data +! On linux/unix <<< +| Location ??? + +The location of the local data directory is +! On windows <<< +| Location %USER_APPLICATION_DATA%\Magic Set Editor\data +| Usually C:\Documents and Settings\%USERNAME%\Application Data\Magic Set Editor\data diff --git a/doc/file/package.txt b/doc/file/package.txt index 426484f3..96bf9da5 100644 --- a/doc/file/package.txt +++ b/doc/file/package.txt @@ -1,20 +1,20 @@ -Packages - -Most files used by Magic Set Editor are stored in ''packages''. - -A package is either a zip file or simply a directory. - -A package has an extension to indicate its type, for example @"*.mse-set"@ is a [[type:set]] file and @"*.mse-symbol-font"@ is a [[type:symbol font]]. -To open a zipped package using a program like winzip you may need to rename it to @"something.zip"@ - ---Contents-- - -A package always contains a [[file:format|heirarchical data file]] with the same name as the package type and no extension. -For example @"my-set.mse-set"@ contains a file called @"set"@. - -A package can also contain other files like images. - ---Examples-- - -The [[file:index|data directory]] contains packages in the form of directories. -Each of the subdirectories is a package. +Packages + +Most files used by Magic Set Editor are stored in ''packages''. + +A package is either a zip file or simply a directory. + +A package has an extension to indicate its type, for example @"*.mse-set"@ is a [[type:set]] file and @"*.mse-symbol-font"@ is a [[type:symbol font]]. +To open a zipped package using a program like winzip you may need to rename it to @"something.zip"@ + +--Contents-- + +A package always contains a [[file:format|heirarchical data file]] with the same name as the package type and no extension. +For example @"my-set.mse-set"@ contains a file called @"set"@. + +A package can also contain other files like images. + +--Examples-- + +The [[file:index|data directory]] contains packages in the form of directories. +Each of the subdirectories is a package. diff --git a/doc/file/style_triangle.txt b/doc/file/style_triangle.txt index e20569e5..5aaa5201 100644 --- a/doc/file/style_triangle.txt +++ b/doc/file/style_triangle.txt @@ -1,19 +1,19 @@ -Style triangle - -A central idea of MSE is the separation of data and styling. - -Consider a single card, say "Forest". -This card could be printed in an old set, for example Fifth Edition, using an old style frame. -The ''same'' card can also be put into a new fram in for instance Ninth Edition. - -So the card (the data) is independent of the style, but both are based on the same game (description), i.e. Magic. - -This distinction is made on two levels. -The three different types of packages, [[type:game]], [[type:stylesheet]] and [[type:set]]. -They contain three different things, [[type:field]]s, [[type:style]]s and [[type:value]]s. - -This is illustrated in the diagram on the right and in the following table. -| Description Looks Data -| High level [[type:Game]] [[type:Stylesheet]] [[type:Set]] -| [[type:Card]] -| Low level [[type:Field]] [[type:Style]] [[type:Value]] +Style triangle + +A central idea of MSE is the separation of data and styling. + +Consider a single card, say "Forest". +This card could be printed in an old set, for example Fifth Edition, using an old style frame. +The ''same'' card can also be put into a new fram in for instance Ninth Edition. + +So the card (the data) is independent of the style, but both are based on the same game (description), i.e. Magic. + +This distinction is made on two levels. +The three different types of packages, [[type:game]], [[type:stylesheet]] and [[type:set]]. +They contain three different things, [[type:field]]s, [[type:style]]s and [[type:value]]s. + +This is illustrated in the diagram on the right and in the following table. +| Description Looks Data +| High level [[type:Game]] [[type:Stylesheet]] [[type:Set]] +| [[type:Card]] +| Low level [[type:Field]] [[type:Style]] [[type:Value]] diff --git a/doc/function/abs.txt b/doc/function/abs.txt index 552d2685..833363da 100644 --- a/doc/function/abs.txt +++ b/doc/function/abs.txt @@ -1,16 +1,16 @@ -Function: abs - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> abs(some_number) - -Returns the absolute value of a number. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:int]] or [[type:double]] Number to determine the absolute value of - ---Examples-- -> abs(1.5) == 1.5 -> abs(-1) == 1 +Function: abs + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> abs(some_number) + +Returns the absolute value of a number. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:int]] or [[type:double]] Number to determine the absolute value of + +--Examples-- +> abs(1.5) == 1.5 +> abs(-1) == 1 diff --git a/doc/function/assert.txt b/doc/function/assert.txt index 16d4601f..8e55af07 100644 --- a/doc/function/assert.txt +++ b/doc/function/assert.txt @@ -1,22 +1,22 @@ -Function: assert - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> assert(condition) - -Check that the condition is @true@. Shows a warning message if it is not. - -Note: @assert@ is a special built-in keyword, so that the error message can include the condition. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:boolean]] Condition to check. - ---Examples-- -> assert(1 + 1 == 2) # nothing happens -> assert(1 * 1 == 2) # An error message is shown - ---See also-- -| [[fun:warning]] Output a warning message. -| [[fun:error]] Output an error message. +Function: assert + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> assert(condition) + +Check that the condition is @true@. Shows a warning message if it is not. + +Note: @assert@ is a special built-in keyword, so that the error message can include the condition. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:boolean]] Condition to check. + +--Examples-- +> assert(1 + 1 == 2) # nothing happens +> assert(1 * 1 == 2) # An error message is shown + +--See also-- +| [[fun:warning]] Output a warning message. +| [[fun:error]] Output an error message. diff --git a/doc/function/break_text.txt b/doc/function/break_text.txt index 3110aa15..2fcaed2b 100644 --- a/doc/function/break_text.txt +++ b/doc/function/break_text.txt @@ -1,45 +1,45 @@ -Function: break_text - ---Usage-- -> break_text(some_string, match: regular expression, in_context: regular expression) - -Break text by only keeping the parts of the input that match the regular expression. -The function returns a [[type:list]] of parts. - -If @in_context@ is given, the context must also match the string where the match is represented as <match>. - -When the @break_text@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments: -> my_break := break_text@(match: "something") -> my_break("input") # called many times -This way the regular expression is only compiled once. - ---Filter vs. break-- - -The function @filter_text@ is very similar to @break_text@, instead of returning a list it concatenates the items. -So for example where @break_text@ returns @["a","b","c"]@, @filter_text@ would return @"abc"@. -In fact, @filter_text@ could be implemented as -> filter_text := { for part in break_text() do part } - ---Split vs. break-- - -The function @split_text@ does the opposite of @break_text@, keeping the parts between the regular expression matches, instead of the matching text itself. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to replace in. -| @match@ [[type:regex]] Regular expression to match. -| @in_context@ [[type:regex]] (optional) Context to match - ---Examples-- -> break_text(match: "a", "banana") == ["a","a","a"] -> break_text(match: "na|.", "banana") == ["b","a","na","na"] -> break_text(match: "ap", "banana") == [] -> break_text(match: "/", "a/b/c") == ["/","/"] -> break_text(match: "[^/]+", "a/b/c") == ["a","b","c"] -> -> f := break_text@(match: "xx+") -> f("xyzxxxxyyzz") == ["xxxx"] - ---See also-- -| [[fun:filter_text]] Keep only the text matching a regular expression. -| [[fun:split_text]] Split text into parts separated by a regular expression. +Function: break_text + +--Usage-- +> break_text(some_string, match: regular expression, in_context: regular expression) + +Break text by only keeping the parts of the input that match the regular expression. +The function returns a [[type:list]] of parts. + +If @in_context@ is given, the context must also match the string where the match is represented as <match>. + +When the @break_text@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments: +> my_break := break_text@(match: "something") +> my_break("input") # called many times +This way the regular expression is only compiled once. + +--Filter vs. break-- + +The function @filter_text@ is very similar to @break_text@, instead of returning a list it concatenates the items. +So for example where @break_text@ returns @["a","b","c"]@, @filter_text@ would return @"abc"@. +In fact, @filter_text@ could be implemented as +> filter_text := { for part in break_text() do part } + +--Split vs. break-- + +The function @split_text@ does the opposite of @break_text@, keeping the parts between the regular expression matches, instead of the matching text itself. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to replace in. +| @match@ [[type:regex]] Regular expression to match. +| @in_context@ [[type:regex]] (optional) Context to match + +--Examples-- +> break_text(match: "a", "banana") == ["a","a","a"] +> break_text(match: "na|.", "banana") == ["b","a","na","na"] +> break_text(match: "ap", "banana") == [] +> break_text(match: "/", "a/b/c") == ["/","/"] +> break_text(match: "[^/]+", "a/b/c") == ["a","b","c"] +> +> f := break_text@(match: "xx+") +> f("xyzxxxxyyzz") == ["xxxx"] + +--See also-- +| [[fun:filter_text]] Keep only the text matching a regular expression. +| [[fun:split_text]] Split text into parts separated by a regular expression. diff --git a/doc/function/built_in_image.txt b/doc/function/built_in_image.txt index 87ab7419..3edf2bad 100644 --- a/doc/function/built_in_image.txt +++ b/doc/function/built_in_image.txt @@ -1,18 +1,18 @@ -Function: built_in_image - ---Usage-- -> built_in_image(image_name) - -Retrieve an image built into the program. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Name of the image to retrieve - ---Possible values-- -! Image name Image -| @"bool_yes"@ bool_yes -| @"bool_no"@ bool_no - ---Examples-- -> built_in_image("bool_yes") == [[Image]] +Function: built_in_image + +--Usage-- +> built_in_image(image_name) + +Retrieve an image built into the program. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Name of the image to retrieve + +--Possible values-- +! Image name Image +| @"bool_yes"@ bool_yes +| @"bool_no"@ bool_no + +--Examples-- +> built_in_image("bool_yes") == [[Image]] diff --git a/doc/function/check_spelling.txt b/doc/function/check_spelling.txt index 688ea76b..e2976e08 100644 --- a/doc/function/check_spelling.txt +++ b/doc/function/check_spelling.txt @@ -1,36 +1,36 @@ -Function: check_spelling - ---Usage-- -> check_spelling(some_tagged_string, language:language_code) - -Check the spelling of a piece of text, and mark errors with @@ tags. - ---Dictionaries-- -The language code must correspond to a dictionary in the @dictionaries@ data directory (usually @%MSE_DIR%\data\dictionaries@). -A dictionary consists of two files, @language.dic@ and @language.aff@. - -Magic Set Editor is compatible with Hunspell dictionaries, which are also used by Open Office and Firefox. -These dictionaries can be found on [[http://wiki.services.openoffice.org/wiki/Dictionaries|the Open Office website]]. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:tagged string]] String to check. -| @language@ [[type:string]] Language code.
- The language code consists of an [[http://en.wikipedia.org/wiki/ISO_639|ISO language code]] and an [[http://en.wikipedia.org/wiki/ISO_3166-1|ISO country code]] separated by an underscore. -| @extra_dictionary@ [[type:string]] (optional) - Name of an additional dictionary to use. This dictionary could be specific to the game file. - The name should be of the form @"my-game.mse-game/dictionary"@, - in which case MSE looks for the file @"my-game.mse-game/dictionary.en_US.dic"@ where @"en_US"@ is the language code. -| @extra_match@ [[type:function]] (optional) - Function that returns @true@ for additional words that are spelled correctly. - This can be used for codes like @"+1/+1"@ on magic cards. - ---Examples-- -> check_spelling("Can I have an appple?", language:"en_US") -> == "Can I have an appple?" - -In the second example any text matching the [[type:regex]] @"x[a-z]*"@, i.e. any word beginning with the letter x, is not considered an error: -> check_spelling("xyzzyx", language:"en_US") -> == "xyzzyx" -> check_spelling("xyzzyx", language:"en_US", extra_match: match@(match:"x[a-z]*")) -> == "xyzzyx" +Function: check_spelling + +--Usage-- +> check_spelling(some_tagged_string, language:language_code) + +Check the spelling of a piece of text, and mark errors with @@ tags. + +--Dictionaries-- +The language code must correspond to a dictionary in the @dictionaries@ data directory (usually @%MSE_DIR%\data\dictionaries@). +A dictionary consists of two files, @language.dic@ and @language.aff@. + +Magic Set Editor is compatible with Hunspell dictionaries, which are also used by Open Office and Firefox. +These dictionaries can be found on [[http://wiki.services.openoffice.org/wiki/Dictionaries|the Open Office website]]. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:tagged string]] String to check. +| @language@ [[type:string]] Language code.
+ The language code consists of an [[http://en.wikipedia.org/wiki/ISO_639|ISO language code]] and an [[http://en.wikipedia.org/wiki/ISO_3166-1|ISO country code]] separated by an underscore. +| @extra_dictionary@ [[type:string]] (optional) + Name of an additional dictionary to use. This dictionary could be specific to the game file. + The name should be of the form @"my-game.mse-game/dictionary"@, + in which case MSE looks for the file @"my-game.mse-game/dictionary.en_US.dic"@ where @"en_US"@ is the language code. +| @extra_match@ [[type:function]] (optional) + Function that returns @true@ for additional words that are spelled correctly. + This can be used for codes like @"+1/+1"@ on magic cards. + +--Examples-- +> check_spelling("Can I have an appple?", language:"en_US") +> == "Can I have an appple?" + +In the second example any text matching the [[type:regex]] @"x[a-z]*"@, i.e. any word beginning with the letter x, is not considered an error: +> check_spelling("xyzzyx", language:"en_US") +> == "xyzzyx" +> check_spelling("xyzzyx", language:"en_US", extra_match: match@(match:"x[a-z]*")) +> == "xyzzyx" diff --git a/doc/function/chosen.txt b/doc/function/chosen.txt index 6e499620..1e5b58cb 100644 --- a/doc/function/chosen.txt +++ b/doc/function/chosen.txt @@ -1,20 +1,20 @@ -Function: chosen - ---Usage-- -> chosen(choice: some_string, some_multiple_choice_value) - -Is the given choice selected in the [[type:value#multiple_choice|multiple choice value]]? - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Multiple choice value to look in. -| @choice@ [[type:string]] Choice to look for. - ---Examples-- -> chosen(choice: "red", "red") == true -> chosen(choice: "red", "blue") == false -> chosen(choice: "red", "red, blue") == true -> chosen(choice: "blue", "red, blue") == true - ---See also-- -| [[fun:count_chosen]] Count then number of choices selected in a multiple choice value. +Function: chosen + +--Usage-- +> chosen(choice: some_string, some_multiple_choice_value) + +Is the given choice selected in the [[type:value#multiple_choice|multiple choice value]]? + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Multiple choice value to look in. +| @choice@ [[type:string]] Choice to look for. + +--Examples-- +> chosen(choice: "red", "red") == true +> chosen(choice: "red", "blue") == false +> chosen(choice: "red", "red, blue") == true +> chosen(choice: "blue", "red, blue") == true + +--See also-- +| [[fun:count_chosen]] Count then number of choices selected in a multiple choice value. diff --git a/doc/function/combine_blend.txt b/doc/function/combine_blend.txt index d97d5cbc..684493a6 100644 --- a/doc/function/combine_blend.txt +++ b/doc/function/combine_blend.txt @@ -1,22 +1,22 @@ -Function: combine_blend - ---Usage-- -> combine_blend(image1: image, image2: image, combine: combine_mode) - -Blend two images together using a [[type:combine|combine function]]. - -The images must have the same size. - ---Parameters-- -! Parameter Type Description -| @image1@ [[type:image]] First image to blend -| @image2@ [[type:image]] Second image to blend -| @combine@ [[type:combine]] Combining function to use - ---Examples-- -> combine_blend(image1: "image1.png", image2: "image2.png", combine: "add") == [[Image]] ->>> combine_blend(image1: "image1.png", image2: "image2.png", combine: "add") == "image_combine_blend.png" - ---See also-- -| [[fun:linear_blend]] Blend two images together using a linear gradient. -| [[fun:masked_blend]] Blend two images together using a third mask image. +Function: combine_blend + +--Usage-- +> combine_blend(image1: image, image2: image, combine: combine_mode) + +Blend two images together using a [[type:combine|combine function]]. + +The images must have the same size. + +--Parameters-- +! Parameter Type Description +| @image1@ [[type:image]] First image to blend +| @image2@ [[type:image]] Second image to blend +| @combine@ [[type:combine]] Combining function to use + +--Examples-- +> combine_blend(image1: "image1.png", image2: "image2.png", combine: "add") == [[Image]] +>>> combine_blend(image1: "image1.png", image2: "image2.png", combine: "add") == "image_combine_blend.png" + +--See also-- +| [[fun:linear_blend]] Blend two images together using a linear gradient. +| [[fun:masked_blend]] Blend two images together using a third mask image. diff --git a/doc/function/combined_editor.txt b/doc/function/combined_editor.txt index 9339484d..3b9e7296 100644 --- a/doc/function/combined_editor.txt +++ b/doc/function/combined_editor.txt @@ -1,46 +1,46 @@ -Function: combined_editor - ---Usage-- -> forward_editor(field: some_text_value) -> combined_editor(field1: some_text_value, field2: some_text_value, ..., separator1: some_string, ...) - -Use one text field to edit one or more others. - -This function must be used in the @script@ of a [[type:field#text|text field]]. -This field will then contain the combined values of the given fields, separated by the separators in @@ tags. -When the field changes the underlying values are updated and vice versa. - -Note: @forward_editor@ and @combined_editor@ are the same function. - ---Parameters-- -! Parameter Type Default Description -| @field@ [[type:value#text|text value]] Text value to edit -| @field1@ [[type:value#text|text value]] Another text value to edit -| @field2@ [[type:value#text|text value]] ''etc.'' -| @separator@ [[type:string]] Separator between field 1 and 2 -| @separator1@ [[type:string]] Multiple separators -| @separator2@ [[type:string]] Next separator, ''etc.'' -| @prefix@ [[type:string]] ''optional'' Prefix before the combined editor; like a separator between the start and the first field. -| @suffix@ [[type:string]] ''optional'' Suffix after the combined editor; like a separator between the last field and the end. -| @hide when empty@ [[type:boolean]] @false@ Don't include separators if the entire value is empty. -| @soft before empty@ [[type:boolean]] @false@ Make separators 'soft' when the value following it is empty. - Soft separators are hidden by default and shown grayed when the field is selected. - ---Examples-- ->card field: -> ... -> script: ->> combined_editor( ->> field1: card.first_part ->> separator: " - " ->> field2: card.second_part ->> ) - -Forwarding just one field should be used in cases when two fields share a value, or when sometimes multiple fields are combined. -For example the Magic uses: ->> if set.include_automatic_card_numbers then ->> combined_editor(field1: card.copyright, ->> separator: "/", ->> field2: card.card_number) ->> else ->> forward_editor(field: card.copyright) +Function: combined_editor + +--Usage-- +> forward_editor(field: some_text_value) +> combined_editor(field1: some_text_value, field2: some_text_value, ..., separator1: some_string, ...) + +Use one text field to edit one or more others. + +This function must be used in the @script@ of a [[type:field#text|text field]]. +This field will then contain the combined values of the given fields, separated by the separators in @@ tags. +When the field changes the underlying values are updated and vice versa. + +Note: @forward_editor@ and @combined_editor@ are the same function. + +--Parameters-- +! Parameter Type Default Description +| @field@ [[type:value#text|text value]] Text value to edit +| @field1@ [[type:value#text|text value]] Another text value to edit +| @field2@ [[type:value#text|text value]] ''etc.'' +| @separator@ [[type:string]] Separator between field 1 and 2 +| @separator1@ [[type:string]] Multiple separators +| @separator2@ [[type:string]] Next separator, ''etc.'' +| @prefix@ [[type:string]] ''optional'' Prefix before the combined editor; like a separator between the start and the first field. +| @suffix@ [[type:string]] ''optional'' Suffix after the combined editor; like a separator between the last field and the end. +| @hide when empty@ [[type:boolean]] @false@ Don't include separators if the entire value is empty. +| @soft before empty@ [[type:boolean]] @false@ Make separators 'soft' when the value following it is empty. + Soft separators are hidden by default and shown grayed when the field is selected. + +--Examples-- +>card field: +> ... +> script: +>> combined_editor( +>> field1: card.first_part +>> separator: " - " +>> field2: card.second_part +>> ) + +Forwarding just one field should be used in cases when two fields share a value, or when sometimes multiple fields are combined. +For example the Magic uses: +>> if set.include_automatic_card_numbers then +>> combined_editor(field1: card.copyright, +>> separator: "/", +>> field2: card.card_number) +>> else +>> forward_editor(field: card.copyright) diff --git a/doc/function/contains.txt b/doc/function/contains.txt index 339de15f..cdd44050 100644 --- a/doc/function/contains.txt +++ b/doc/function/contains.txt @@ -1,19 +1,19 @@ -Function: contains - ---Usage-- -> contains(some_string, match: to_search_for) - -Does one string contain another at any position? - ---Parameters-- -| @input@ [[type:string]] String to look in -| @match@ [[type:string]] String to look for - ---Examples-- -> contains("abcdefg", match:"abc") == true -> contains("abcdefg", match:"defg") == true -> contains("abcdefg", match:"abd") == false - ---See also-- -| [[fun:match]] Does a string match a regular expression? -| [[fun:chosen]] Is the given choice selected in a multiple choice value? +Function: contains + +--Usage-- +> contains(some_string, match: to_search_for) + +Does one string contain another at any position? + +--Parameters-- +| @input@ [[type:string]] String to look in +| @match@ [[type:string]] String to look for + +--Examples-- +> contains("abcdefg", match:"abc") == true +> contains("abcdefg", match:"defg") == true +> contains("abcdefg", match:"abd") == false + +--See also-- +| [[fun:match]] Does a string match a regular expression? +| [[fun:chosen]] Is the given choice selected in a multiple choice value? diff --git a/doc/function/copy_file.txt b/doc/function/copy_file.txt index 986d963e..d2eb2fdc 100644 --- a/doc/function/copy_file.txt +++ b/doc/function/copy_file.txt @@ -1,22 +1,22 @@ -Function: copy_file - ---Usage-- -> copy_file(filename) - -Copy a file from the export template package to the output directory. -If a file with the given name already exists it is overwritten. - -Returns the name of the file written. - -This function can only be used in an [[type:export template]], when create directory is true. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:filename]] File to copy - ---Examples-- -> copy_file("logo.png") == "logo.png" # this file is now in the output directory - ---See also-- -| [[fun:write_text_file]] Write a text file to the output directory. -| [[fun:write_image_file]] Write an image file to the output directory. +Function: copy_file + +--Usage-- +> copy_file(filename) + +Copy a file from the export template package to the output directory. +If a file with the given name already exists it is overwritten. + +Returns the name of the file written. + +This function can only be used in an [[type:export template]], when create directory is true. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:filename]] File to copy + +--Examples-- +> copy_file("logo.png") == "logo.png" # this file is now in the output directory + +--See also-- +| [[fun:write_text_file]] Write a text file to the output directory. +| [[fun:write_image_file]] Write an image file to the output directory. diff --git a/doc/function/count_chosen.txt b/doc/function/count_chosen.txt index cb9bf91c..1b34eebe 100644 --- a/doc/function/count_chosen.txt +++ b/doc/function/count_chosen.txt @@ -1,24 +1,24 @@ -Function: count_chosen - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> count_chosen(choices: some_string, some_multiple_choice_value) - -Coint the number of choices that are selected in a [[type:value#multiple_choice|multiple choice value]]. - -If the @choices@ parameter is given then only choices from that list are counted. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Multiple choice value to look in. -| @choices@ optional [[type:string]] A comma separated list of choices to look for. - ---Examples-- -> count_chosen("") == 0 -> count_chosen("red") == 1 -> count_chosen("red, green") == 2 -> count_chosen("red, green", choices: "red,blue") == 1 - ---See also-- -| [[fun:chosen]] Is a given choice selected in a multiple choice value? +Function: count_chosen + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> count_chosen(choices: some_string, some_multiple_choice_value) + +Coint the number of choices that are selected in a [[type:value#multiple_choice|multiple choice value]]. + +If the @choices@ parameter is given then only choices from that list are counted. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Multiple choice value to look in. +| @choices@ optional [[type:string]] A comma separated list of choices to look for. + +--Examples-- +> count_chosen("") == 0 +> count_chosen("red") == 1 +> count_chosen("red, green") == 2 +> count_chosen("red, green", choices: "red,blue") == 1 + +--See also-- +| [[fun:chosen]] Is a given choice selected in a multiple choice value? diff --git a/doc/function/crop.txt b/doc/function/crop.txt index cff79709..a7002a27 100644 --- a/doc/function/crop.txt +++ b/doc/function/crop.txt @@ -1,15 +1,15 @@ -Function: crop - ---Usage-- -> crop(input: image, height: height_of_new_image, width: width_of_new_image, offset_x: x_position_to_start_crop, offset_y: y_position_to_start_crop) - -Shrink an image by cutting off some of the image, starting at the position denoted by the offsets. The resulting image size is specified in the parameters. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to enlarge -| @height@ [[type:double]] Height of the resulting image -| @width@ [[type:double]] Width of the resulting image -| @offset_x@ [[type:double]] Offset of crop, horizontally -| @offset_y@ [[type:double]] Offset of crop, vertically - +Function: crop + +--Usage-- +> crop(input: image, height: height_of_new_image, width: width_of_new_image, offset_x: x_position_to_start_crop, offset_y: y_position_to_start_crop) + +Shrink an image by cutting off some of the image, starting at the position denoted by the offsets. The resulting image size is specified in the parameters. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to enlarge +| @height@ [[type:double]] Height of the resulting image +| @width@ [[type:double]] Width of the resulting image +| @offset_x@ [[type:double]] Offset of crop, horizontally +| @offset_y@ [[type:double]] Offset of crop, vertically + diff --git a/doc/function/curly_quotes.txt b/doc/function/curly_quotes.txt index a2987614..165aac9b 100644 --- a/doc/function/curly_quotes.txt +++ b/doc/function/curly_quotes.txt @@ -1,17 +1,17 @@ -Function: curly_quotes - ---Usage-- -> curly_quotes(some_tagged_string) - -Make quotes 'curly'. -Single and double quotation marks are changed to opening or closing versions depending on where they appear in the text. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:tagged string]] String to make quotes curly in. - ---Examples-- ->>> curly_quotes("He said: 'This is cool!', she said: \"No way!\" ") ->>> == "He said: ‘This is cool!’, she said: “No way!” " ->>> curly_quotes("Also: ’Wrong quotes‘ ") ->>> == "Also: ‘Wrong quotes’ " +Function: curly_quotes + +--Usage-- +> curly_quotes(some_tagged_string) + +Make quotes 'curly'. +Single and double quotation marks are changed to opening or closing versions depending on where they appear in the text. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:tagged string]] String to make quotes curly in. + +--Examples-- +>>> curly_quotes("He said: 'This is cool!', she said: \"No way!\" ") +>>> == "He said: ‘This is cool!’, she said: “No way!” " +>>> curly_quotes("Also: ’Wrong quotes‘ ") +>>> == "Also: ‘Wrong quotes’ " diff --git a/doc/function/drop_shadow.txt b/doc/function/drop_shadow.txt index 2d8c942a..34c64716 100644 --- a/doc/function/drop_shadow.txt +++ b/doc/function/drop_shadow.txt @@ -1,28 +1,28 @@ -Function: drop_shadow - ---Usage-- -> drop_shadow(image, offset_x: offset, offset_y: offset) - -Add a drop shadow to an image. - -The shadow is based on the opacity of the image. - -To make sure the shadow doesn't fall outside the image, it can be a good idea to [[fun:enlarge]] the image first. - ---Parameters-- -! Parameter Type Default Description -| @input@ [[type:image]] Image to add drop shadow to -| @offset_x@ [[type:double]] 0 Relative position of the shadow, a positive number moves the shadow to the left.
- Value is in the range 0 (no movement) to 1 (move by the width of the image) -| @offset_y@ [[type:double]] 0 Relative position of the shadow, a positive number moves the shadow down.
- Value is in the range 0 (no movement) to 1 (move by the height of the image) -| @blur_radius@ [[type:double]] 0 Amount to blur the shadow. -| @alpha@ [[type:double]] 0 Opacity of the shadow, in the range 0 (fully transparent) to 1 (fully opaque) -| @color@ [[type:color]] black Color of the shadow. - ---Examples-- -> drop_shadow("image4.png", offset_x: 0.08, offset_y: 0.08, alpha: 0.5) == [[Image]] ->>> drop_shadow("image1.png", offset_x: 0.08, offset_y: 0.08, alpha: 0.5) == "image_drop_shadow_1.png" - -> drop_shadow("image4.png", offset_x: -0.1, offset_y: 0.1, alpha: 1, color: rgb(0,0,255), blur_radius: 0.05) == [[Image]] ->>> drop_shadow("image1.png", offset_x: -0.1, offset_y: 0.1, alpha: 1, color: rgb(0,0,255), blur_radius: 0.05) == "image_drop_shadow_1.png" +Function: drop_shadow + +--Usage-- +> drop_shadow(image, offset_x: offset, offset_y: offset) + +Add a drop shadow to an image. + +The shadow is based on the opacity of the image. + +To make sure the shadow doesn't fall outside the image, it can be a good idea to [[fun:enlarge]] the image first. + +--Parameters-- +! Parameter Type Default Description +| @input@ [[type:image]] Image to add drop shadow to +| @offset_x@ [[type:double]] 0 Relative position of the shadow, a positive number moves the shadow to the left.
+ Value is in the range 0 (no movement) to 1 (move by the width of the image) +| @offset_y@ [[type:double]] 0 Relative position of the shadow, a positive number moves the shadow down.
+ Value is in the range 0 (no movement) to 1 (move by the height of the image) +| @blur_radius@ [[type:double]] 0 Amount to blur the shadow. +| @alpha@ [[type:double]] 0 Opacity of the shadow, in the range 0 (fully transparent) to 1 (fully opaque) +| @color@ [[type:color]] black Color of the shadow. + +--Examples-- +> drop_shadow("image4.png", offset_x: 0.08, offset_y: 0.08, alpha: 0.5) == [[Image]] +>>> drop_shadow("image1.png", offset_x: 0.08, offset_y: 0.08, alpha: 0.5) == "image_drop_shadow_1.png" + +> drop_shadow("image4.png", offset_x: -0.1, offset_y: 0.1, alpha: 1, color: rgb(0,0,255), blur_radius: 0.05) == [[Image]] +>>> drop_shadow("image1.png", offset_x: -0.1, offset_y: 0.1, alpha: 1, color: rgb(0,0,255), blur_radius: 0.05) == "image_drop_shadow_1.png" diff --git a/doc/function/english_number.txt b/doc/function/english_number.txt index 30daa6c2..9c89e027 100644 --- a/doc/function/english_number.txt +++ b/doc/function/english_number.txt @@ -1,24 +1,24 @@ -Function: english_number - ---Usage-- -> english_number(number) -> english_number_a(number) -> english_number_multiple(number) -> english_number_ordinal(number) - -Convert a number to English. -These four functions all behave slightly differently: -! Function function(1) function(2) function(3) -| @english_number@ @"one"@ @"two"@ @"three"@ -| @english_number_a@ @"a"@ @"two"@ @"three"@ -| @english_number_multiple@ @""@ @"two"@ @"three"@ -| @english_number_ordinal@ @"first"@ @"second"@ @"third"@ - -If the input is a keyword parameter value, it leaves a hint tag for [[fun:process_english_hints]], to indicate whether the following word should be plural or singular. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:int]] Number to convert - ---Examples-- -> english_number(1) == "one" +Function: english_number + +--Usage-- +> english_number(number) +> english_number_a(number) +> english_number_multiple(number) +> english_number_ordinal(number) + +Convert a number to English. +These four functions all behave slightly differently: +! Function function(1) function(2) function(3) +| @english_number@ @"one"@ @"two"@ @"three"@ +| @english_number_a@ @"a"@ @"two"@ @"three"@ +| @english_number_multiple@ @""@ @"two"@ @"three"@ +| @english_number_ordinal@ @"first"@ @"second"@ @"third"@ + +If the input is a keyword parameter value, it leaves a hint tag for [[fun:process_english_hints]], to indicate whether the following word should be plural or singular. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:int]] Number to convert + +--Examples-- +> english_number(1) == "one" diff --git a/doc/function/english_plural.txt b/doc/function/english_plural.txt index 4111c4fc..f071102f 100644 --- a/doc/function/english_plural.txt +++ b/doc/function/english_plural.txt @@ -1,16 +1,16 @@ -Function: english_plural - ---Usage-- -> english_plural(some_word) -> english_singular(some_word) - -Convert a word to the plural or singular form. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to convert - ---Examples-- -> english_plural("apple") == "apples" -> english_plural("berry") == "berries" -> english_singular("Red Horses") == "Red Horse" +Function: english_plural + +--Usage-- +> english_plural(some_word) +> english_singular(some_word) + +Convert a word to the plural or singular form. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to convert + +--Examples-- +> english_plural("apple") == "apples" +> english_plural("berry") == "berries" +> english_singular("Red Horses") == "Red Horse" diff --git a/doc/function/enlarge.txt b/doc/function/enlarge.txt index 65f94ef5..4c3c3278 100644 --- a/doc/function/enlarge.txt +++ b/doc/function/enlarge.txt @@ -1,16 +1,16 @@ -Function: enlarge - ---Usage-- -> enlarge(input: image, border_size: amount_to_enlarge) - -Enlarge an image by putting a transparent border around it. -The border size is given in percentages of the image size, so @border_size: 1@ makes the image three times as large by putting a border of 100% the size on all sides. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to enlarge -| @border_size@ [[type:double]] Amount of border to add - ---Examples-- -> enlarge(input: "image1.png", border_size: 0.1) == [[Image]] ->>> enlarge(input: "image1.png", border_size: 0.1) == "image_enlarge.png" +Function: enlarge + +--Usage-- +> enlarge(input: image, border_size: amount_to_enlarge) + +Enlarge an image by putting a transparent border around it. +The border size is given in percentages of the image size, so @border_size: 1@ makes the image three times as large by putting a border of 100% the size on all sides. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to enlarge +| @border_size@ [[type:double]] Amount of border to add + +--Examples-- +> enlarge(input: "image1.png", border_size: 0.1) == [[Image]] +>>> enlarge(input: "image1.png", border_size: 0.1) == "image_enlarge.png" diff --git a/doc/function/error.txt b/doc/function/error.txt index 1d634835..424562c7 100644 --- a/doc/function/error.txt +++ b/doc/function/error.txt @@ -1,21 +1,21 @@ -Function: error - -DOC_MSE_VERSION: since 2.0.1 - ---Usage-- -> error(some_string) - -Output an error message. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Message -| @condition@ [[type:boolean]] (optional) Only show the message if this condition holds. - ---Examples-- -> error("message") # the message is shown in the console panel -> error("message", condition: false) # shows no message - ---See also-- -| [[fun:assert]] Check that the condition is @true@. Shows a warning message if it is not. -| [[fun:warning]] Output a warning message. +Function: error + +DOC_MSE_VERSION: since 2.0.1 + +--Usage-- +> error(some_string) + +Output an error message. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Message +| @condition@ [[type:boolean]] (optional) Only show the message if this condition holds. + +--Examples-- +> error("message") # the message is shown in the console panel +> error("message", condition: false) # shows no message + +--See also-- +| [[fun:assert]] Check that the condition is @true@. Shows a warning message if it is not. +| [[fun:warning]] Output a warning message. diff --git a/doc/function/exclusive_choice.txt b/doc/function/exclusive_choice.txt index cb347821..b2bb170a 100644 --- a/doc/function/exclusive_choice.txt +++ b/doc/function/exclusive_choice.txt @@ -1,29 +1,29 @@ -Function: exclusive_choice - ---Usage-- -> exclusive_choice(choices: some_strings, some_multiple_choice_value) - -Requre that ''at most one'' of the given choices is selected in a [[type:value#multiple_choice|multiple choice value]]. - -If more then one is selected, deselects the last ones until one remains. -The choice that was just toggled in the GUI is never deselected if possible - -If non of the choices is selected the selection stays the same. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Multiple choice value to look update. -| @choice@ [[type:string]] Choice to look for. -| @choice1@ [[type:string]] Exclusion between multiple choices. -| @choice2@ [[type:string]] ''etc.'' - ---Examples-- -> exclusive_choice(choice1: "red", choice2: "green", "red, blue") == "red, blue" -> exclusive_choice(choice1: "red", choice2: "green", "red, green") == "red" -> exclusive_choice(choice1: "red", choice2: "green", "green, blue") == "green, blue" -> exclusive_choice(choice1: "red", choice2: "green", "black, blue") == "black, blue" - ---See also-- -| [[fun:require_choice]] Require that ''at least 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. +Function: exclusive_choice + +--Usage-- +> exclusive_choice(choices: some_strings, some_multiple_choice_value) + +Requre that ''at most one'' of the given choices is selected in a [[type:value#multiple_choice|multiple choice value]]. + +If more then one is selected, deselects the last ones until one remains. +The choice that was just toggled in the GUI is never deselected if possible + +If non of the choices is selected the selection stays the same. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Multiple choice value to look update. +| @choice@ [[type:string]] Choice to look for. +| @choice1@ [[type:string]] Exclusion between multiple choices. +| @choice2@ [[type:string]] ''etc.'' + +--Examples-- +> exclusive_choice(choice1: "red", choice2: "green", "red, blue") == "red, blue" +> exclusive_choice(choice1: "red", choice2: "green", "red, green") == "red" +> exclusive_choice(choice1: "red", choice2: "green", "green, blue") == "green, blue" +> exclusive_choice(choice1: "red", choice2: "green", "black, blue") == "black, blue" + +--See also-- +| [[fun:require_choice]] Require that ''at least 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. diff --git a/doc/function/expand_keywords.txt b/doc/function/expand_keywords.txt index bd48e4eb..133d89aa 100644 --- a/doc/function/expand_keywords.txt +++ b/doc/function/expand_keywords.txt @@ -1,64 +1,64 @@ -Function: expand_keywords - ---Usage-- -> expand_keywords(some_tagged_string, default_expand: {...}, combine: {...}) - -Find [[type:keyword]]s and generate their reminder text. - -The string is searched for keywords, when one is found its reminder text is generated. -This is done by calling @keyword.reminder(param1:.., param2:..., ...)@. -Where the @param@s are the matching keyword parameters. - -The it is determined whether the reminder text should be shown. -This is either because the user explicitly selected it, or when @default_expand(mode: keyword.mode)@ returns true. -Whether reminder text is shown is stored in a @@ tag around the keyword. -! Tag Reminder text Changed by user -| @@ hidden no -| @@ shown no -| @@ hidden yes -| @@ shown yes - -If the reminder text is shown the function @combine@ is called which should combine the reminder text with (in the variable @reminder@) with the keyword and its parameters (in the variable @keyword@). - -For example, in the case of magic: -> expand_keywords( -> default_expand: { set.automatic_reminder_text } -> combine: { "{keyword} ({reminder})" } -> ) -is used. This shows reminder text by default based on a [[type:set]] option, and it combined the keyword as @"keyword (reminder)"@. - ---Parameters-- -! Parameter Type Default Description -| @input@ [[type:tagged string]] String to expand keywords in. -| @condition@ [[type:function]] @{true}@ DOC_MSE_VERSION: since 0.3.7 - When should a keyword be recognized at all? -| @default_expand@ [[type:function]] @{true}@ Should reminder text be shown by default? -| @combine@ [[type:function]] How to combine keywords with the reminder text? - ---Arguments-- - -The @condition@, @default_expand@ and @combine@ functions will be called for each potential keyword match in the input. - -! Parameter Type Description -| @param1@, @param2@, ... [[type:tagged string]]s The parameter values. -| @mode@ [[type:string]] The @mode@ of the keyword. -| @used_placeholders@ [[type:boolean]] DOC_MSE_VERSION: since 0.3.7 - Is a placeholder used for any of the parameters? -| @correct_case@ [[type:boolean]] DOC_MSE_VERSION: since 0.3.7 - Is the keyword matched exactly, with the same case? -| @keyword@ [[type:tagged string]] In @combine@ only: The full keyword text including parameters -| @reminder@ [[type:string]] In @combine@ only: The expanded reminder text. - - ---Examples-- -Assuming a keyword @"mse"@ exists with reminder text @"Magic Set Editor"@ exists. -> expand_keywords(default_expand: {true}, combine: { keyword + " (= " + reminder + ")" }, "mse is cool") -> == "mse (= Magic Set Editor) is cool" -> -> f := expand_keywords@(default_expand: {true}, combine: { keyword+" (= "+reminder+")" }) -> f("mse is cool") == "mse (= Magic Set Editor) is cool" - -DOC_MSE_VERSION: since 0.3.7 -Keyword matching is case insensitive, to get case sensitive matching use a @condition@ that check for the @correct case@: -> expand_keywords(..., condition: { correct_case }) -In prior MSE versions matching was always case sensitive. +Function: expand_keywords + +--Usage-- +> expand_keywords(some_tagged_string, default_expand: {...}, combine: {...}) + +Find [[type:keyword]]s and generate their reminder text. + +The string is searched for keywords, when one is found its reminder text is generated. +This is done by calling @keyword.reminder(param1:.., param2:..., ...)@. +Where the @param@s are the matching keyword parameters. + +The it is determined whether the reminder text should be shown. +This is either because the user explicitly selected it, or when @default_expand(mode: keyword.mode)@ returns true. +Whether reminder text is shown is stored in a @@ tag around the keyword. +! Tag Reminder text Changed by user +| @@ hidden no +| @@ shown no +| @@ hidden yes +| @@ shown yes + +If the reminder text is shown the function @combine@ is called which should combine the reminder text with (in the variable @reminder@) with the keyword and its parameters (in the variable @keyword@). + +For example, in the case of magic: +> expand_keywords( +> default_expand: { set.automatic_reminder_text } +> combine: { "{keyword} ({reminder})" } +> ) +is used. This shows reminder text by default based on a [[type:set]] option, and it combined the keyword as @"keyword (reminder)"@. + +--Parameters-- +! Parameter Type Default Description +| @input@ [[type:tagged string]] String to expand keywords in. +| @condition@ [[type:function]] @{true}@ DOC_MSE_VERSION: since 0.3.7 + When should a keyword be recognized at all? +| @default_expand@ [[type:function]] @{true}@ Should reminder text be shown by default? +| @combine@ [[type:function]] How to combine keywords with the reminder text? + +--Arguments-- + +The @condition@, @default_expand@ and @combine@ functions will be called for each potential keyword match in the input. + +! Parameter Type Description +| @param1@, @param2@, ... [[type:tagged string]]s The parameter values. +| @mode@ [[type:string]] The @mode@ of the keyword. +| @used_placeholders@ [[type:boolean]] DOC_MSE_VERSION: since 0.3.7 + Is a placeholder used for any of the parameters? +| @correct_case@ [[type:boolean]] DOC_MSE_VERSION: since 0.3.7 + Is the keyword matched exactly, with the same case? +| @keyword@ [[type:tagged string]] In @combine@ only: The full keyword text including parameters +| @reminder@ [[type:string]] In @combine@ only: The expanded reminder text. + + +--Examples-- +Assuming a keyword @"mse"@ exists with reminder text @"Magic Set Editor"@ exists. +> expand_keywords(default_expand: {true}, combine: { keyword + " (= " + reminder + ")" }, "mse is cool") +> == "mse (= Magic Set Editor) is cool" +> +> f := expand_keywords@(default_expand: {true}, combine: { keyword+" (= "+reminder+")" }) +> f("mse is cool") == "mse (= Magic Set Editor) is cool" + +DOC_MSE_VERSION: since 0.3.7 +Keyword matching is case insensitive, to get case sensitive matching use a @condition@ that check for the @correct case@: +> expand_keywords(..., condition: { correct_case }) +In prior MSE versions matching was always case sensitive. diff --git a/doc/function/filter_list.txt b/doc/function/filter_list.txt index 9100ce3b..8a58901a 100644 --- a/doc/function/filter_list.txt +++ b/doc/function/filter_list.txt @@ -1,19 +1,19 @@ -Function: filter_list - ---Usage-- -> filter_list(some_list, filter: some_predicate) - -Returns a new list that contain all elements in the list for which the filter predicate returns @true@. - -If possible, when using a set, use the [[fun:position]] and [[fun:number_of_items]] functions instead. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:list]] or [[type:set]] List to filter. -| @filter@ [[type:function]] Function indicating which values to keep, - Will be called with @input@ set to an item in the list. - ---Examples-- -> filter_list([1,2,3,4], filter: { input > 2 } ) == [3,4] -> filter_list([1,2,3,4], filter: { input % 2 == 0 }) == [2,4] -> filter_list(set, filter: { input.color == "red" }) == # red cards in the set +Function: filter_list + +--Usage-- +> filter_list(some_list, filter: some_predicate) + +Returns a new list that contain all elements in the list for which the filter predicate returns @true@. + +If possible, when using a set, use the [[fun:position]] and [[fun:number_of_items]] functions instead. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:list]] or [[type:set]] List to filter. +| @filter@ [[type:function]] Function indicating which values to keep, + Will be called with @input@ set to an item in the list. + +--Examples-- +> filter_list([1,2,3,4], filter: { input > 2 } ) == [3,4] +> filter_list([1,2,3,4], filter: { input % 2 == 0 }) == [2,4] +> filter_list(set, filter: { input.color == "red" }) == # red cards in the set diff --git a/doc/function/filter_text.txt b/doc/function/filter_text.txt index ad97e937..1b006011 100644 --- a/doc/function/filter_text.txt +++ b/doc/function/filter_text.txt @@ -1,31 +1,31 @@ -Function: filter_text - ---Usage-- -> filter_text(some_string, match: regular expression, in_context: regular expression) - -Filter text by only keeping the parts of the input that match the regular expression. - -If @in_context@ is given, the context must also match the string where the match is represented as <match>. - -When the @filter_text@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments: -> my_filter := filter_text@(match: "something") -> my_filter("input") # called many times -This way the regular expression is only compiled once. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to replace in. -| @match@ [[type:regex]] Regular expression to match. -| @in_context@ [[type:regex]] (optional) Context to match - ---Examples-- -> filter_text(match: "a", "banana") == "aaa" -> filter_text(match: ".", in_context:"a", "banana") == "nn" -> filter_text(match: "[xy]", "xyz") == "xy" -> -> f := filter_text@(match: "xx+") -> f("xyzxxyyzz") == "xx" - ---See also-- -| [[fun:break_text]] Break text into parts each matching a regular expression. -| [[fun:replace]] Replace text matching a regular expression. +Function: filter_text + +--Usage-- +> filter_text(some_string, match: regular expression, in_context: regular expression) + +Filter text by only keeping the parts of the input that match the regular expression. + +If @in_context@ is given, the context must also match the string where the match is represented as <match>. + +When the @filter_text@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments: +> my_filter := filter_text@(match: "something") +> my_filter("input") # called many times +This way the regular expression is only compiled once. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to replace in. +| @match@ [[type:regex]] Regular expression to match. +| @in_context@ [[type:regex]] (optional) Context to match + +--Examples-- +> filter_text(match: "a", "banana") == "aaa" +> filter_text(match: ".", in_context:"a", "banana") == "nn" +> filter_text(match: "[xy]", "xyz") == "xy" +> +> f := filter_text@(match: "xx+") +> f("xyzxxyyzz") == "xx" + +--See also-- +| [[fun:break_text]] Break text into parts each matching a regular expression. +| [[fun:replace]] Replace text matching a regular expression. diff --git a/doc/function/flip_horizontal.txt b/doc/function/flip_horizontal.txt index 14bdc90c..cb1433e3 100644 --- a/doc/function/flip_horizontal.txt +++ b/doc/function/flip_horizontal.txt @@ -1,20 +1,20 @@ -Function: flip_horizontal - -DOC_MSE_VERSION: since 0.3.9 - ---Usage-- -> flip_horizontal(input: image) - -Flip an image horizontally. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to flip. - ---Examples-- -> flip_horizontal("image_logo.png") == [[Image]] ->>> flip_horizontal("image_logo.png") == "image_logo_hflip.png" - ---See also-- -| [[fun:flip_vertical]] Flip an image vertically -| [[fun:rotate]] Rotate an image +Function: flip_horizontal + +DOC_MSE_VERSION: since 0.3.9 + +--Usage-- +> flip_horizontal(input: image) + +Flip an image horizontally. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to flip. + +--Examples-- +> flip_horizontal("image_logo.png") == [[Image]] +>>> flip_horizontal("image_logo.png") == "image_logo_hflip.png" + +--See also-- +| [[fun:flip_vertical]] Flip an image vertically +| [[fun:rotate]] Rotate an image diff --git a/doc/function/flip_vertical.txt b/doc/function/flip_vertical.txt index 913f624e..614c973c 100644 --- a/doc/function/flip_vertical.txt +++ b/doc/function/flip_vertical.txt @@ -1,20 +1,20 @@ -Function: flip_vertical - -DOC_MSE_VERSION: since 0.3.9 - ---Usage-- -> flip_vertical(input: image) - -Flip an image vertically. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to flip. - ---Examples-- -> flip_vertical("image_logo.png") == [[Image]] ->>> flip_vertical("image_logo.png") == "image_logo_vflip.png" - ---See also-- -| [[fun:flip_horizontal]] Flip an image horizontally -| [[fun:rotate]] Rotate an image +Function: flip_vertical + +DOC_MSE_VERSION: since 0.3.9 + +--Usage-- +> flip_vertical(input: image) + +Flip an image vertically. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to flip. + +--Examples-- +> flip_vertical("image_logo.png") == [[Image]] +>>> flip_vertical("image_logo.png") == "image_logo_vflip.png" + +--See also-- +| [[fun:flip_horizontal]] Flip an image horizontally +| [[fun:rotate]] Rotate an image diff --git a/doc/function/format.txt b/doc/function/format.txt index d809309e..54840fc9 100644 --- a/doc/function/format.txt +++ b/doc/function/format.txt @@ -1,25 +1,25 @@ -Function: format - -DOC_MSE_VERSION: deprecated in 0.3.7, use to_string - ---Usage-- -> format(some_number, format: format_specification) - -Format a number or other string as a string, [[http://www.cplusplus.com/reference/clibrary/cstdio/printf.html|printf]] style. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:int]] or [[type:double]] or [[type:string]] - Item to format. -| @format@ [[type:string]] Format specification. - ---Examples-- -> format(format: "%03X", 13) == "00D" -> format(format: "%03d", 13) == "013" -> format(format: "%3s", "xy") == " xy" -> -> f := format@(format: "%03d") -> f(1) == "001" - ---See also-- -| [[fun:to_string]] Convert any value to a [[type:string]] +Function: format + +DOC_MSE_VERSION: deprecated in 0.3.7, use to_string + +--Usage-- +> format(some_number, format: format_specification) + +Format a number or other string as a string, [[http://www.cplusplus.com/reference/clibrary/cstdio/printf.html|printf]] style. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:int]] or [[type:double]] or [[type:string]] + Item to format. +| @format@ [[type:string]] Format specification. + +--Examples-- +> format(format: "%03X", 13) == "00D" +> format(format: "%03d", 13) == "013" +> format(format: "%3s", "xy") == " xy" +> +> f := format@(format: "%03d") +> f(1) == "001" + +--See also-- +| [[fun:to_string]] Convert any value to a [[type:string]] diff --git a/doc/function/index.txt b/doc/function/index.txt index 3f65d09e..6c159609 100644 --- a/doc/function/index.txt +++ b/doc/function/index.txt @@ -1,113 +1,113 @@ -Script functions by category - -These functions are built into the program, other [[type:function]]s can be defined using the scripting language. - -! Type conversion <<< -| [[fun:to_string]] Convert any value to a [[type:string]] -| [[fun:to_int]] Convert any value to a [[type:int]] -| [[fun:to_real]] Convert any value to a [[type:double]] -| [[fun:to_number]] Convert any value to a number -| [[fun:to_boolean]] Convert any value to a [[type:boolean]] -| [[fun:to_color]] Convert any value to a [[type:color]] -| [[fun:to_image]] Convert any value to an [[type:image]] -| [[fun:to_date]] Convert any value to a [[type:date]] - -! Numbers <<< -| [[fun:abs]] Absolute value -| [[fun:random_int]] Generate a random [[type:int]]. -| [[fun:random_real]] Generate a random [[type:double]]. -| [[fun:random_boolean]] Generate a random [[type:boolean]]. - -! 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:trim]] Remove leading and trailing whitespace from a string, @" abc " -> "abc"@. -| [[fun:substring]] Extract a part of a string. -| [[fun:replace]] Replace text matching a regular expression. -| [[fun:filter_text]] Keep only the text matching a regular expression. -| [[fun:break_text]] Break text into parts each matching a regular expression. -| [[fun:split_text]] Split text into parts separated by a regular expression. -| [[fun:sort_text]] Sort the letters in a string using a custom order. -| [[fun:contains]] Does a string contain another one? -| [[fun:match]] Does a string match a regular expression? -| [[fun:regex_escape]] Escape a string for use in a regular expression. -| [[fun:curly_quotes]] Make quotes curly. -| [[fun:check_spelling]] Check text for spelling errors. - -! [[type:tagged_string|Tags]] <<< -| [[fun:tag_contents]] Change the contents of a specific tag. -| [[fun:remove_tag]] Remove a tag, keep the contents. -| [[fun:remove_tags]] Remove all tags from tagged text. - -! [[type:list|Lists]] <<< -| [[fun:position]] Find the position of an element in a list. -| [[fun:length]] Return the number of items in a list. -| [[fun:number_of_items]] Return 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. -| [[fun:random_shuffle]] Randomly shuffle a list. -| [[fun:random_select]] Pick a random element from a list. -| [[fun:random_select_many]] Pick multiple random elements from a list. - -! Keywords <<< -| [[fun:expand_keywords]] Expand the keywords in a piece of text. -| [[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|english_number_a]] Convert a number to text (@"a"@, @"two"@, ''etc.'') -| [[fun:english_number|english_number_multiple]] Convert a number to text (@""@, @"two"@, ''etc.'') -| [[fun:english_number|english_number_ordinal]] Convert a number to text (@"first"@, @"second"@, ''etc.'') -| [[fun:english_plural]] Find the plural of a word, @"card" -> "cards"@. -| [[fun:english_plural|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:count_chosen]] Count then number of choices 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]] Change how the image should be combined with the background. -| [[fun:saturate]] Saturate/desaturate an image. -| [[fun:invert_image]] Invert the colors of an image. -| [[fun:recolor_image]] Change the colors of an image to match the font color. -| [[fun:enlarge]] Enlarge an image by putting a border around it. -| [[fun:crop]] Crop an image, giving only a small subset of it. -| [[fun:flip_horizontal]] Flip an image horizontally. -| [[fun:flip_vertical]] Flip an image vertically. -| [[fun:rotate]] Rotate an image. -| [[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. - -! Cards <<< -| [[fun:new_card]] Construct a new [[type:card]] object. - -! HTML export <<< -| [[fun:to_html]] Convert [[type:tagged text]] to html. -| [[fun:symbols_to_html]] Convert text to html using a [[type:symbol font]]. -| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. -| [[fun:copy_file]] Copy a file from the [[type:export template]] to the output directory. -| [[fun:write_text_file]] Write a text file to the output directory. -| [[fun:write_image_file]] Write an image file to the output directory. -| [[fun:write_set_file]] Write a MSE set file to the output directory. - -! Other functions <<< -| [[fun:trace]] Output a message for debugging purposes. -| [[fun:assert]] Check a condition for debugging purposes. -| [[fun:warning]] Output a warning message. -| [[fun:error]] Output an error message. +Script functions by category + +These functions are built into the program, other [[type:function]]s can be defined using the scripting language. + +! Type conversion <<< +| [[fun:to_string]] Convert any value to a [[type:string]] +| [[fun:to_int]] Convert any value to a [[type:int]] +| [[fun:to_real]] Convert any value to a [[type:double]] +| [[fun:to_number]] Convert any value to a number +| [[fun:to_boolean]] Convert any value to a [[type:boolean]] +| [[fun:to_color]] Convert any value to a [[type:color]] +| [[fun:to_image]] Convert any value to an [[type:image]] +| [[fun:to_date]] Convert any value to a [[type:date]] + +! Numbers <<< +| [[fun:abs]] Absolute value +| [[fun:random_int]] Generate a random [[type:int]]. +| [[fun:random_real]] Generate a random [[type:double]]. +| [[fun:random_boolean]] Generate a random [[type:boolean]]. + +! 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:trim]] Remove leading and trailing whitespace from a string, @" abc " -> "abc"@. +| [[fun:substring]] Extract a part of a string. +| [[fun:replace]] Replace text matching a regular expression. +| [[fun:filter_text]] Keep only the text matching a regular expression. +| [[fun:break_text]] Break text into parts each matching a regular expression. +| [[fun:split_text]] Split text into parts separated by a regular expression. +| [[fun:sort_text]] Sort the letters in a string using a custom order. +| [[fun:contains]] Does a string contain another one? +| [[fun:match]] Does a string match a regular expression? +| [[fun:regex_escape]] Escape a string for use in a regular expression. +| [[fun:curly_quotes]] Make quotes curly. +| [[fun:check_spelling]] Check text for spelling errors. + +! [[type:tagged_string|Tags]] <<< +| [[fun:tag_contents]] Change the contents of a specific tag. +| [[fun:remove_tag]] Remove a tag, keep the contents. +| [[fun:remove_tags]] Remove all tags from tagged text. + +! [[type:list|Lists]] <<< +| [[fun:position]] Find the position of an element in a list. +| [[fun:length]] Return the number of items in a list. +| [[fun:number_of_items]] Return 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. +| [[fun:random_shuffle]] Randomly shuffle a list. +| [[fun:random_select]] Pick a random element from a list. +| [[fun:random_select_many]] Pick multiple random elements from a list. + +! Keywords <<< +| [[fun:expand_keywords]] Expand the keywords in a piece of text. +| [[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|english_number_a]] Convert a number to text (@"a"@, @"two"@, ''etc.'') +| [[fun:english_number|english_number_multiple]] Convert a number to text (@""@, @"two"@, ''etc.'') +| [[fun:english_number|english_number_ordinal]] Convert a number to text (@"first"@, @"second"@, ''etc.'') +| [[fun:english_plural]] Find the plural of a word, @"card" -> "cards"@. +| [[fun:english_plural|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:count_chosen]] Count then number of choices 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]] Change how the image should be combined with the background. +| [[fun:saturate]] Saturate/desaturate an image. +| [[fun:invert_image]] Invert the colors of an image. +| [[fun:recolor_image]] Change the colors of an image to match the font color. +| [[fun:enlarge]] Enlarge an image by putting a border around it. +| [[fun:crop]] Crop an image, giving only a small subset of it. +| [[fun:flip_horizontal]] Flip an image horizontally. +| [[fun:flip_vertical]] Flip an image vertically. +| [[fun:rotate]] Rotate an image. +| [[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. + +! Cards <<< +| [[fun:new_card]] Construct a new [[type:card]] object. + +! HTML export <<< +| [[fun:to_html]] Convert [[type:tagged text]] to html. +| [[fun:symbols_to_html]] Convert text to html using a [[type:symbol font]]. +| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. +| [[fun:copy_file]] Copy a file from the [[type:export template]] to the output directory. +| [[fun:write_text_file]] Write a text file to the output directory. +| [[fun:write_image_file]] Write an image file to the output directory. +| [[fun:write_set_file]] Write a MSE set file to the output directory. + +! Other functions <<< +| [[fun:trace]] Output a message for debugging purposes. +| [[fun:assert]] Check a condition for debugging purposes. +| [[fun:warning]] Output a warning message. +| [[fun:error]] Output an error message. diff --git a/doc/function/invert_image.txt b/doc/function/invert_image.txt index 06e298c6..491728c4 100644 --- a/doc/function/invert_image.txt +++ b/doc/function/invert_image.txt @@ -1,16 +1,16 @@ -Function: invert_image - -DOC_MSE_VERSION: since 0.3.9 - ---Usage-- -> invert_image(input: image) - -Invert the colors in an image. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to invert. - ---Examples-- -> invert_image("image_logo.png") == [[Image]] ->>> invert_image("image_logo.png") == "image_logo_invert.png" +Function: invert_image + +DOC_MSE_VERSION: since 0.3.9 + +--Usage-- +> invert_image(input: image) + +Invert the colors in an image. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to invert. + +--Examples-- +> invert_image("image_logo.png") == [[Image]] +>>> invert_image("image_logo.png") == "image_logo_invert.png" diff --git a/doc/function/keyword_usage.txt b/doc/function/keyword_usage.txt index 46ffa356..caf190b8 100644 --- a/doc/function/keyword_usage.txt +++ b/doc/function/keyword_usage.txt @@ -1,19 +1,19 @@ -Function: keyword_usage - ---Usage-- -> keyword_usage(card: some_card) - -Returns a comma separated list of the keywords that appear on the card. - -For example if a card contains the keywords "Flying" and "Haste" the function will return @"Flying, Haste"@. - -If a keyword appears multiple times on the card it will also appear multiple times in the output, unless @unique@ is specified. - ---Parameters-- -! Parameter Type Description -| @card@ [[type:card]] Card to find keywords on. -| @unique@ [[type:boolean]] (optional) Return each keyword at most once. - ---Examples-- -> keyword_usage(card: some_card, unique: false) == "Flying, Flying, Haste" -> keyword_usage(card: some_card, unique: true) == "Flying, Haste" +Function: keyword_usage + +--Usage-- +> keyword_usage(card: some_card) + +Returns a comma separated list of the keywords that appear on the card. + +For example if a card contains the keywords "Flying" and "Haste" the function will return @"Flying, Haste"@. + +If a keyword appears multiple times on the card it will also appear multiple times in the output, unless @unique@ is specified. + +--Parameters-- +! Parameter Type Description +| @card@ [[type:card]] Card to find keywords on. +| @unique@ [[type:boolean]] (optional) Return each keyword at most once. + +--Examples-- +> keyword_usage(card: some_card, unique: false) == "Flying, Flying, Haste" +> keyword_usage(card: some_card, unique: true) == "Flying, Haste" diff --git a/doc/function/length.txt b/doc/function/length.txt index 7798007b..9338c93e 100644 --- a/doc/function/length.txt +++ b/doc/function/length.txt @@ -1,22 +1,22 @@ -Function: length - ---Usage-- -> length(some_collection) - -Returns the number of items in a list or the number of characters in a string. - -Note: This function is exactly the same as [[fun:number_of_items]]. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:list]] or [[type:map]] or [[type:set]] or [[type:string]] - Object to determine the number of items of. - When it is a set, returns the number of cards. - When it is a string, returns the number of characters. - ---Examples-- -> length(["x", "y", "z"]) == 3 -> length("pink") == 4 - ---See also-- -| [[fun:number_of_items]] Return the number of items in a list. +Function: length + +--Usage-- +> length(some_collection) + +Returns the number of items in a list or the number of characters in a string. + +Note: This function is exactly the same as [[fun:number_of_items]]. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:list]] or [[type:map]] or [[type:set]] or [[type:string]] + Object to determine the number of items of. + When it is a set, returns the number of cards. + When it is a string, returns the number of characters. + +--Examples-- +> length(["x", "y", "z"]) == 3 +> length("pink") == 4 + +--See also-- +| [[fun:number_of_items]] Return the number of items in a list. diff --git a/doc/function/linear_blend.txt b/doc/function/linear_blend.txt index b9711445..a480fbcb 100644 --- a/doc/function/linear_blend.txt +++ b/doc/function/linear_blend.txt @@ -1,31 +1,31 @@ -Function: linear_blend - ---Usage-- -> linear_blend( -> image1: image, image2: image, -> x1: coordinate, y1: coordinate, -> x2: coordinate, y2: coordinate, -> ) - -Blend two images together using a linear gradient. - -Coordinates range from 0 to 1, where 0 is the top and the left, and 1 is the right and the bottom. -So for example a blend from @x1:0, y1:0@ to @x2:0, y2:1@ is from top to bottom. - -The images must have the same size. - ---Parameters-- -! Parameter Type Description -| @image1@ [[type:image]] First image to blend -| @image2@ [[type:image]] Second image to blend -| @x1@,@y1@ [[type:double]] Coordinates where the gradient begins, and the first image is shown for 100% -| @x2@,@y2@ [[type:double]] Coordinates where the gradient ends, and the second image is shown for 100% - ---Examples-- -This gives a vertical gradient: -> linear_blend(image1: "image1.png", image2: "image2.png", x1:0, y1:0, x2:0, y2:1) == [[Image]] ->>> linear_blend(image1: "image1.png", image2: "image2.png", x1:0, y1:0, x2:1, y2:1) == "image_linear_blend.png" - ---See also-- -| [[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]]. +Function: linear_blend + +--Usage-- +> linear_blend( +> image1: image, image2: image, +> x1: coordinate, y1: coordinate, +> x2: coordinate, y2: coordinate, +> ) + +Blend two images together using a linear gradient. + +Coordinates range from 0 to 1, where 0 is the top and the left, and 1 is the right and the bottom. +So for example a blend from @x1:0, y1:0@ to @x2:0, y2:1@ is from top to bottom. + +The images must have the same size. + +--Parameters-- +! Parameter Type Description +| @image1@ [[type:image]] First image to blend +| @image2@ [[type:image]] Second image to blend +| @x1@,@y1@ [[type:double]] Coordinates where the gradient begins, and the first image is shown for 100% +| @x2@,@y2@ [[type:double]] Coordinates where the gradient ends, and the second image is shown for 100% + +--Examples-- +This gives a vertical gradient: +> linear_blend(image1: "image1.png", image2: "image2.png", x1:0, y1:0, x2:0, y2:1) == [[Image]] +>>> linear_blend(image1: "image1.png", image2: "image2.png", x1:0, y1:0, x2:1, y2:1) == "image_linear_blend.png" + +--See also-- +| [[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]]. diff --git a/doc/function/masked_blend.txt b/doc/function/masked_blend.txt index 914e6f35..0759c37d 100644 --- a/doc/function/masked_blend.txt +++ b/doc/function/masked_blend.txt @@ -1,24 +1,24 @@ -Function: masked_blend - ---Usage-- -> masked_blend(light: image, dark: image, mask: image) - -Blend two images together using a third as a mask. -On pixels the mask is white the 'light' image is used, where the mask is black the 'dark' image is used. -For grey pixels the images are blended. - -The images must have the same size. - ---Parameters-- -! Parameter Type Description -| @light@ [[type:image]] Image for the light colores in the mask -| @dark@ [[type:image]] Image for the dark colores in the mask -| @mask@ [[type:image]] Mask image that selects between the two images - ---Examples-- -> masked_blend(light: "image1.png", dark: "image2.png", mask: "image3.png") == [[Image]] ->>> masked_blend(light: "image1.png", dark: "image2.png", mask: "image3.png") == "image_masked_blend.png" - ---See also-- -| [[fun:linear_blend]] Blend two images together using a linear gradient. -| [[fun:combine_blend]] Blend two images together using a given [[type:combine|combining mode]]. +Function: masked_blend + +--Usage-- +> masked_blend(light: image, dark: image, mask: image) + +Blend two images together using a third as a mask. +On pixels the mask is white the 'light' image is used, where the mask is black the 'dark' image is used. +For grey pixels the images are blended. + +The images must have the same size. + +--Parameters-- +! Parameter Type Description +| @light@ [[type:image]] Image for the light colores in the mask +| @dark@ [[type:image]] Image for the dark colores in the mask +| @mask@ [[type:image]] Mask image that selects between the two images + +--Examples-- +> masked_blend(light: "image1.png", dark: "image2.png", mask: "image3.png") == [[Image]] +>>> masked_blend(light: "image1.png", dark: "image2.png", mask: "image3.png") == "image_masked_blend.png" + +--See also-- +| [[fun:linear_blend]] Blend two images together using a linear gradient. +| [[fun:combine_blend]] Blend two images together using a given [[type:combine|combining mode]]. diff --git a/doc/function/match.txt b/doc/function/match.txt index 481edb0f..3d6cbcee 100644 --- a/doc/function/match.txt +++ b/doc/function/match.txt @@ -1,29 +1,29 @@ -Function: match - ---Usage-- -> match(some_string, match: regular expression) - -Does a string match the given [[type:regex|regular expression]]? - -When the match is performed many times with the same regular expression it is more efficient to declare that as a default argument: -> my_match := match@(match: "something") -> my_match("input") # called many times -This way the regular expression is only compiled once. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to match. -| @match@ [[type:regex]] Regular expression to match. - ---Examples-- -> match("aaaa", match:"a*") == true -> match("a", match:"b*") == true -> match("abc", match:"b+") == true -> match("abc", match:"$b+^") == false -> -> f := match@(match: "a+|b+") -> f("xyz") == false -> f("aabb") == true - ---See also-- -| [[fun:contains]] Does a string contain another one? +Function: match + +--Usage-- +> match(some_string, match: regular expression) + +Does a string match the given [[type:regex|regular expression]]? + +When the match is performed many times with the same regular expression it is more efficient to declare that as a default argument: +> my_match := match@(match: "something") +> my_match("input") # called many times +This way the regular expression is only compiled once. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to match. +| @match@ [[type:regex]] Regular expression to match. + +--Examples-- +> match("aaaa", match:"a*") == true +> match("a", match:"b*") == true +> match("abc", match:"b+") == true +> match("abc", match:"$b+^") == false +> +> f := match@(match: "a+|b+") +> f("xyz") == false +> f("aabb") == true + +--See also-- +| [[fun:contains]] Does a string contain another one? diff --git a/doc/function/new_card.txt b/doc/function/new_card.txt index 620fd75c..0167742f 100644 --- a/doc/function/new_card.txt +++ b/doc/function/new_card.txt @@ -1,25 +1,25 @@ -Function: new_card - ---Usage-- -> new_card(map_of_field_names_to_values) - -Create a new [[type:card]] object not already in the set. - -The argument is a map of values to set, for example @new_card([name: "My Card"])@ creates a card with the name @"My Card"@, and all other fields at their default value. - -NOTE: you should use underscores instead of spaces in field names. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:map]] of field names to field values Field values to set - ---Examples-- -> # Create a new card -> my_card := new_card( -> [ name: "My Card" ->> , type: "Super cool" ->> , rule_text: "This card is mine!" -> ]) -> -> # Write an image of the card to a file -> write_image_file(my_card, file: "my_card.jpg") +Function: new_card + +--Usage-- +> new_card(map_of_field_names_to_values) + +Create a new [[type:card]] object not already in the set. + +The argument is a map of values to set, for example @new_card([name: "My Card"])@ creates a card with the name @"My Card"@, and all other fields at their default value. + +NOTE: you should use underscores instead of spaces in field names. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:map]] of field names to field values Field values to set + +--Examples-- +> # Create a new card +> my_card := new_card( +> [ name: "My Card" +>> , type: "Super cool" +>> , rule_text: "This card is mine!" +> ]) +> +> # Write an image of the card to a file +> write_image_file(my_card, file: "my_card.jpg") diff --git a/doc/function/number_of_items.txt b/doc/function/number_of_items.txt index 727f4cd4..db107462 100644 --- a/doc/function/number_of_items.txt +++ b/doc/function/number_of_items.txt @@ -1,30 +1,30 @@ -Function: number_of_items - ---Usage-- -> number_of_items(in: some_collection) - -Returns the number of items in a list or the number of characters in a string. - -Note: This function is exactly the same as [[fun:length]]. - ---Parameters-- -! Parameter Type Description -| @in@ [[type:list]] or [[type:map]] or [[type:set]] or [[type:string]] - Object to determine the number of items of. - When it is a set, returns the number of cards. - When it is a string, returns the number of characters. -| @filter@ [[type:function]] (optional) Act as if the list was [[fun:filter_list|filtered]] by this criterion. - Only when @in@ is a set. - ---Examples-- -> number_of_items(in: ["x", "y", "z"]) == 3 -> number_of_items(in: "pink") == 4 -> number_of_items(in: set) == # number of cards in the set -> -> # the number of red cards in the set -> number_of_items(in: set, filter: { card.color == "red" } ) - ---See also-- -| [[fun:length]] Return 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. +Function: number_of_items + +--Usage-- +> number_of_items(in: some_collection) + +Returns the number of items in a list or the number of characters in a string. + +Note: This function is exactly the same as [[fun:length]]. + +--Parameters-- +! Parameter Type Description +| @in@ [[type:list]] or [[type:map]] or [[type:set]] or [[type:string]] + Object to determine the number of items of. + When it is a set, returns the number of cards. + When it is a string, returns the number of characters. +| @filter@ [[type:function]] (optional) Act as if the list was [[fun:filter_list|filtered]] by this criterion. + Only when @in@ is a set. + +--Examples-- +> number_of_items(in: ["x", "y", "z"]) == 3 +> number_of_items(in: "pink") == 4 +> number_of_items(in: set) == # number of cards in the set +> +> # the number of red cards in the set +> number_of_items(in: set, filter: { card.color == "red" } ) + +--See also-- +| [[fun:length]] Return 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. diff --git a/doc/function/position.txt b/doc/function/position.txt index dae1aef0..d9ec6c24 100644 --- a/doc/function/position.txt +++ b/doc/function/position.txt @@ -1,31 +1,31 @@ -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-- -! Parameter Type Description -| @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"}) - ---See also-- -| [[fun:length]] / [[fun:number_of_items]] Return 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. +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-- +! Parameter Type Description +| @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"}) + +--See also-- +| [[fun:length]] / [[fun:number_of_items]] Return 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. diff --git a/doc/function/primary_choice.txt b/doc/function/primary_choice.txt index 090d1a9e..23d3f228 100644 --- a/doc/function/primary_choice.txt +++ b/doc/function/primary_choice.txt @@ -1,29 +1,29 @@ -Function: primary_choice - ---Usage-- -> primary_choice(some_choice_value) - -Returns the name of the 'top level' choice selected. - -For example if a [[type:field|choice field]] is declared with the [[type:choice]]s: ->choice: -> name: large -> choice: red -> choice: blue ->choice: -> name: small -> group choice: just small -> choice: green -> choice: yellow -Then @primary_choice("large red") == "large"@. - -This function is used to keep [[type:statiscs_dimension|statistics]] cleaner by not having columns for all possible sub choices. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Choice value to look at. - ---Examples-- -> primary_choice("large red") == "large" -> primary_choice("large") == "large" -> primary_choice("small green") == "small" +Function: primary_choice + +--Usage-- +> primary_choice(some_choice_value) + +Returns the name of the 'top level' choice selected. + +For example if a [[type:field|choice field]] is declared with the [[type:choice]]s: +>choice: +> name: large +> choice: red +> choice: blue +>choice: +> name: small +> group choice: just small +> choice: green +> choice: yellow +Then @primary_choice("large red") == "large"@. + +This function is used to keep [[type:statiscs_dimension|statistics]] cleaner by not having columns for all possible sub choices. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Choice value to look at. + +--Examples-- +> primary_choice("large red") == "large" +> primary_choice("large") == "large" +> primary_choice("small green") == "small" diff --git a/doc/function/process_english_hints.txt b/doc/function/process_english_hints.txt index 86875efa..efc99bbb 100644 --- a/doc/function/process_english_hints.txt +++ b/doc/function/process_english_hints.txt @@ -1,31 +1,31 @@ -Function: process_english_hints - ---Usage-- -> process_english_hints(some_string_with_hints) - -Process the hints left in the string by [[fun:english_number]] and by inserting keyword parameters. -There are two types of hints: -! Hint Description -| <hint-1> Indicates that a number 1 was inserted, the following should be in singular form. -| <hint-2> Indicates that a number not 1 was inserted, the following should be in plural form. -| <param> Indicates that a keyword was inserted, if the text is @"a something"@ where something begins with a vowel, - turns it into @"an something"@. - -For the plurality hints, the text following it can contain information on how to use it -! Code Example Description -| (...) house(s) When the thing preceding it is singular the contents of the parentheses are removed, otherwise they are kept.
- So this will result in @"house"@ or @"houses"@. -| <singular>...</singular> <singular>mouse</singular> Only kept when in singular mode. -| <plural>...</plural> <plural>mice</plural> Only kept when in plural mode. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:tagged string]] String to process hints in. - ---Examples-- -> process_english_hints("a {param1}") == "a card" -> process_english_hints("a {param1}") == "an apple" -> process_english_hints("{english_number(1)} house(s)") == "one house" -> process_english_hints("{english_number(2)} house(s)") == "two houses" -> process_english_hints("{english_number(1)} mousemice") == "one mouse" -> process_english_hints("{english_number(1)} mousemice") == "two mice" +Function: process_english_hints + +--Usage-- +> process_english_hints(some_string_with_hints) + +Process the hints left in the string by [[fun:english_number]] and by inserting keyword parameters. +There are two types of hints: +! Hint Description +| <hint-1> Indicates that a number 1 was inserted, the following should be in singular form. +| <hint-2> Indicates that a number not 1 was inserted, the following should be in plural form. +| <param> Indicates that a keyword was inserted, if the text is @"a something"@ where something begins with a vowel, + turns it into @"an something"@. + +For the plurality hints, the text following it can contain information on how to use it +! Code Example Description +| (...) house(s) When the thing preceding it is singular the contents of the parentheses are removed, otherwise they are kept.
+ So this will result in @"house"@ or @"houses"@. +| <singular>...</singular> <singular>mouse</singular> Only kept when in singular mode. +| <plural>...</plural> <plural>mice</plural> Only kept when in plural mode. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:tagged string]] String to process hints in. + +--Examples-- +> process_english_hints("a {param1}") == "a card" +> process_english_hints("a {param1}") == "an apple" +> process_english_hints("{english_number(1)} house(s)") == "one house" +> process_english_hints("{english_number(2)} house(s)") == "two houses" +> process_english_hints("{english_number(1)} mousemice") == "one mouse" +> process_english_hints("{english_number(1)} mousemice") == "two mice" diff --git a/doc/function/random_boolean.txt b/doc/function/random_boolean.txt index c603d17e..379fce5f 100644 --- a/doc/function/random_boolean.txt +++ b/doc/function/random_boolean.txt @@ -1,22 +1,22 @@ -Function: random_boolean - -DOC_MSE_VERSION: since 0.3.8 - ---Usage-- -> random_boolean(probability) - -Returns a random [[type:bool]], either @true@ or @false@. -The parameter is the probability of returning @true@, so @random_boolean(0.0)@ always returns @true@, @random_boolean(1.0)@ always returns @false@ and @random_boolean(0.5)@ simulates a fair coin toss. - -Since the result is random, calling the function twice will give a different answer. - ---Parameters-- -! Parameter Type Default Description -| @input@ [[type:double]] @0.5@ Probability of returining true - ---Examples-- -> random_boolean(0.5) == true -> random_boolean(0.5) == false - ---See also-- -| [[fun:random_real]] Generate a random [[type:double]]. +Function: random_boolean + +DOC_MSE_VERSION: since 0.3.8 + +--Usage-- +> random_boolean(probability) + +Returns a random [[type:bool]], either @true@ or @false@. +The parameter is the probability of returning @true@, so @random_boolean(0.0)@ always returns @true@, @random_boolean(1.0)@ always returns @false@ and @random_boolean(0.5)@ simulates a fair coin toss. + +Since the result is random, calling the function twice will give a different answer. + +--Parameters-- +! Parameter Type Default Description +| @input@ [[type:double]] @0.5@ Probability of returining true + +--Examples-- +> random_boolean(0.5) == true +> random_boolean(0.5) == false + +--See also-- +| [[fun:random_real]] Generate a random [[type:double]]. diff --git a/doc/function/random_int.txt b/doc/function/random_int.txt index 8d7e7e50..92f47cc9 100644 --- a/doc/function/random_int.txt +++ b/doc/function/random_int.txt @@ -1,26 +1,26 @@ -Function: random_int - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> random_int(begin: lower bound, end: upper bound) - -Returns a random [[type:int]] between @begin@ and @end@. -By default @begin: 0@ is used. -The random number @x@ will be in the range @begin <= x < end@. - -Since the result is random, calling the function twice will give a different answer. - ---Parameters-- -! Parameter Type Default Description -| @begin@ [[type:int]] @0@ Lower end point of the range the number will be in. -| @end@ [[type:int]] ''required'' Upper end point of the range the number will be in. - ---Examples-- -> random_int(end:10) == 2 -> random_int(end:10) == 5 -> random_int(begin:100, end:200) == 43 - ---See also-- -| [[fun:random_real]] Generate a random [[type:double]]. -| [[fun:random_boolean]] Generate a random [[type:boolean]]. +Function: random_int + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> random_int(begin: lower bound, end: upper bound) + +Returns a random [[type:int]] between @begin@ and @end@. +By default @begin: 0@ is used. +The random number @x@ will be in the range @begin <= x < end@. + +Since the result is random, calling the function twice will give a different answer. + +--Parameters-- +! Parameter Type Default Description +| @begin@ [[type:int]] @0@ Lower end point of the range the number will be in. +| @end@ [[type:int]] ''required'' Upper end point of the range the number will be in. + +--Examples-- +> random_int(end:10) == 2 +> random_int(end:10) == 5 +> random_int(begin:100, end:200) == 43 + +--See also-- +| [[fun:random_real]] Generate a random [[type:double]]. +| [[fun:random_boolean]] Generate a random [[type:boolean]]. diff --git a/doc/function/random_real.txt b/doc/function/random_real.txt index 94a93a13..8b0b7610 100644 --- a/doc/function/random_real.txt +++ b/doc/function/random_real.txt @@ -1,25 +1,25 @@ -Function: random_real - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> random_real(begin: lower bound, end: upper bound) - -Returns a random [[type:double]] between @begin@ and @end@. -By default the range @0.0@ to @1.0@ is used. - -Since the result is random, calling the function twice will give a different answer. - ---Parameters-- -! Parameter Type Default Description -| @begin@ [[type:double]] @0.0@ Lower end point of the range the number will be in. -| @end@ [[type:double]] @1.0@ Upper end point of the range the number will be in. - ---Examples-- -> random_real() == 0.1451651461 -> random_real() == 0.7521351365 -> random_real(begin:100, end:200) == 193.2914351341 - ---See also-- -| [[fun:random_int]] Generate a random [[type:int|integer number]]. -| [[fun:random_boolean]] Generate a random [[type:boolean]]. +Function: random_real + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> random_real(begin: lower bound, end: upper bound) + +Returns a random [[type:double]] between @begin@ and @end@. +By default the range @0.0@ to @1.0@ is used. + +Since the result is random, calling the function twice will give a different answer. + +--Parameters-- +! Parameter Type Default Description +| @begin@ [[type:double]] @0.0@ Lower end point of the range the number will be in. +| @end@ [[type:double]] @1.0@ Upper end point of the range the number will be in. + +--Examples-- +> random_real() == 0.1451651461 +> random_real() == 0.7521351365 +> random_real(begin:100, end:200) == 193.2914351341 + +--See also-- +| [[fun:random_int]] Generate a random [[type:int|integer number]]. +| [[fun:random_boolean]] Generate a random [[type:boolean]]. diff --git a/doc/function/random_select.txt b/doc/function/random_select.txt index e2f87a0e..4a16d446 100644 --- a/doc/function/random_select.txt +++ b/doc/function/random_select.txt @@ -1,22 +1,22 @@ -Function: random_select - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> random_select(some_list, count: some_number, replace: some_boolean) - -Randomly select an items from a list. - -Since the result is random, calling the function twice will give a different answer. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:list]] List to shuffle. - ---Examples-- -> random_select([1,2,3,4]) == 4 -> random_select([1,2,3,4]) == 2 - ---See also-- -| [[fun:random_select_many]] Pick multiple random elements from a list. -| [[fun:random_shuffle]] Randomly shuffle a list. +Function: random_select + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> random_select(some_list, count: some_number, replace: some_boolean) + +Randomly select an items from a list. + +Since the result is random, calling the function twice will give a different answer. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:list]] List to shuffle. + +--Examples-- +> random_select([1,2,3,4]) == 4 +> random_select([1,2,3,4]) == 2 + +--See also-- +| [[fun:random_select_many]] Pick multiple random elements from a list. +| [[fun:random_shuffle]] Randomly shuffle a list. diff --git a/doc/function/random_select_many.txt b/doc/function/random_select_many.txt index 2da407c6..aede3f2c 100644 --- a/doc/function/random_select_many.txt +++ b/doc/function/random_select_many.txt @@ -1,29 +1,29 @@ -Function: random_select_many - -DOC_MSE_VERSION: since 0.3.8 - ---Usage-- -> random_select(some_list, count: some_number, replace: some_boolean) - -Randomly select a number of items from a list. - -By default @count@ ''different'' items are selected (selection without replacment). -Setting the @replace@ parameter allows the same item to occur more than once in the result (selection with replacment). - -Since the result is random, calling the function twice will give a different answer. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:list]] List to shuffle. -| @count@ [[type:int]] Number of items to select. -| @replace@ [[type:boolean]] Select with replacement? - ---Examples-- -> random_select_many([1,2,3,4], count:3) == [2,3,1] -> random_select_many([1,2,3,4], count:3) == [3,1,4] -> random_select_many([1,2,3,4], count:3, replace: true) == [2,3,2] -> random_select_many([1,2,3,4], count:3, replace: false) == [1,3,4] - ---See also-- -| [[fun:random_select]] Pick a single random element from a list. -| [[fun:random_shuffle]] Randomly shuffle a list. +Function: random_select_many + +DOC_MSE_VERSION: since 0.3.8 + +--Usage-- +> random_select(some_list, count: some_number, replace: some_boolean) + +Randomly select a number of items from a list. + +By default @count@ ''different'' items are selected (selection without replacment). +Setting the @replace@ parameter allows the same item to occur more than once in the result (selection with replacment). + +Since the result is random, calling the function twice will give a different answer. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:list]] List to shuffle. +| @count@ [[type:int]] Number of items to select. +| @replace@ [[type:boolean]] Select with replacement? + +--Examples-- +> random_select_many([1,2,3,4], count:3) == [2,3,1] +> random_select_many([1,2,3,4], count:3) == [3,1,4] +> random_select_many([1,2,3,4], count:3, replace: true) == [2,3,2] +> random_select_many([1,2,3,4], count:3, replace: false) == [1,3,4] + +--See also-- +| [[fun:random_select]] Pick a single random element from a list. +| [[fun:random_shuffle]] Randomly shuffle a list. diff --git a/doc/function/random_shuffle.txt b/doc/function/random_shuffle.txt index f49c42a7..d2d68bad 100644 --- a/doc/function/random_shuffle.txt +++ b/doc/function/random_shuffle.txt @@ -1,22 +1,22 @@ -Function: random_shuffle - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> random_shuffle(some_list) - -Randomly shuffle a list, putting the elements in a different order. - -Since the result is random, calling the function twice will give a different answer. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:list]] List to shuffle. - ---Examples-- -> random_shuffle([1,2,3,4]) == [4,1,2,3] -> random_shuffle([1,2,3,4]) == [2,3,4,1] - ---See also-- -| [[fun:random_select]] Pick a single random element from a list. -| [[fun:random_select_many]] Pick multiple random elements from a list. +Function: random_shuffle + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> random_shuffle(some_list) + +Randomly shuffle a list, putting the elements in a different order. + +Since the result is random, calling the function twice will give a different answer. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:list]] List to shuffle. + +--Examples-- +> random_shuffle([1,2,3,4]) == [4,1,2,3] +> random_shuffle([1,2,3,4]) == [2,3,4,1] + +--See also-- +| [[fun:random_select]] Pick a single random element from a list. +| [[fun:random_select_many]] Pick multiple random elements from a list. diff --git a/doc/function/recolor_image.txt b/doc/function/recolor_image.txt index 2efa35fa..3410a178 100644 --- a/doc/function/recolor_image.txt +++ b/doc/function/recolor_image.txt @@ -1,41 +1,41 @@ -Function: recolor_image - -DOC_MSE_VERSION: since 0.3.9 - ---Usage-- -> recolor_image(input: image, color: color) -> recolor_image(input: image, red: color, green: color, blue: color, white: color) - -Re-color an image: - * Red is replaced by the color - * Green is replaced by black or white, of the same lightness as the color. - So if the color is light, green will be replaced by white. - * Blue is replaced by black or white, of the opposite lightness. - * White stays white, black stays black - -This function is mostly intended to make symbols in a symbol font wich can match the text color. - - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to recolor. -| @color@ [[type:color]] Color by which to replace red. - -Or -! Parameter Type Description -| @input@ [[type:image]] Image to recolor. -| @red@ [[type:color]] Color by which to replace red. -| @green@ [[type:color]] Color by which to replace green. -| @blue@ [[type:color]] Color by which to replace blue. -| @white@ [[type:color]] Color by which to replace white. - - ---Examples-- -> recolor_image("symbol1.png", color: rgb(180,0,0)) == [[Image]] ->>> recolor_image("symbol1.png", color: rgb(180,0,0)) == "symbol1_red.png" -> recolor_image("symbol1.png", color: rgb(100,255,0)) == [[Image]] ->>> recolor_image("symbol1.png", color: rgb(100,255,0)) == "symbol1_green.png" - -Custom choices for green, blue and white are also possible: ->>> recolor_image("symbol1.png", red:rgb(0,170,0), green:rgb(200,0,255), blue:rgb(128,0,0), white:rgb(220,255,0)) ->>> == "symbol1_recolor_custom.png" +Function: recolor_image + +DOC_MSE_VERSION: since 0.3.9 + +--Usage-- +> recolor_image(input: image, color: color) +> recolor_image(input: image, red: color, green: color, blue: color, white: color) + +Re-color an image: + * Red is replaced by the color + * Green is replaced by black or white, of the same lightness as the color. + So if the color is light, green will be replaced by white. + * Blue is replaced by black or white, of the opposite lightness. + * White stays white, black stays black + +This function is mostly intended to make symbols in a symbol font wich can match the text color. + + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to recolor. +| @color@ [[type:color]] Color by which to replace red. + +Or +! Parameter Type Description +| @input@ [[type:image]] Image to recolor. +| @red@ [[type:color]] Color by which to replace red. +| @green@ [[type:color]] Color by which to replace green. +| @blue@ [[type:color]] Color by which to replace blue. +| @white@ [[type:color]] Color by which to replace white. + + +--Examples-- +> recolor_image("symbol1.png", color: rgb(180,0,0)) == [[Image]] +>>> recolor_image("symbol1.png", color: rgb(180,0,0)) == "symbol1_red.png" +> recolor_image("symbol1.png", color: rgb(100,255,0)) == [[Image]] +>>> recolor_image("symbol1.png", color: rgb(100,255,0)) == "symbol1_green.png" + +Custom choices for green, blue and white are also possible: +>>> recolor_image("symbol1.png", red:rgb(0,170,0), green:rgb(200,0,255), blue:rgb(128,0,0), white:rgb(220,255,0)) +>>> == "symbol1_recolor_custom.png" diff --git a/doc/function/regex_escape.txt b/doc/function/regex_escape.txt index 9f70e380..839f9f42 100644 --- a/doc/function/regex_escape.txt +++ b/doc/function/regex_escape.txt @@ -1,14 +1,14 @@ -Function: regex_escape - ---Usage-- -> regex_escape(some_string) - -Escape a string so it can safely be used in a [[type:regex|regular expression]]. -The regular expression will match the literal string, and nothing else. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to escape. - ---Examples-- -> regex_escape("some(thing)") == "some\\(thing\\)" +Function: regex_escape + +--Usage-- +> regex_escape(some_string) + +Escape a string so it can safely be used in a [[type:regex|regular expression]]. +The regular expression will match the literal string, and nothing else. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to escape. + +--Examples-- +> regex_escape("some(thing)") == "some\\(thing\\)" diff --git a/doc/function/remove_choice.txt b/doc/function/remove_choice.txt index 853ab1eb..fc74c401 100644 --- a/doc/function/remove_choice.txt +++ b/doc/function/remove_choice.txt @@ -1,28 +1,28 @@ -Function: remove_choice - ---Usage-- -> remove_choice(choice: some_strings, some_multiple_choice_value) - -Deselect the given choice(s) from a [[type:value#multiple_choice|multiple choice value]], -returns the new value. - -If a choice is not selected it is ignored. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Multiple choice value to look update. -| @choice@ [[type:string]] Choice to remove. -| @choice1@ [[type:string]] Remove multiple choices. -| @choice2@ [[type:string]] ''etc.'' - ---Examples-- -> remove_choice(choice: "red", "red") == "" -> remove_choice(choice: "red", "blue") == "blue" -> remove_choice(choice: "red", "red, blue") == "blue" -> remove_choice(choice: "blue", "red, blue") == "red" -> remove_choice(choice1: "red", choice2: "green", "red, blue") == "blue" - ---See also-- -| [[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. +Function: remove_choice + +--Usage-- +> remove_choice(choice: some_strings, some_multiple_choice_value) + +Deselect the given choice(s) from a [[type:value#multiple_choice|multiple choice value]], +returns the new value. + +If a choice is not selected it is ignored. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Multiple choice value to look update. +| @choice@ [[type:string]] Choice to remove. +| @choice1@ [[type:string]] Remove multiple choices. +| @choice2@ [[type:string]] ''etc.'' + +--Examples-- +> remove_choice(choice: "red", "red") == "" +> remove_choice(choice: "red", "blue") == "blue" +> remove_choice(choice: "red", "red, blue") == "blue" +> remove_choice(choice: "blue", "red, blue") == "red" +> remove_choice(choice1: "red", choice2: "green", "red, blue") == "blue" + +--See also-- +| [[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. \ No newline at end of file diff --git a/doc/function/remove_tag.txt b/doc/function/remove_tag.txt index 88e47acc..abf0a7e5 100644 --- a/doc/function/remove_tag.txt +++ b/doc/function/remove_tag.txt @@ -1,25 +1,25 @@ -Function: remove_tag - ---Usage-- -> remove_tag(tag: some_tag, some_string) - -Remove a tag and its matching close tag from a [[type:tagged string]], but keep the contents. - -The tag can be a whole tag, @""@, or a prefix @" remove_tag(tag: "", "bold text") == "bold text" -> remove_tag(tag: "bold text") == "bold text" -> -> f := remove_tag@(tag: "") -> f("text, reminder italic") == "text, reminder italic" - ---See also-- -| [[fun:tag_contents]] Change the contents of a specific tag. -| [[fun:remove_tags]] Remove all tags from tagged text. -| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. +Function: remove_tag + +--Usage-- +> remove_tag(tag: some_tag, some_string) + +Remove a tag and its matching close tag from a [[type:tagged string]], but keep the contents. + +The tag can be a whole tag, @""@, or a prefix @" remove_tag(tag: "", "bold text") == "bold text" +> remove_tag(tag: "bold text") == "bold text" +> +> f := remove_tag@(tag: "") +> f("text, reminder italic") == "text, reminder italic" + +--See also-- +| [[fun:tag_contents]] Change the contents of a specific tag. +| [[fun:remove_tags]] Remove all tags from tagged text. +| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. diff --git a/doc/function/remove_tags.txt b/doc/function/remove_tags.txt index 2024183d..3ae4c227 100644 --- a/doc/function/remove_tags.txt +++ b/doc/function/remove_tags.txt @@ -1,20 +1,20 @@ -Function: remove_tags - ---Usage-- -> remove_tags(some_tagged_text) - -Removing all tags from a [[type:tagged string]]. - -This function differs from [[fun:to_text]], that function also un-escapes < characters. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:tagged string]] String to remove tags from - ---Examples-- -> remove_tags("bold text") == "bold text" -> remove_tags("1 \< 2") == "1 \< 2" - ---See also-- -| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. -| [[fun:remove_tag]] Remove a single tag type. +Function: remove_tags + +--Usage-- +> remove_tags(some_tagged_text) + +Removing all tags from a [[type:tagged string]]. + +This function differs from [[fun:to_text]], that function also un-escapes < characters. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:tagged string]] String to remove tags from + +--Examples-- +> remove_tags("bold text") == "bold text" +> remove_tags("1 \< 2") == "1 \< 2" + +--See also-- +| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. +| [[fun:remove_tag]] Remove a single tag type. diff --git a/doc/function/replace.txt b/doc/function/replace.txt index dbab4446..395b1f76 100644 --- a/doc/function/replace.txt +++ b/doc/function/replace.txt @@ -1,40 +1,40 @@ -Function: replace - ---Usage-- -> replace(some_string, match: regular expression, replace: replacement, in_context: regular expression) - -Replace all matches of a regular expression with a replacement value. -The replacement can either be a string or a function. -* The string can contain backreference @"\\0"@, @"\\1"@, etc. refering to the components captured by the parentheses in the regular expression. -* When the replacement is a function, the variable @input@ contains the whole match and @_1@, @_2@, etc. contains the components. - -Optionally a context can be given. The replacement is only performed if the string where the match is represented as <match> also matches the context. - -When the @replace@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments: -> my_replace := replace@(match: "something", replace: "something else") -> my_replace("input") # called many times -This way the regular expression is compiled only once. - -Note: Avoid using @in_context@, since it is quite slow. -Consider using lookahead and lookbehind assertions first if possible. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to replace in. -| @match@ [[type:regex]] Regular expression to match. -| @replace@ [[type:string]] or [[type:function]] - Replacement -| @in_context@ [[type:regex]] (optional) Context to match - ---Examples-- -> replace(match: "a", replace: "e", "banana") == "benene" -> replace(match: "a", replace: "e", in_context: "n", "banana") == "benena" -> replace(match: "(a|b)x", replace: "[\\0,\\1]", "axabxc") == "[ax,a]a[bx,b]c" -> replace(match: "[ab]", replace: to_upper, "banana") == "BAnAnA" -> replace(match: "([0-9])[*]([0-9])", replace: { _1 * _2 }, "2*2+3*3") == "4+9" -> -> f := replace@(match: "xx+", replace: "A") -> f("xyzxxyyzz") == "xyzAAyyzz" - ---See also-- -| [[fun:filter_text]] Keep only the text matching a regular expression. +Function: replace + +--Usage-- +> replace(some_string, match: regular expression, replace: replacement, in_context: regular expression) + +Replace all matches of a regular expression with a replacement value. +The replacement can either be a string or a function. +* The string can contain backreference @"\\0"@, @"\\1"@, etc. refering to the components captured by the parentheses in the regular expression. +* When the replacement is a function, the variable @input@ contains the whole match and @_1@, @_2@, etc. contains the components. + +Optionally a context can be given. The replacement is only performed if the string where the match is represented as <match> also matches the context. + +When the @replace@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments: +> my_replace := replace@(match: "something", replace: "something else") +> my_replace("input") # called many times +This way the regular expression is compiled only once. + +Note: Avoid using @in_context@, since it is quite slow. +Consider using lookahead and lookbehind assertions first if possible. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to replace in. +| @match@ [[type:regex]] Regular expression to match. +| @replace@ [[type:string]] or [[type:function]] + Replacement +| @in_context@ [[type:regex]] (optional) Context to match + +--Examples-- +> replace(match: "a", replace: "e", "banana") == "benene" +> replace(match: "a", replace: "e", in_context: "n", "banana") == "benena" +> replace(match: "(a|b)x", replace: "[\\0,\\1]", "axabxc") == "[ax,a]a[bx,b]c" +> replace(match: "[ab]", replace: to_upper, "banana") == "BAnAnA" +> replace(match: "([0-9])[*]([0-9])", replace: { _1 * _2 }, "2*2+3*3") == "4+9" +> +> f := replace@(match: "xx+", replace: "A") +> f("xyzxxyyzz") == "xyzAAyyzz" + +--See also-- +| [[fun:filter_text]] Keep only the text matching a regular expression. diff --git a/doc/function/require_choice.txt b/doc/function/require_choice.txt index 0c816982..3e321aba 100644 --- a/doc/function/require_choice.txt +++ b/doc/function/require_choice.txt @@ -1,37 +1,37 @@ -Function: require_choice - ---Usage-- -> require_choice(choices: some_strings, some_multiple_choice_value) - -Requre that ''at least one'' of the given choices is selected in a [[type:value#multiple_choice|multiple choice value]]. - -If non of the choices is selected, selects the first one. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Multiple choice value to look update. -| @choices@ [[type:string]] Comma separated list of choices of which one is required. - -For backwards compatability the following form is also supported: - -DOC_MSE_VERSION: until 0.3.6 - -! Parameter Type Description -| @input@ [[type:string]] Multiple choice value to look update. -| @choice@ [[type:string]] Single choice to require. -| @choice1@ [[type:string]] Require multiple choices. -| @choice2@ [[type:string]] ''etc.'' - ---Examples-- -> require_choice(choices: "red", "red") == "red" -> require_choice(choices: "red", "blue") == "blue, red" -> require_choice(choices: "red", "red, blue") == "red, blue" -> require_choice(choices: "red,green", "red, blue") == "red, blue" -> require_choice(choices: "red,green", "red, green") == "red, blue" -> require_choice(choices: "red,green", "green, blue") == "green, blue" -> require_choice(choices: "red,green", "black, blue") == "black, blue, red" - ---See also-- -| [[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. +Function: require_choice + +--Usage-- +> require_choice(choices: some_strings, some_multiple_choice_value) + +Requre that ''at least one'' of the given choices is selected in a [[type:value#multiple_choice|multiple choice value]]. + +If non of the choices is selected, selects the first one. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Multiple choice value to look update. +| @choices@ [[type:string]] Comma separated list of choices of which one is required. + +For backwards compatability the following form is also supported: + +DOC_MSE_VERSION: until 0.3.6 + +! Parameter Type Description +| @input@ [[type:string]] Multiple choice value to look update. +| @choice@ [[type:string]] Single choice to require. +| @choice1@ [[type:string]] Require multiple choices. +| @choice2@ [[type:string]] ''etc.'' + +--Examples-- +> require_choice(choices: "red", "red") == "red" +> require_choice(choices: "red", "blue") == "blue, red" +> require_choice(choices: "red", "red, blue") == "red, blue" +> require_choice(choices: "red,green", "red, blue") == "red, blue" +> require_choice(choices: "red,green", "red, green") == "red, blue" +> require_choice(choices: "red,green", "green, blue") == "green, blue" +> require_choice(choices: "red,green", "black, blue") == "black, blue, red" + +--See also-- +| [[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. diff --git a/doc/function/require_exclusive_choice.txt b/doc/function/require_exclusive_choice.txt index 151f040b..c7ad137d 100644 --- a/doc/function/require_exclusive_choice.txt +++ b/doc/function/require_exclusive_choice.txt @@ -1,26 +1,26 @@ -Function: require_exclusive_choice - ---Usage-- ->>> require_exclusive_choice(choices some_strings, some_multiple_choice_value) - -Requre that ''exacttly one'' of the given choices is selected in a [[type:value#multiple_choice|multiple choice value]]. - -This is a combination of [[fun:require_choice]] and [[fun:exclusive_choice]]. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Multiple choice value to look update. -| @choice@ [[type:string]] Choice to require. -| @choice1@ [[type:string]] Require multiple choices. -| @choice2@ [[type:string]] ''etc.'' - ---Examples-- -> require_exclusive_choice(choice1: "red", choice2: "green", "red, blue") == "red, blue" -> require_exclusive_choice(choice1: "red", choice2: "green", "red, green") == "red" -> require_exclusive_choice(choice1: "red", choice2: "green", "green, blue") == "green, blue" -> require_exclusive_choice(choice1: "red", choice2: "green", "black, blue") == "black, blue, red" - ---See also-- -| [[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:remove_choice]] Remove the given choices from a multiple choice value. +Function: require_exclusive_choice + +--Usage-- +>>> require_exclusive_choice(choices some_strings, some_multiple_choice_value) + +Requre that ''exacttly one'' of the given choices is selected in a [[type:value#multiple_choice|multiple choice value]]. + +This is a combination of [[fun:require_choice]] and [[fun:exclusive_choice]]. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Multiple choice value to look update. +| @choice@ [[type:string]] Choice to require. +| @choice1@ [[type:string]] Require multiple choices. +| @choice2@ [[type:string]] ''etc.'' + +--Examples-- +> require_exclusive_choice(choice1: "red", choice2: "green", "red, blue") == "red, blue" +> require_exclusive_choice(choice1: "red", choice2: "green", "red, green") == "red" +> require_exclusive_choice(choice1: "red", choice2: "green", "green, blue") == "green, blue" +> require_exclusive_choice(choice1: "red", choice2: "green", "black, blue") == "black, blue, red" + +--See also-- +| [[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:remove_choice]] Remove the given choices from a multiple choice value. diff --git a/doc/function/reverse.txt b/doc/function/reverse.txt index bd5d047f..dc0320d7 100644 --- a/doc/function/reverse.txt +++ b/doc/function/reverse.txt @@ -1,13 +1,13 @@ -Function: reverse - ---Usage-- -> reverse(some_string) - -Reverse a string. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to reverse. - ---Examples-- -> reverse("abc") == "cba" +Function: reverse + +--Usage-- +> reverse(some_string) + +Reverse a string. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to reverse. + +--Examples-- +> reverse("abc") == "cba" diff --git a/doc/function/rotate.txt b/doc/function/rotate.txt index 5c36edc9..335c2f4e 100644 --- a/doc/function/rotate.txt +++ b/doc/function/rotate.txt @@ -1,21 +1,21 @@ -Function: rotate - -DOC_MSE_VERSION: since 0.3.9 - ---Usage-- -> rotate(input: image, angle: some_number) - -Rotate an image. The image can become larger to accomodate the rotated bounding box. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to rotate. -| @angle@ [[type:double]] Angle to rotate by, in degrees counter clockwise. - ---Examples-- -> rotate("image_logo.png", angle:30) == [[Image]] ->>> rotate("image_logo.png", angle:30) == "image_logo_rotate30.png" - ---See also-- -| [[fun:flip_horizontal]] Flip an image horizontally -| [[fun:flip_vertical]] Flip an image vertically +Function: rotate + +DOC_MSE_VERSION: since 0.3.9 + +--Usage-- +> rotate(input: image, angle: some_number) + +Rotate an image. The image can become larger to accomodate the rotated bounding box. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to rotate. +| @angle@ [[type:double]] Angle to rotate by, in degrees counter clockwise. + +--Examples-- +> rotate("image_logo.png", angle:30) == [[Image]] +>>> rotate("image_logo.png", angle:30) == "image_logo_rotate30.png" + +--See also-- +| [[fun:flip_horizontal]] Flip an image horizontally +| [[fun:flip_vertical]] Flip an image vertically diff --git a/doc/function/saturate.txt b/doc/function/saturate.txt index 1895bcc4..781e91ad 100644 --- a/doc/function/saturate.txt +++ b/doc/function/saturate.txt @@ -1,25 +1,25 @@ -Function: saturate - -DOC_MSE_VERSION: since 0.3.9 - ---Usage-- -> saturate(input: image, amount: saturation amount) - -Saturate or desaturate an image. Saturation makes the colors brighter, desaturation makes the image more grey. - -To saturate use an amount between @0@ (no saturation) and @1@ (super crazy, too much saturation). - -To desaturate use an amount between @0@ (no desaturation) and @-1@ (convert to greyscale). - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to (de)saturate. -| @alpha@ [[type:double]] Saturation factor. - ---Examples-- -> saturate("image5.png", amount: 0.5) == [[Image]] ->>> saturate("image5.png", amount: 0.5) == "image_saturate1.png" -> saturate("image5.png", amount: -0.5) == [[Image]] ->>> saturate("image5.png", amount: -0.5) == "image_saturate2.png" -> saturate("image_logo.png", amount: -1) == [[Image]] ->>> saturate("image_logo.png", amount: -1) == "image_logo_desaturate.png" +Function: saturate + +DOC_MSE_VERSION: since 0.3.9 + +--Usage-- +> saturate(input: image, amount: saturation amount) + +Saturate or desaturate an image. Saturation makes the colors brighter, desaturation makes the image more grey. + +To saturate use an amount between @0@ (no saturation) and @1@ (super crazy, too much saturation). + +To desaturate use an amount between @0@ (no desaturation) and @-1@ (convert to greyscale). + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to (de)saturate. +| @alpha@ [[type:double]] Saturation factor. + +--Examples-- +> saturate("image5.png", amount: 0.5) == [[Image]] +>>> saturate("image5.png", amount: 0.5) == "image_saturate1.png" +> saturate("image5.png", amount: -0.5) == [[Image]] +>>> saturate("image5.png", amount: -0.5) == "image_saturate2.png" +> saturate("image_logo.png", amount: -1) == [[Image]] +>>> saturate("image_logo.png", amount: -1) == "image_logo_desaturate.png" diff --git a/doc/function/set_alpha.txt b/doc/function/set_alpha.txt index 3305646e..e6b603fb 100644 --- a/doc/function/set_alpha.txt +++ b/doc/function/set_alpha.txt @@ -1,21 +1,21 @@ -Function: set_alpha - ---Usage-- -> set_alpha(input: image, alpha: transparency value) - -Make an image more transparent. - -The transprarency is multiplied by @alpha@. -If @alpha@ is 1 the image stays the same, if @alpha@ is 0 the image becomes completely transprent. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to make transparent. -| @alpha@ [[type:double]] Transparency factor. - ---Examples-- -> set_alpha("image1.png", alpha: 0.5) == [[Image]] ->>> set_alpha("image1.png", alpha: 0.5) == "image_set_alpha.png" - ---See also-- -| [[fun:set_mask]] Set the transparancy mask of an image. +Function: set_alpha + +--Usage-- +> set_alpha(input: image, alpha: transparency value) + +Make an image more transparent. + +The transprarency is multiplied by @alpha@. +If @alpha@ is 1 the image stays the same, if @alpha@ is 0 the image becomes completely transprent. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to make transparent. +| @alpha@ [[type:double]] Transparency factor. + +--Examples-- +> set_alpha("image1.png", alpha: 0.5) == [[Image]] +>>> set_alpha("image1.png", alpha: 0.5) == "image_set_alpha.png" + +--See also-- +| [[fun:set_mask]] Set the transparancy mask of an image. diff --git a/doc/function/set_combine.txt b/doc/function/set_combine.txt index 0208ec19..4f69177a 100644 --- a/doc/function/set_combine.txt +++ b/doc/function/set_combine.txt @@ -1,17 +1,17 @@ -Function: set_combine - ---Usage-- -> set_combine(input: image, combine: combine_mode) - -Set how the resulting image should be combined with the background. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to change combining mode of -| @combine@ [[type:combine]] Combining function to use - ---Examples-- -> set_combine(input: "image1.png", combine: "shadow") == [[Image]] - ---See also-- -| [[fun:combine_blend]] Blend two images together using a given [[type:combine|combining mode]]. +Function: set_combine + +--Usage-- +> set_combine(input: image, combine: combine_mode) + +Set how the resulting image should be combined with the background. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to change combining mode of +| @combine@ [[type:combine]] Combining function to use + +--Examples-- +> set_combine(input: "image1.png", combine: "shadow") == [[Image]] + +--See also-- +| [[fun:combine_blend]] Blend two images together using a given [[type:combine|combining mode]]. diff --git a/doc/function/set_mask.txt b/doc/function/set_mask.txt index 340ac8cb..77a58b67 100644 --- a/doc/function/set_mask.txt +++ b/doc/function/set_mask.txt @@ -1,21 +1,21 @@ -Function: set_mask - ---Usage-- -> set_mask(image: image, mask: mask_image) - -Make parts of an image (more) transparent using a mask. -Black areas in the mask make the image transparent, white areas stay opaque. - -The images must have the same size. - ---Parameters-- -! Parameter Type Description -| @image@ [[type:image]] Image to apply the mask to -| @mask@ [[type:image]] Mask image. - ---Examples-- -> set_mask(image: "image1.png", mask: "image3.png") == [[Image]] ->>> set_mask(image: "image1.png", mask: "image3.png") == "image_set_mask.png" - ---See also-- -| [[fun:set_alpha]] Change the transparency of an image. +Function: set_mask + +--Usage-- +> set_mask(image: image, mask: mask_image) + +Make parts of an image (more) transparent using a mask. +Black areas in the mask make the image transparent, white areas stay opaque. + +The images must have the same size. + +--Parameters-- +! Parameter Type Description +| @image@ [[type:image]] Image to apply the mask to +| @mask@ [[type:image]] Mask image. + +--Examples-- +> set_mask(image: "image1.png", mask: "image3.png") == [[Image]] +>>> set_mask(image: "image1.png", mask: "image3.png") == "image_set_mask.png" + +--See also-- +| [[fun:set_alpha]] Change the transparency of an image. diff --git a/doc/function/sort_list.txt b/doc/function/sort_list.txt index 426489c0..91089583 100644 --- a/doc/function/sort_list.txt +++ b/doc/function/sort_list.txt @@ -1,21 +1,21 @@ -Function: sort_list - ---Usage-- -> sort_list(some_list, order_by: some_function) - -Order the elements in a list in lexicographical order, from smallest to largest. -Optionally order by some other property. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:list]] or [[type:set]] List to sort. -| @order_by@ [[type:function]] (optional) Function to order by, for example when @order_by: {input.name}@ orders items by their name property. -| @remove_duplicates@ [[type:boolean]] DOC_MSE_VERSION: since 0.3.7 - If @true@, keep only one copy of duplicate elements. - ---Examples-- -> sort_list([5,2,3,1,4]) == [1,2,3,4,5] -> sort_list(["aaa","cccc","bb"]) == ["aaa","bb","cccc"] -> sort_list(["aaa","cccc","bb"], order_by: length) -> == ["bb","aaa","cccc"] -> sort_list([1,2,1,2,2,3], remove_duplicates:true) == [1,2,3] +Function: sort_list + +--Usage-- +> sort_list(some_list, order_by: some_function) + +Order the elements in a list in lexicographical order, from smallest to largest. +Optionally order by some other property. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:list]] or [[type:set]] List to sort. +| @order_by@ [[type:function]] (optional) Function to order by, for example when @order_by: {input.name}@ orders items by their name property. +| @remove_duplicates@ [[type:boolean]] DOC_MSE_VERSION: since 0.3.7 + If @true@, keep only one copy of duplicate elements. + +--Examples-- +> sort_list([5,2,3,1,4]) == [1,2,3,4,5] +> sort_list(["aaa","cccc","bb"]) == ["aaa","bb","cccc"] +> sort_list(["aaa","cccc","bb"], order_by: length) +> == ["bb","aaa","cccc"] +> sort_list([1,2,1,2,2,3], remove_duplicates:true) == [1,2,3] diff --git a/doc/function/sort_text.txt b/doc/function/sort_text.txt index 432572a2..e8bdf741 100644 --- a/doc/function/sort_text.txt +++ b/doc/function/sort_text.txt @@ -1,68 +1,68 @@ -Function: sort_text - ---Usage-- -> sort_text(order: order specification, some_text) - -Sort a string or filter it by keeping specific characters. - -When the @order@ parameter is not given, the input is sorted in alphabetical order. - -Otherwise the @order@ parameter determines what characters to show in the output. -The @order@ is a string consisting of multiple ''parts'', each part selects a specific thing from the input. -Parts -! Part sort("zzyyxxy") Description -| @"x"@ @"xx"@ A normal character, selects all matching characters from the input -| @" "@ @""@ Whitespace is ignored. -| @"\\<"@ @""@ Characters can be escaped with a backslash, normally the character @"<"@ has special behaviour. - Note that you also need to escape the backslash for the [[type:string]]. -| @""@ @"xy"@ Selects the characters from the input, but only once. - @""@ is the same as @""@. -| @"[wxy]"@ @"yyyxx"@ Selects the given characters, but keep them in the same order as in the input. -| @"(xwz)"@ @"zzxx"@ The same as @"cycle(xyz)"@. -| @"ordered(wxy)"@ @"xxyyy"@ The same as just @"wxy"@. -| @"once(wxy)"@ @"xy"@ The same as @""@. -| @"mixed(wxy)"@ @"yyyxx"@ The same as @"[wxy]"@. -| @"compound(yx)"@ @"yx"@ Selects the literal substring @"xy"@ only where it matches exactly. Selects it as many times as it appears -| @"any()"@ @"zzyyxxy"@ Selects the remaining part of the input. -| @"cycle(xwz)"@ @"zzxx"@ Selects the given characters, and put them in the order that minimizes the distance. - around a 'circle'. Imagine w x and y in a circle, then "zx" is shorter then "x.z" because the latter passes the "w" space. - This sorting option is used to sort colored mana symbols in Magic. -| @"reverse_order(x y)"@ @"yyyxx"@ Inside the parentheses can be multiple parts (that can again include part-functions). - @"reverse_order(x y)"@ is ''not'' the same as just @"y x"@, because in the first case x is evaluated first. - For example @"x compound(xy)"@ doesn't work, because the xs are all matched by the time the compound part is evaluated. - So instead you can use @"reverse_order(compound(xy) x)"@. -| @"pattern(.z. xyz)"@ @"yzz"@ Selects all things that match the pattern, where @"."@ is a wildcard. - The things matching the wildcards are then sorted using the given pattern (separated by a space), and subsituted back in. - So in "zzyyxxy" the pattern matches "zzyxxy" with wildcards "zy" these sort as "yz" and in the pattern this becomes "yzz". -| @"in_place(yz)"@ @"yyyzxxz"@ Sort everything with the given pattern, and insert the remaining characters in their orignal places.
- For example, in @"zzyyxxy"@ we match y and z, leaving @"....xx."@. - The result of the pattern is @"yyyzz"@, subsituting that back in gives @"yyyzxxz"@. - -The parts are read from left to right, each part that matches something removes it from the input, so for example -> sort_text(order: "xx") -behaves the same as -> sort_text(order: "x") -because the first @"x"@ already selects all xs from the input. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Text to sort -| @order@ [[type:string]] (optional) Order specification - ---Examples-- -> sort_text("banana") == "aaabnn" -> sort_text(order: "na", "banana") == "nnaaa" -> sort_text(order: "n a", "banana") == "nnaaa" -> sort_text(order: "", "banana") == "na" -> sort_text(order: "once(na)", "banana") == "na" -> sort_text(order: "[na]", "banana") == "anana" -> sort_text(order: "mixed(na)", "banana") == "anana" -> sort_text(order: "compound(na)", "banana") == "nana" -> sort_text(order: "reverse_order(na)", "banana") == "aaann" -> sort_text(order: "a n ", "banana") == "aaann" -> sort_text(order: "reverse_order( n a)", "banana") == "aanna" -> sort_text(order: "pattern(./. cycle(wubrg))", "wgw/g") == "g/w" -> sort_text(order: "[1234567890]cycle(wubrg)", "21wg") == "21gw" -> -> f := sort_text@(order: "[1234567890]cycle(wubrg)") -> f("21wg") == "21gw" +Function: sort_text + +--Usage-- +> sort_text(order: order specification, some_text) + +Sort a string or filter it by keeping specific characters. + +When the @order@ parameter is not given, the input is sorted in alphabetical order. + +Otherwise the @order@ parameter determines what characters to show in the output. +The @order@ is a string consisting of multiple ''parts'', each part selects a specific thing from the input. +Parts +! Part sort("zzyyxxy") Description +| @"x"@ @"xx"@ A normal character, selects all matching characters from the input +| @" "@ @""@ Whitespace is ignored. +| @"\\<"@ @""@ Characters can be escaped with a backslash, normally the character @"<"@ has special behaviour. + Note that you also need to escape the backslash for the [[type:string]]. +| @""@ @"xy"@ Selects the characters from the input, but only once. + @""@ is the same as @""@. +| @"[wxy]"@ @"yyyxx"@ Selects the given characters, but keep them in the same order as in the input. +| @"(xwz)"@ @"zzxx"@ The same as @"cycle(xyz)"@. +| @"ordered(wxy)"@ @"xxyyy"@ The same as just @"wxy"@. +| @"once(wxy)"@ @"xy"@ The same as @""@. +| @"mixed(wxy)"@ @"yyyxx"@ The same as @"[wxy]"@. +| @"compound(yx)"@ @"yx"@ Selects the literal substring @"xy"@ only where it matches exactly. Selects it as many times as it appears +| @"any()"@ @"zzyyxxy"@ Selects the remaining part of the input. +| @"cycle(xwz)"@ @"zzxx"@ Selects the given characters, and put them in the order that minimizes the distance. + around a 'circle'. Imagine w x and y in a circle, then "zx" is shorter then "x.z" because the latter passes the "w" space. + This sorting option is used to sort colored mana symbols in Magic. +| @"reverse_order(x y)"@ @"yyyxx"@ Inside the parentheses can be multiple parts (that can again include part-functions). + @"reverse_order(x y)"@ is ''not'' the same as just @"y x"@, because in the first case x is evaluated first. + For example @"x compound(xy)"@ doesn't work, because the xs are all matched by the time the compound part is evaluated. + So instead you can use @"reverse_order(compound(xy) x)"@. +| @"pattern(.z. xyz)"@ @"yzz"@ Selects all things that match the pattern, where @"."@ is a wildcard. + The things matching the wildcards are then sorted using the given pattern (separated by a space), and subsituted back in. + So in "zzyyxxy" the pattern matches "zzyxxy" with wildcards "zy" these sort as "yz" and in the pattern this becomes "yzz". +| @"in_place(yz)"@ @"yyyzxxz"@ Sort everything with the given pattern, and insert the remaining characters in their orignal places.
+ For example, in @"zzyyxxy"@ we match y and z, leaving @"....xx."@. + The result of the pattern is @"yyyzz"@, subsituting that back in gives @"yyyzxxz"@. + +The parts are read from left to right, each part that matches something removes it from the input, so for example +> sort_text(order: "xx") +behaves the same as +> sort_text(order: "x") +because the first @"x"@ already selects all xs from the input. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Text to sort +| @order@ [[type:string]] (optional) Order specification + +--Examples-- +> sort_text("banana") == "aaabnn" +> sort_text(order: "na", "banana") == "nnaaa" +> sort_text(order: "n a", "banana") == "nnaaa" +> sort_text(order: "", "banana") == "na" +> sort_text(order: "once(na)", "banana") == "na" +> sort_text(order: "[na]", "banana") == "anana" +> sort_text(order: "mixed(na)", "banana") == "anana" +> sort_text(order: "compound(na)", "banana") == "nana" +> sort_text(order: "reverse_order(na)", "banana") == "aaann" +> sort_text(order: "a n
", "banana") == "aaann" +> sort_text(order: "reverse_order( n a)", "banana") == "aanna" +> sort_text(order: "pattern(./. cycle(wubrg))", "wgw/g") == "g/w" +> sort_text(order: "[1234567890]cycle(wubrg)", "21wg") == "21gw" +> +> f := sort_text@(order: "[1234567890]cycle(wubrg)") +> f("21wg") == "21gw" diff --git a/doc/function/split_text.txt b/doc/function/split_text.txt index fc39ed1a..064ca9b5 100644 --- a/doc/function/split_text.txt +++ b/doc/function/split_text.txt @@ -1,41 +1,41 @@ -Function: split_text - -DOC_MSE_VERSION: since 0.3.8 - ---Usage-- -> split_text(some_string, match: regular expression, in_context: regular expression) - -Split text by keeping the parts between separators matching a regular expression. -The function returns a [[type:list]] of parts. - -When the @split_text@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments: -> my_break := split_text@(match: ",") -> my_break("a,b,c") # called many times -This way the regular expression is only compiled once. - ---Split vs. break-- - -The function @break_text@ does the opposite of @split_text@, keeping the parts mathing the regular expression, instead of the parts between it. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to replace in. -| @match@ [[type:regex]] Regular expression to match. -| @include_empty@ [[type:boolean]] (default: @true@) If set to @false@, remove all empty parts - ---Examples-- -> split_text(match: ",", "ab,cd,,ef") == ["ab","cd","","ef"] -> split_text(match: ",", "ab,cd,,ef", include_empty:false) == ["ab","cd","ef"] -> split_text(match: "a", "banana") == ["b","n","n",""] -> break_text(match: "a", "banana") == ["a","a","a"] - ---See also-- -| [[fun:break_text]] Break text into parts each matching a regular expression. - -For working with comma separated lists, such as those from multiple choice fields, there are special functions: -| [[fun:chosen]] Is the given choice selected in a multiple choice value? -| [[fun:count_chosen]] Count then number of choices 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. +Function: split_text + +DOC_MSE_VERSION: since 0.3.8 + +--Usage-- +> split_text(some_string, match: regular expression, in_context: regular expression) + +Split text by keeping the parts between separators matching a regular expression. +The function returns a [[type:list]] of parts. + +When the @split_text@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments: +> my_break := split_text@(match: ",") +> my_break("a,b,c") # called many times +This way the regular expression is only compiled once. + +--Split vs. break-- + +The function @break_text@ does the opposite of @split_text@, keeping the parts mathing the regular expression, instead of the parts between it. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to replace in. +| @match@ [[type:regex]] Regular expression to match. +| @include_empty@ [[type:boolean]] (default: @true@) If set to @false@, remove all empty parts + +--Examples-- +> split_text(match: ",", "ab,cd,,ef") == ["ab","cd","","ef"] +> split_text(match: ",", "ab,cd,,ef", include_empty:false) == ["ab","cd","ef"] +> split_text(match: "a", "banana") == ["b","n","n",""] +> break_text(match: "a", "banana") == ["a","a","a"] + +--See also-- +| [[fun:break_text]] Break text into parts each matching a regular expression. + +For working with comma separated lists, such as those from multiple choice fields, there are special functions: +| [[fun:chosen]] Is the given choice selected in a multiple choice value? +| [[fun:count_chosen]] Count then number of choices 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. diff --git a/doc/function/substring.txt b/doc/function/substring.txt index f3e0e814..456ce3fd 100644 --- a/doc/function/substring.txt +++ b/doc/function/substring.txt @@ -1,20 +1,20 @@ -Function: substring - ---Usage-- -> substring(some_string, begin: number, end: number) - -Extract a subsection of a string. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to extract something from. -| @begin@ [[type:int]] (optional) Index of first character to keep (the first index is 0). - If ommitted, starts at the begining of the string. -| @end@ [[type:int]] (optional) Index just beyond the last character to keep. - If ommitted, runs to the end of the string. - ---Examples-- -> substring("abcdefg", end:2) == "ab" -> substring("abcdefg", begin:2) == "cdefg" -> substring("abcdefg", begin:2, end:4) == "cd" -> substring("abcdefg", begin:2, end:2) == "" +Function: substring + +--Usage-- +> substring(some_string, begin: number, end: number) + +Extract a subsection of a string. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to extract something from. +| @begin@ [[type:int]] (optional) Index of first character to keep (the first index is 0). + If ommitted, starts at the begining of the string. +| @end@ [[type:int]] (optional) Index just beyond the last character to keep. + If ommitted, runs to the end of the string. + +--Examples-- +> substring("abcdefg", end:2) == "ab" +> substring("abcdefg", begin:2) == "cdefg" +> substring("abcdefg", begin:2, end:4) == "cd" +> substring("abcdefg", begin:2, end:2) == "" diff --git a/doc/function/symbol_variation.txt b/doc/function/symbol_variation.txt index c17bf60b..90df1ed0 100644 --- a/doc/function/symbol_variation.txt +++ b/doc/function/symbol_variation.txt @@ -1,53 +1,53 @@ -Function: symbol_variation - ---Usage-- -> symbol_variation(symbol: symbol_value, variation: name_of_variation) - -Render a [[type:symbol variation|variation]] of a symbol. -The variation name refers to one of the variations declared in the [[type:style]] of the symbol field. - -> symbol_variation(symbol: symbol_value, border_radius: .., fill_type: .., ...) - -Render a custom variation of a symbol. -Additional parameters corresponding to the properties of a [[type:symbol variation]] must be present. - ---Parameters-- -! Parameter Type Description -| @symbol@ [[type:value#symbol|symbol value]] Symbol to render. -| @variation@ [[type:string]] Name of the variation to use. - -or - -! Parameter Type Description -| @symbol@ [[type:value#symbol|symbol value]] Symbol to render. -| @border_radius@ [[type:double]] Border radius of the symbol. -| @fill_type@ @"solid"@ (default) Use the solid fill type, this is the default. -| @fill_color@ [[type:color]] Color to use for filling the symbol. -| @border_color@ [[type:color]] Color to use for the border of the symbol. - -or - -! Parameter Type Description -| @symbol@ [[type:value#symbol|symbol value]] Symbol to render. -| @border_radius@ [[type:double]] Border radius of the symbol. -| @fill_type@ @"linear gradient"@ Use the linear gradient fill type. -| @fill_color_1@ [[type:color]] Color to use for filling the symbol at the center of the gradient. -| @border_color_1@ [[type:color]] Color to use for the border of the symbol at the center of the gradient. -| @fill_color_2@ [[type:color]] Color to use for filling the symbol at the ends of the gradient. -| @border_color_2@ [[type:color]] Color to use for the border of the symbol at the ends of the gradient. -| @center_x@, @center_y@ [[type:double]] Position of the center point of the gradient (in the range 0 to 1) -| @end_x@, @end_y@ [[type:double]] Position of the end point of the gradient (in the range 0 to 1) - -or - -! Parameter Type Description -| @symbol@ [[type:value#symbol|symbol value]] Symbol to render. -| @border_radius@ [[type:double]] Border radius of the symbol. -| @fill_type@ @"radial gradient"@ Use the radial gradient fill type. -| @fill_color_1@ [[type:color]] Color to use for filling the symbol at the center of the symbol. -| @border_color_1@ [[type:color]] Color to use for the border of the symbol at the center of the symbol. -| @fill_color_2@ [[type:color]] Color to use for filling the symbol at the edges of the symbol. -| @border_color_2@ [[type:color]] Color to use for the border of the symbol at the edges of the symbol. - ---Examples-- -> symbol_variation(symbol: set.set_symbol, variation: "common") == [[Image]] +Function: symbol_variation + +--Usage-- +> symbol_variation(symbol: symbol_value, variation: name_of_variation) + +Render a [[type:symbol variation|variation]] of a symbol. +The variation name refers to one of the variations declared in the [[type:style]] of the symbol field. + +> symbol_variation(symbol: symbol_value, border_radius: .., fill_type: .., ...) + +Render a custom variation of a symbol. +Additional parameters corresponding to the properties of a [[type:symbol variation]] must be present. + +--Parameters-- +! Parameter Type Description +| @symbol@ [[type:value#symbol|symbol value]] Symbol to render. +| @variation@ [[type:string]] Name of the variation to use. + +or + +! Parameter Type Description +| @symbol@ [[type:value#symbol|symbol value]] Symbol to render. +| @border_radius@ [[type:double]] Border radius of the symbol. +| @fill_type@ @"solid"@ (default) Use the solid fill type, this is the default. +| @fill_color@ [[type:color]] Color to use for filling the symbol. +| @border_color@ [[type:color]] Color to use for the border of the symbol. + +or + +! Parameter Type Description +| @symbol@ [[type:value#symbol|symbol value]] Symbol to render. +| @border_radius@ [[type:double]] Border radius of the symbol. +| @fill_type@ @"linear gradient"@ Use the linear gradient fill type. +| @fill_color_1@ [[type:color]] Color to use for filling the symbol at the center of the gradient. +| @border_color_1@ [[type:color]] Color to use for the border of the symbol at the center of the gradient. +| @fill_color_2@ [[type:color]] Color to use for filling the symbol at the ends of the gradient. +| @border_color_2@ [[type:color]] Color to use for the border of the symbol at the ends of the gradient. +| @center_x@, @center_y@ [[type:double]] Position of the center point of the gradient (in the range 0 to 1) +| @end_x@, @end_y@ [[type:double]] Position of the end point of the gradient (in the range 0 to 1) + +or + +! Parameter Type Description +| @symbol@ [[type:value#symbol|symbol value]] Symbol to render. +| @border_radius@ [[type:double]] Border radius of the symbol. +| @fill_type@ @"radial gradient"@ Use the radial gradient fill type. +| @fill_color_1@ [[type:color]] Color to use for filling the symbol at the center of the symbol. +| @border_color_1@ [[type:color]] Color to use for the border of the symbol at the center of the symbol. +| @fill_color_2@ [[type:color]] Color to use for filling the symbol at the edges of the symbol. +| @border_color_2@ [[type:color]] Color to use for the border of the symbol at the edges of the symbol. + +--Examples-- +> symbol_variation(symbol: set.set_symbol, variation: "common") == [[Image]] diff --git a/doc/function/symbols_to_html.txt b/doc/function/symbols_to_html.txt index fd95d579..dc95d194 100644 --- a/doc/function/symbols_to_html.txt +++ b/doc/function/symbols_to_html.txt @@ -1,22 +1,22 @@ -Function: symbols_to_html - ---Usage-- -> symbols_to_html(some_tagged_text) - -Convert a [[type:tagged string]] to HTML code for use in web pages, entirely using a symbol font. -This is intended for fields with @always symbol:true@. - -This function can only be used in an [[type:export template]], when create directory is true, as the images -of the font are written to the output directory. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:tagged string]] String to convert to html -| @symbol_font@ [[type:string]] Name of a symbol font to use. -| @symbol_font_size@ [[type:double]] (optional) Size in points to use for the symbol font, default 12 - ---Examples-- -> symbols_to_html("WU") == "WU" - ---See also-- -| [[fun:to_html]] Convert [[type:tagged text]] to html. +Function: symbols_to_html + +--Usage-- +> symbols_to_html(some_tagged_text) + +Convert a [[type:tagged string]] to HTML code for use in web pages, entirely using a symbol font. +This is intended for fields with @always symbol:true@. + +This function can only be used in an [[type:export template]], when create directory is true, as the images +of the font are written to the output directory. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:tagged string]] String to convert to html +| @symbol_font@ [[type:string]] Name of a symbol font to use. +| @symbol_font_size@ [[type:double]] (optional) Size in points to use for the symbol font, default 12 + +--Examples-- +> symbols_to_html("WU") == "WU" + +--See also-- +| [[fun:to_html]] Convert [[type:tagged text]] to html. diff --git a/doc/function/tag_contents.txt b/doc/function/tag_contents.txt index 621105e8..9ec2a935 100644 --- a/doc/function/tag_contents.txt +++ b/doc/function/tag_contents.txt @@ -1,27 +1,27 @@ -Function: tag_contents - ---Usage-- -> tag_contents(tag: some_tag, contents: some_function, some_string) - -Apply a function to the contents of a particular tag. -The function is called with @input@ set to the old value inside the tag. - -The tag can be a whole tag, @""@, or a prefix @" tag_contents(tag: "", contents: to_upper, "this is text") -> == "this IS TEXT" -> tag_contents(tag: " loses 1 life") -> == "Pink Elephant loses 1 life" -> -> f := tag_contents@(tag: "", contents: {""}) -> f("text, reminder italic") == "text, reminder " - ---See also-- -| [[fun:remove_tag]] Remove a tag, keep the contents. +Function: tag_contents + +--Usage-- +> tag_contents(tag: some_tag, contents: some_function, some_string) + +Apply a function to the contents of a particular tag. +The function is called with @input@ set to the old value inside the tag. + +The tag can be a whole tag, @""@, or a prefix @" tag_contents(tag: "", contents: to_upper, "this is text") +> == "this IS TEXT" +> tag_contents(tag: " loses 1 life") +> == "Pink Elephant loses 1 life" +> +> f := tag_contents@(tag: "", contents: {""}) +> f("text, reminder italic") == "text, reminder " + +--See also-- +| [[fun:remove_tag]] Remove a tag, keep the contents. diff --git a/doc/function/to_boolean.txt b/doc/function/to_boolean.txt index c14eb604..49ce2954 100644 --- a/doc/function/to_boolean.txt +++ b/doc/function/to_boolean.txt @@ -1,20 +1,20 @@ -Function: to_boolean - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> to_boolean(any value) - -Convert any value to a [[type:boolean]] representation. - -Normally numbers are not converted to booleans automatically, with the to_boolean function @0@ is converted to @false@ while any other number is converted to @true@. - ---Parameters-- -! Parameter Type Description -| @input@ ''any type'' Value to convert to a boolean. - ---Examples-- -> to_boolean(true) == true -> to_boolean("true") == true -> to_boolean(1) == true -> to_boolean(0) == false +Function: to_boolean + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> to_boolean(any value) + +Convert any value to a [[type:boolean]] representation. + +Normally numbers are not converted to booleans automatically, with the to_boolean function @0@ is converted to @false@ while any other number is converted to @true@. + +--Parameters-- +! Parameter Type Description +| @input@ ''any type'' Value to convert to a boolean. + +--Examples-- +> to_boolean(true) == true +> to_boolean("true") == true +> to_boolean(1) == true +> to_boolean(0) == false diff --git a/doc/function/to_color.txt b/doc/function/to_color.txt index bdfd2655..ef4af37e 100644 --- a/doc/function/to_color.txt +++ b/doc/function/to_color.txt @@ -1,16 +1,16 @@ -Function: to_color - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> to_color(any value) - -Convert any value to a [[type:color]]. - ---Parameters-- -! Parameter Type Description -| @input@ ''any type'' Value to convert to a color - ---Examples-- -> to_color("red") == rgb(255,0,0) - +Function: to_color + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> to_color(any value) + +Convert any value to a [[type:color]]. + +--Parameters-- +! Parameter Type Description +| @input@ ''any type'' Value to convert to a color + +--Examples-- +> to_color("red") == rgb(255,0,0) + diff --git a/doc/function/to_date.txt b/doc/function/to_date.txt index 8b29d7b9..076eeeb7 100644 --- a/doc/function/to_date.txt +++ b/doc/function/to_date.txt @@ -1,19 +1,19 @@ -Function: to_date - -DOC_MSE_VERSION: since 0.3.8 - ---Usage-- -> to_date(any value) - -Convert a string value to a [[type:date]]. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Value to convert to a date. - ---Examples-- -> to_date("2008-12-31 23:59:59") -> to_date("today midnight") - ---See also-- -| [[fun:to_string]] Convert dates to strings +Function: to_date + +DOC_MSE_VERSION: since 0.3.8 + +--Usage-- +> to_date(any value) + +Convert a string value to a [[type:date]]. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Value to convert to a date. + +--Examples-- +> to_date("2008-12-31 23:59:59") +> to_date("today midnight") + +--See also-- +| [[fun:to_string]] Convert dates to strings diff --git a/doc/function/to_html.txt b/doc/function/to_html.txt index 11af6504..cee9f73c 100644 --- a/doc/function/to_html.txt +++ b/doc/function/to_html.txt @@ -1,30 +1,30 @@ -Function: to_html - ---Usage-- -> to_html(some_tagged_text) - -Convert a [[type:tagged string]] to HTML code for use in web pages. -Characters are correctly escaped for HTML code. - -The following tags are converted to html: -! Tag Description -| <b> Bold -| <i> Italic -| <sym> Symbols, if the @symbol_font@ parameter is set. - -Symbol fonts can only be used in an [[type:export template]], when create directory is true, as the images -of the font are written to the output directory. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:tagged string]] String to convert to html -| @symbol_font@ [[type:string]] (optional) Name of a symbol font to use for images. -| @symbol_font_size@ [[type:double]] (optional) Size in points to use for the symbol font, default 12 - ---Examples-- -> to_html("bold text") == "bold text" -> to_html("WU") == "WU" - ---See also-- -| [[fun:symbols_to_html]] Convert text to html using a [[type:symbol font]]. -| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. +Function: to_html + +--Usage-- +> to_html(some_tagged_text) + +Convert a [[type:tagged string]] to HTML code for use in web pages. +Characters are correctly escaped for HTML code. + +The following tags are converted to html: +! Tag Description +| <b> Bold +| <i> Italic +| <sym> Symbols, if the @symbol_font@ parameter is set. + +Symbol fonts can only be used in an [[type:export template]], when create directory is true, as the images +of the font are written to the output directory. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:tagged string]] String to convert to html +| @symbol_font@ [[type:string]] (optional) Name of a symbol font to use for images. +| @symbol_font_size@ [[type:double]] (optional) Size in points to use for the symbol font, default 12 + +--Examples-- +> to_html("bold text") == "bold text" +> to_html("WU") == "WU" + +--See also-- +| [[fun:symbols_to_html]] Convert text to html using a [[type:symbol font]]. +| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. diff --git a/doc/function/to_image.txt b/doc/function/to_image.txt index 2947c05a..9de1d8bf 100644 --- a/doc/function/to_image.txt +++ b/doc/function/to_image.txt @@ -1,17 +1,17 @@ -Function: to_image - -DOC_MSE_VERSION: since 0.3.8 - ---Usage-- -> to_image(any value) - -Convert any value to a [[type:image]]. - -A string is interpreted as a [[type:filename]]. - ---Parameters-- -! Parameter Type Description -| @input@ ''any type'' Value to convert to an image - ---Examples-- ->>> to_image("image1.png") == "image1.png" +Function: to_image + +DOC_MSE_VERSION: since 0.3.8 + +--Usage-- +> to_image(any value) + +Convert any value to a [[type:image]]. + +A string is interpreted as a [[type:filename]]. + +--Parameters-- +! Parameter Type Description +| @input@ ''any type'' Value to convert to an image + +--Examples-- +>>> to_image("image1.png") == "image1.png" diff --git a/doc/function/to_int.txt b/doc/function/to_int.txt index 0956ee5c..bf2556db 100644 --- a/doc/function/to_int.txt +++ b/doc/function/to_int.txt @@ -1,30 +1,30 @@ -Function: to_int - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> to_int(any value) - -Convert any value to a [[type:int]]. - -* Real numbers are rounded towards zero when converted to integer numbers. -* The boolean value @true@ becomes @1@, while @false@ is converted to @0@. -* For colors the grayscale value between @0@ and @255@ is returned. - ---Parameters-- -! Parameter Type Description -| @input@ ''any type'' Value to convert to an integer number - ---Examples-- -> to_int(1.5) == "1" -> to_int("15") == "15" -> to_int(true) == 1 -> to_int(rgb(255,255,255)) == 255 - -Use @or else@ to recover from errors: -> to_number("not a number") or else 0 == 0 -> to_number("123") or else 0 == 123 - ---See also-- -| [[fun:to_real]] Convert any value to a [[type:double]] -| [[fun:to_number]] Convert any value to a number +Function: to_int + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> to_int(any value) + +Convert any value to a [[type:int]]. + +* Real numbers are rounded towards zero when converted to integer numbers. +* The boolean value @true@ becomes @1@, while @false@ is converted to @0@. +* For colors the grayscale value between @0@ and @255@ is returned. + +--Parameters-- +! Parameter Type Description +| @input@ ''any type'' Value to convert to an integer number + +--Examples-- +> to_int(1.5) == "1" +> to_int("15") == "15" +> to_int(true) == 1 +> to_int(rgb(255,255,255)) == 255 + +Use @or else@ to recover from errors: +> to_number("not a number") or else 0 == 0 +> to_number("123") or else 0 == 123 + +--See also-- +| [[fun:to_real]] Convert any value to a [[type:double]] +| [[fun:to_number]] Convert any value to a number diff --git a/doc/function/to_lower.txt b/doc/function/to_lower.txt index 35ad5d49..400d96ef 100644 --- a/doc/function/to_lower.txt +++ b/doc/function/to_lower.txt @@ -1,18 +1,18 @@ -Function: to_lower - ---Usage-- -> to_lower(some_string) - -Convert a string to lower case. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to convert. - ---Examples-- -> to_lower("ABC") == "abc" -> to_lower("123 aBc") == "123 abc" - ---See also-- -| [[fun:to_upper]] Convert a string to upper case, @"aBc" -> "ABC"@. -| [[fun:to_title]] Convert a string to title case, @"aBc" -> "Abc"@. +Function: to_lower + +--Usage-- +> to_lower(some_string) + +Convert a string to lower case. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to convert. + +--Examples-- +> to_lower("ABC") == "abc" +> to_lower("123 aBc") == "123 abc" + +--See also-- +| [[fun:to_upper]] Convert a string to upper case, @"aBc" -> "ABC"@. +| [[fun:to_title]] Convert a string to title case, @"aBc" -> "Abc"@. diff --git a/doc/function/to_number.txt b/doc/function/to_number.txt index 7b48a9b6..019073ec 100644 --- a/doc/function/to_number.txt +++ b/doc/function/to_number.txt @@ -1,29 +1,29 @@ -Function: to_number - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> to_number(any value) - -Convert any value to a number. -If the number can be represented as an [[type:int|integer number]] that is done. -Otherwise it is converted to a [[type:double]]. - - ---Parameters-- -! Parameter Type Description -| @input@ ''any type'' Value to convert to a number - ---Examples-- -> to_number(1) == 1 -> to_number(1.5) == 1.5 -> to_number("1") == 1 -> to_number("1.5") == 1.5 - -Use @or else@ to recover from errors: -> to_number("not a number") or else 0 == 0 -> to_number("123") or else 0 == 123 - ---See also-- -| [[fun:to_int]] Convert any value to a [[type:int]] -| [[fun:to_real]] Convert any value to a [[type:double]] +Function: to_number + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> to_number(any value) + +Convert any value to a number. +If the number can be represented as an [[type:int|integer number]] that is done. +Otherwise it is converted to a [[type:double]]. + + +--Parameters-- +! Parameter Type Description +| @input@ ''any type'' Value to convert to a number + +--Examples-- +> to_number(1) == 1 +> to_number(1.5) == 1.5 +> to_number("1") == 1 +> to_number("1.5") == 1.5 + +Use @or else@ to recover from errors: +> to_number("not a number") or else 0 == 0 +> to_number("123") or else 0 == 123 + +--See also-- +| [[fun:to_int]] Convert any value to a [[type:int]] +| [[fun:to_real]] Convert any value to a [[type:double]] diff --git a/doc/function/to_real.txt b/doc/function/to_real.txt index 7b3a74fb..78985a51 100644 --- a/doc/function/to_real.txt +++ b/doc/function/to_real.txt @@ -1,25 +1,25 @@ -Function: to_real - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> to_real(any value) - -Convert any value to a [[type:double]]. - - ---Parameters-- -! Parameter Type Description -| @input@ ''any type'' Value to convert to a real number - ---Examples-- -> to_real(1) == 1.0 -> to_real("1.5") == 1.5 - -Use @or else@ to recover from errors: -> to_number("not a number") or else 0.0 == 0.0 -> to_number("123") or else 0.0 == 123.0 - ---See also-- -| [[fun:to_int]] Convert any value to a [[type:int]] -| [[fun:to_number]] Convert any value to a number +Function: to_real + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> to_real(any value) + +Convert any value to a [[type:double]]. + + +--Parameters-- +! Parameter Type Description +| @input@ ''any type'' Value to convert to a real number + +--Examples-- +> to_real(1) == 1.0 +> to_real("1.5") == 1.5 + +Use @or else@ to recover from errors: +> to_number("not a number") or else 0.0 == 0.0 +> to_number("123") or else 0.0 == 123.0 + +--See also-- +| [[fun:to_int]] Convert any value to a [[type:int]] +| [[fun:to_number]] Convert any value to a number diff --git a/doc/function/to_string.txt b/doc/function/to_string.txt index caff65de..c506e630 100644 --- a/doc/function/to_string.txt +++ b/doc/function/to_string.txt @@ -1,27 +1,27 @@ -Function: to_string - -DOC_MSE_VERSION: since 0.3.7 - ---Usage-- -> to_string(any value) - -Convert any value to a [[type:string]] representation. - - -The @to_string@ function should not be confused with @to_text@. -The former converts things like number to string, while the latter removes tags from a [[type:tagged string]]. - ---Parameters-- -! Parameter Type Description -| @input@ ''any type'' Value to convert to a string -| @format@ ''optional'' Formatting to apply.
- This takes the same form as [[http://www.cplusplus.com/reference/clibrary/cstdio/printf.html|printf format specifiers]].
- When formating a date, the format string takes the same form as [[http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html|strftime format specifiers]]. - ---Examples-- -> to_string(to_color("blue")) == "rgb(0,0,255)" -> to_string(10 + 20) == "30" -> to_string(10 + 20, format: ".3f") == "30.000" -> to_string(10 + 20, format: "x") == "1e" # hexadecimal notation -> to_string("xy", format: "3s") == " xy" -> to_string(to_date("2008-12-31 23:59:59"), format:"%d/%m/%y") == "31/12/08" +Function: to_string + +DOC_MSE_VERSION: since 0.3.7 + +--Usage-- +> to_string(any value) + +Convert any value to a [[type:string]] representation. + + +The @to_string@ function should not be confused with @to_text@. +The former converts things like number to string, while the latter removes tags from a [[type:tagged string]]. + +--Parameters-- +! Parameter Type Description +| @input@ ''any type'' Value to convert to a string +| @format@ ''optional'' Formatting to apply.
+ This takes the same form as [[http://www.cplusplus.com/reference/clibrary/cstdio/printf.html|printf format specifiers]].
+ When formating a date, the format string takes the same form as [[http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html|strftime format specifiers]]. + +--Examples-- +> to_string(to_color("blue")) == "rgb(0,0,255)" +> to_string(10 + 20) == "30" +> to_string(10 + 20, format: ".3f") == "30.000" +> to_string(10 + 20, format: "x") == "1e" # hexadecimal notation +> to_string("xy", format: "3s") == " xy" +> to_string(to_date("2008-12-31 23:59:59"), format:"%d/%m/%y") == "31/12/08" diff --git a/doc/function/to_text.txt b/doc/function/to_text.txt index 2dd9c47a..97a2c0cb 100644 --- a/doc/function/to_text.txt +++ b/doc/function/to_text.txt @@ -1,19 +1,19 @@ -Function: to_text - ---Usage-- -> to_text(some_tagged_text) - -Convert a [[type:tagged string]] to a normal string by removing all tags and restoring escaped < characters. - - ---Parameters-- -! Parameter Type Description -| @input@ [[type:tagged string]] String to convert to text - ---Examples-- -> to_text("bold text") == "bold text" -> to_text("1 \< 2") == "1 < 2" - ---See also-- -| [[fun:to_html]] Convert [[type:tagged text]] to html. -| [[fun:remove_tags]] Remove all tags from tagged text. +Function: to_text + +--Usage-- +> to_text(some_tagged_text) + +Convert a [[type:tagged string]] to a normal string by removing all tags and restoring escaped < characters. + + +--Parameters-- +! Parameter Type Description +| @input@ [[type:tagged string]] String to convert to text + +--Examples-- +> to_text("bold text") == "bold text" +> to_text("1 \< 2") == "1 < 2" + +--See also-- +| [[fun:to_html]] Convert [[type:tagged text]] to html. +| [[fun:remove_tags]] Remove all tags from tagged text. diff --git a/doc/function/to_title.txt b/doc/function/to_title.txt index 345b500a..06b44b87 100644 --- a/doc/function/to_title.txt +++ b/doc/function/to_title.txt @@ -1,18 +1,18 @@ -Function: to_title - ---Usage-- -> to_title(some_string) - -Convert a string to title case, where each words starts with an upper case leter. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to convert. - ---Examples-- -> to_title("ABC") == "Abc" -> to_title("123 aBc") == "123 Abc" - ---See also-- -| [[fun:to_lower]] Convert a string to lower case, @"aBc" -> "abc"@. -| [[fun:to_upper]] Convert a string to upper case, @"aBc" -> "ABC"@. +Function: to_title + +--Usage-- +> to_title(some_string) + +Convert a string to title case, where each words starts with an upper case leter. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to convert. + +--Examples-- +> to_title("ABC") == "Abc" +> to_title("123 aBc") == "123 Abc" + +--See also-- +| [[fun:to_lower]] Convert a string to lower case, @"aBc" -> "abc"@. +| [[fun:to_upper]] Convert a string to upper case, @"aBc" -> "ABC"@. diff --git a/doc/function/to_upper.txt b/doc/function/to_upper.txt index 7ad35e40..33d7460c 100644 --- a/doc/function/to_upper.txt +++ b/doc/function/to_upper.txt @@ -1,18 +1,18 @@ -Function: to_upper - ---Usage-- -> to_upper(some_string) - -Convert a string to upper case. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to convert. - ---Examples-- -> to_upper("abc") == "ABC" -> to_upper("123 aBc") == "123 ABC" - ---See also-- -| [[fun:to_lower]] Convert a string to lower case, @"aBc" -> "abc"@. -| [[fun:to_title]] Convert a string to title case, @"aBc" -> "Abc"@. +Function: to_upper + +--Usage-- +> to_upper(some_string) + +Convert a string to upper case. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to convert. + +--Examples-- +> to_upper("abc") == "ABC" +> to_upper("123 aBc") == "123 ABC" + +--See also-- +| [[fun:to_lower]] Convert a string to lower case, @"aBc" -> "abc"@. +| [[fun:to_title]] Convert a string to title case, @"aBc" -> "Abc"@. diff --git a/doc/function/trace.txt b/doc/function/trace.txt index 084ce294..9020212b 100644 --- a/doc/function/trace.txt +++ b/doc/function/trace.txt @@ -1,17 +1,17 @@ -Function: trace - ---Usage-- -> trace(some_string) - -Output a message for debugging purposes, for example to investigate what is going on in some function. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Message - ---Examples-- -> trace("message") == "message" # the message is shown in the console panel - ---See also-- -| [[fun:warning]] Output a warning message. -| [[fun:error]] Output an error message. +Function: trace + +--Usage-- +> trace(some_string) + +Output a message for debugging purposes, for example to investigate what is going on in some function. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Message + +--Examples-- +> trace("message") == "message" # the message is shown in the console panel + +--See also-- +| [[fun:warning]] Output a warning message. +| [[fun:error]] Output an error message. diff --git a/doc/function/trim.txt b/doc/function/trim.txt index e366e7eb..bb85a085 100644 --- a/doc/function/trim.txt +++ b/doc/function/trim.txt @@ -1,14 +1,14 @@ -Function: trim - ---Usage-- -> trim(some_string) - -Remove leading and trailing whitespace from a string. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] String to remove whitespace from. - ---Examples-- -> trim(" abc ") == "abc" -> trim(" one two three ") == "one two three" +Function: trim + +--Usage-- +> trim(some_string) + +Remove leading and trailing whitespace from a string. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] String to remove whitespace from. + +--Examples-- +> trim(" abc ") == "abc" +> trim(" one two three ") == "one two three" diff --git a/doc/function/warning.txt b/doc/function/warning.txt index 5ade4d84..30d6c164 100644 --- a/doc/function/warning.txt +++ b/doc/function/warning.txt @@ -1,21 +1,21 @@ -Function: warning - -DOC_MSE_VERSION: since 2.0.1 - ---Usage-- -> warning(some_string) - -Output a warning message. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Message -| @condition@ [[type:boolean]] (optional) Only show the message if this condition holds. - ---Examples-- -> warning("message")" # the message is shown in the console panel -> warning("message", condition: false) # shows no message - ---See also-- -| [[fun:assert]] Check that the condition is @true@. Shows a warning message if it is not. -| [[fun:error]] Output an error message. +Function: warning + +DOC_MSE_VERSION: since 2.0.1 + +--Usage-- +> warning(some_string) + +Output a warning message. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Message +| @condition@ [[type:boolean]] (optional) Only show the message if this condition holds. + +--Examples-- +> warning("message")" # the message is shown in the console panel +> warning("message", condition: false) # shows no message + +--See also-- +| [[fun:assert]] Check that the condition is @true@. Shows a warning message if it is not. +| [[fun:error]] Output an error message. diff --git a/doc/function/write_image_file.txt b/doc/function/write_image_file.txt index 19de6c8d..ea89e91b 100644 --- a/doc/function/write_image_file.txt +++ b/doc/function/write_image_file.txt @@ -1,24 +1,24 @@ -Function: write_image_file - ---Usage-- -> write_image_file(some_image, file: filename) - -Write an image to a file in the output directory. -If a file with the given name already exists it is overwritten. - -Returns the name of the file written. - -This function can only be used in an [[type:export template]], when create directory is true. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:image]] Image to write to the file. -| @file@ [[type:string]] Name of the file to write to -| @width@ [[type:int]] Width in pixels to use for the image, by default the size of the image is used if available. -| @height@ [[type:int]] Height in pixels to use for the image, by default the size of the image is used if available. - ---Examples-- -> write_image_file(file:"image_out.png", linear_blend(...)) == "image_out.png" # image_out.png now contains the given image - ---See also-- -| [[fun:write_text_file]] Write a text file to the output directory. +Function: write_image_file + +--Usage-- +> write_image_file(some_image, file: filename) + +Write an image to a file in the output directory. +If a file with the given name already exists it is overwritten. + +Returns the name of the file written. + +This function can only be used in an [[type:export template]], when create directory is true. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:image]] Image to write to the file. +| @file@ [[type:string]] Name of the file to write to +| @width@ [[type:int]] Width in pixels to use for the image, by default the size of the image is used if available. +| @height@ [[type:int]] Height in pixels to use for the image, by default the size of the image is used if available. + +--Examples-- +> write_image_file(file:"image_out.png", linear_blend(...)) == "image_out.png" # image_out.png now contains the given image + +--See also-- +| [[fun:write_text_file]] Write a text file to the output directory. diff --git a/doc/function/write_set_file.txt b/doc/function/write_set_file.txt index 6c08c967..99ab5ae7 100644 --- a/doc/function/write_set_file.txt +++ b/doc/function/write_set_file.txt @@ -1,25 +1,25 @@ -Function: write_set_file - -DOC_MSE_VERSION: since 0.3.8 - ---Usage-- -> write_set_file(set:the_set, file: filename) - -Write the current set to a file in the output directory. -If a file with the given name already exists it is overwritten. - -Returns the name of the file written. - -This function can only be used in an [[type:export template]], when create directory is true. - ---Parameters-- -! Parameter Type Description -| @set@ [[type:set]] Set to write to the file. -| @file@ [[type:string]] Name of the file to write to - ---Examples-- -> write_set_file(file:"the-set.mse-set") == "the-set.mse-set" # the-set.mse-set now contains the set - ---See also-- -| [[fun:write_image_file]] Write an image file to the output directory. -| [[fun:write_text_file]] Write a text file to the output directory. +Function: write_set_file + +DOC_MSE_VERSION: since 0.3.8 + +--Usage-- +> write_set_file(set:the_set, file: filename) + +Write the current set to a file in the output directory. +If a file with the given name already exists it is overwritten. + +Returns the name of the file written. + +This function can only be used in an [[type:export template]], when create directory is true. + +--Parameters-- +! Parameter Type Description +| @set@ [[type:set]] Set to write to the file. +| @file@ [[type:string]] Name of the file to write to + +--Examples-- +> write_set_file(file:"the-set.mse-set") == "the-set.mse-set" # the-set.mse-set now contains the set + +--See also-- +| [[fun:write_image_file]] Write an image file to the output directory. +| [[fun:write_text_file]] Write a text file to the output directory. diff --git a/doc/function/write_text_file.txt b/doc/function/write_text_file.txt index de2c7d0b..8ad822ac 100644 --- a/doc/function/write_text_file.txt +++ b/doc/function/write_text_file.txt @@ -1,22 +1,22 @@ -Function: write_text_file - ---Usage-- -> write_text_file(some_string, file: filename) - -Write a string to a file in the output directory. -If a file with the given name already exists it is overwritten. - -Returns the name of the file written. - -This function can only be used in an [[type:export template]], when create directory is true. - ---Parameters-- -! Parameter Type Description -| @input@ [[type:string]] Text to write to the file. -| @file@ [[type:string]] Name of the file to write to - ---Examples-- -> write_text_file(file:"index.html", lots_of_html_code) == "index.html" # index.html now contains the given text - ---See also-- -| [[fun:write_image_file]] Write an image file to the output directory. +Function: write_text_file + +--Usage-- +> write_text_file(some_string, file: filename) + +Write a string to a file in the output directory. +If a file with the given name already exists it is overwritten. + +Returns the name of the file written. + +This function can only be used in an [[type:export template]], when create directory is true. + +--Parameters-- +! Parameter Type Description +| @input@ [[type:string]] Text to write to the file. +| @file@ [[type:string]] Name of the file to write to + +--Examples-- +> write_text_file(file:"index.html", lots_of_html_code) == "index.html" # index.html now contains the given text + +--See also-- +| [[fun:write_image_file]] Write an image file to the output directory. diff --git a/doc/index.txt b/doc/index.txt index 77fc333f..b68fd21e 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -1,20 +1,20 @@ -Documentation - -Welcome to the Magic Set Editor technical documentation. -These documents describe the file formats and scirpting language used by the program. - -There is currently no information on how to ''use'' the program for making cards. - ---Topics-- -Using the program: -* [[doc/cli|Invoking MSE from the command line]] -Templates: -* [[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]] +Documentation + +Welcome to the Magic Set Editor technical documentation. +These documents describe the file formats and scirpting language used by the program. + +There is currently no information on how to ''use'' the program for making cards. + +--Topics-- +Using the program: +* [[doc/cli|Invoking MSE from the command line]] +Templates: +* [[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]] diff --git a/doc/script/best_practices.txt b/doc/script/best_practices.txt index bbef82b3..fad512df 100644 --- a/doc/script/best_practices.txt +++ b/doc/script/best_practices.txt @@ -1,116 +1,116 @@ -Best practices - -Here are some best practices and tricks for using scripts, try to follow this as much as possible. - ---Use comments-- -Put comments before function definitions to describe what the function does: -> # Transmogrifies a flubble value for in grunk costs -> flubble_script := { ... } - ---Use short scripts-- -Try to put as little as possible in [[type:field]] scripts. -Instead define a function in the init script. - -'''bad''': ->field: -> name: flubble -> script: -> some very complicted expression -'''good''': ->init script: -> ... -> flubble_script := { some very complicted expression } ->field: -> script: flubble_script() - ---Use default arguments-- - -Many functions can be chained together using the @+@ operator. -For these functions [[script:default arguments]] can be given. -Have a look at @text_filter@ in the magic game file for an example. - -Using default arguments is especially important for functions that work on [[type:regex|regular expressions]], -since it allows MSE to compile the regular expressions just once instead of for every call. - ---Don't be afraid to nest-- -Don't be afraid to nest complex things like @if@ expressions inside other expressions. -For example the blend scripts for magic use: -> colors := sort_text( order: "(wubrg)" -> , (if chosen(choice:"white") then "w") -> + (if chosen(choice:"blue") then "u") -> + (if chosen(choice:"black") then "b") -> + (if chosen(choice:"red") then "r") -> + (if chosen(choice:"green") then "g")) -and: -> font_color_positions -> [ if chosen(choice:"horizontal") then "horizontal" -> else if chosen(choice:"vertical") then "vertical" -> else if chosen(choice:"overlay") then "overlay" -> else "radial" -> ][number_of_items(in: colors)] - ---Re-use functions-- -If two scripts or functions are very similair put the common part into another function. -The differences can be passed in parameters. - -A good example is in the @something 2@ fields used for Magic split and flip cards. -They behave exactly the same as the non-2 variants. -Don't use: ->init script: -> automatic_card_color_based_on_casting_cost := { ... card.casting_cost ... } -> automatic_card_color_based_on_casting_cost_2 := { ... card.casting_cost_2 ... } ->field: -> name: card color -> default: automatic_card_color_based_on_casting_cost() ->field: -> name: card color -> default: automatic_card_color_based_on_casting_cost_2() -Instead use: ->init script: -> automatic_card_color := { ... input ... } ->field: -> name: card color -> default: automatic_card_color(card.casting_cost) ->field: -> name: card color -> default: automatic_card_color(card.casting_cost_2) - ---Trick: hooks-- -Use this trick when defining a large function that might be overridden by stylesheets. - -For example things like the blend scripts for Magic cards are very large, and they are shared by all stylesheets. -Some stylesheets need to do something special, or they don't support a particular template. -This can be handled using hooks. - -What this means is that you don't do: -> blend := { large and complicated function bla bla, use "template.png" bla bla } -But instead -> template := "template.png" -> blend := { large and complicated function bla bla, use template bla bla } -Now a stylesheet can override this template by just changing that variable. - -Another option is splitting up the template -> blend := { large and complicated function bla bla, continue_blend() } -> continue_blend := { use template bla bla, etc. } - -A stylesheet can override just a part of this, or even put something in between: -> really_continue_blend := continue_blend -> continue_blend := { do_this_first; really_continue_blend() } - ---Trick: lookup tables-- -Sometimes the behaviour of a function depends on a particular value. -A good example of this are (again) the magic blend scripts. -What way cards are blended depends on the number of colors and on the 'style' of blending. - -Instead of using a lot of @if@ statements it can be cleaner to use a [[type:map]] as a lookup table. -So, instead of: -> if style == "horizontal" then lots of code -> else if style == "vertical" then lots of code -> # etc. -use: -> blends := [ -> horizontal: { lots of code } -> vertical: { lots of code } -> ] -> ... -> blends(style)() # lookup and call the function +Best practices + +Here are some best practices and tricks for using scripts, try to follow this as much as possible. + +--Use comments-- +Put comments before function definitions to describe what the function does: +> # Transmogrifies a flubble value for in grunk costs +> flubble_script := { ... } + +--Use short scripts-- +Try to put as little as possible in [[type:field]] scripts. +Instead define a function in the init script. + +'''bad''': +>field: +> name: flubble +> script: +> some very complicted expression +'''good''': +>init script: +> ... +> flubble_script := { some very complicted expression } +>field: +> script: flubble_script() + +--Use default arguments-- + +Many functions can be chained together using the @+@ operator. +For these functions [[script:default arguments]] can be given. +Have a look at @text_filter@ in the magic game file for an example. + +Using default arguments is especially important for functions that work on [[type:regex|regular expressions]], +since it allows MSE to compile the regular expressions just once instead of for every call. + +--Don't be afraid to nest-- +Don't be afraid to nest complex things like @if@ expressions inside other expressions. +For example the blend scripts for magic use: +> colors := sort_text( order: "(wubrg)" +> , (if chosen(choice:"white") then "w") +> + (if chosen(choice:"blue") then "u") +> + (if chosen(choice:"black") then "b") +> + (if chosen(choice:"red") then "r") +> + (if chosen(choice:"green") then "g")) +and: +> font_color_positions +> [ if chosen(choice:"horizontal") then "horizontal" +> else if chosen(choice:"vertical") then "vertical" +> else if chosen(choice:"overlay") then "overlay" +> else "radial" +> ][number_of_items(in: colors)] + +--Re-use functions-- +If two scripts or functions are very similair put the common part into another function. +The differences can be passed in parameters. + +A good example is in the @something 2@ fields used for Magic split and flip cards. +They behave exactly the same as the non-2 variants. +Don't use: +>init script: +> automatic_card_color_based_on_casting_cost := { ... card.casting_cost ... } +> automatic_card_color_based_on_casting_cost_2 := { ... card.casting_cost_2 ... } +>field: +> name: card color +> default: automatic_card_color_based_on_casting_cost() +>field: +> name: card color +> default: automatic_card_color_based_on_casting_cost_2() +Instead use: +>init script: +> automatic_card_color := { ... input ... } +>field: +> name: card color +> default: automatic_card_color(card.casting_cost) +>field: +> name: card color +> default: automatic_card_color(card.casting_cost_2) + +--Trick: hooks-- +Use this trick when defining a large function that might be overridden by stylesheets. + +For example things like the blend scripts for Magic cards are very large, and they are shared by all stylesheets. +Some stylesheets need to do something special, or they don't support a particular template. +This can be handled using hooks. + +What this means is that you don't do: +> blend := { large and complicated function bla bla, use "template.png" bla bla } +But instead +> template := "template.png" +> blend := { large and complicated function bla bla, use template bla bla } +Now a stylesheet can override this template by just changing that variable. + +Another option is splitting up the template +> blend := { large and complicated function bla bla, continue_blend() } +> continue_blend := { use template bla bla, etc. } + +A stylesheet can override just a part of this, or even put something in between: +> really_continue_blend := continue_blend +> continue_blend := { do_this_first; really_continue_blend() } + +--Trick: lookup tables-- +Sometimes the behaviour of a function depends on a particular value. +A good example of this are (again) the magic blend scripts. +What way cards are blended depends on the number of colors and on the 'style' of blending. + +Instead of using a lot of @if@ statements it can be cleaner to use a [[type:map]] as a lookup table. +So, instead of: +> if style == "horizontal" then lots of code +> else if style == "vertical" then lots of code +> # etc. +use: +> blends := [ +> horizontal: { lots of code } +> vertical: { lots of code } +> ] +> ... +> blends(style)() # lookup and call the function diff --git a/doc/script/control_structures.txt b/doc/script/control_structures.txt index fbca32c0..aba3aae3 100644 --- a/doc/script/control_structures.txt +++ b/doc/script/control_structures.txt @@ -1,87 +1,87 @@ -Control structures - -MSE Script has two types of control structures. - ---Conditional statement (@if then else@)-- - -To switch between two options use: - -> if condition then a else b - -If the condition evaluates to @true@, -then the expression evaluates to @a@, otherwise it evaluates to @b@. -The else part is optional. - -For example: -> if 1 + 1 == 2 then "yes sir!" else "something is wrong" -Will evaluate to @"yes sir!"@. - -Note that if-then-else is an ''expression'', it can be used almost everywhere: -> 1 + (if card.color == "red" then 1 else 2) -> color := (if card.color == "red" then "r") + -> (if card.color == "green" then "g") - -Multiple conditions can be checked by using @else if@: -> if card.color == "white" then "W" -> else if card.color == "red" then "R" -> else if card.color == "blue" then "U" -> else "something else" - -The @then@ and @else@ parts can also contain assignments and other control structures. -> if card.color == "red" then -> filter := filter + "r" - -To use multiple statements in the then or else branches you must use parentheses: -> # WRONG -> if 1 + 1 == 2 then -> x := y -> y := z -> # RIGHT -> if 1 + 1 == 2 then ( -> x := y -> y := z -> ) - ---Loop statement (@for each@)-- - -To iterate over all elements in a [[type:list]] the @for each@ construct can be used - -> for each variable in list do expression - -If list is a list of items, for example set.cards, the expression is evaluated for each item in that list. -The variable becomes set to that each item in succession. -The results of the expression are combined using the @+@ [[script:operators|operator]]: - -> for each x in ["a","b","c"] do x == "abc" -> for each x in ["a","b","c"] do [x+x] == ["aa","bb","cc"] - - -When iterating over a [[type:map]] the key is also available: - ->> for each key:variable in list do expression - -For example: - -> (for each k:v in [name:"Thing", rank:"High"] do -> "Its {k} is {v}. " -> ) == "Its name is Thing. Its rank is High. " - -When iterating over a list, the key is the index in the list, starting with @0@: -> (for each k:v in ["a","b","c"] do -> ["element {k} is {v}"] -> ) == ["element 0 is a","element 1 is b","element 2 is c"] - - -It is also possible to iterate over a range of values: - -> for variable from begin to end do expression - -The expression is evaluated for each number from begin to end (including begin, not including end). The variable becomes set to that each number in succession. Again, the results of the expression are combined using +. - ---Summary-- - -! Syntax Description -| @if a then b else c@ If @a@ is @true@ evaluates to @b@, otherwise evaluates to @c@. -| @for each x in list do something@ Does @something@ for each element in a list, adding the results -| @for each k:v in list do something@ Does @something@ for each element in a map using the key/index in the map. -| @for x from 1 to 100 do something@ Does @something@ for all numbers from 1 to 100. +Control structures + +MSE Script has two types of control structures. + +--Conditional statement (@if then else@)-- + +To switch between two options use: + +> if condition then a else b + +If the condition evaluates to @true@, +then the expression evaluates to @a@, otherwise it evaluates to @b@. +The else part is optional. + +For example: +> if 1 + 1 == 2 then "yes sir!" else "something is wrong" +Will evaluate to @"yes sir!"@. + +Note that if-then-else is an ''expression'', it can be used almost everywhere: +> 1 + (if card.color == "red" then 1 else 2) +> color := (if card.color == "red" then "r") + +> (if card.color == "green" then "g") + +Multiple conditions can be checked by using @else if@: +> if card.color == "white" then "W" +> else if card.color == "red" then "R" +> else if card.color == "blue" then "U" +> else "something else" + +The @then@ and @else@ parts can also contain assignments and other control structures. +> if card.color == "red" then +> filter := filter + "r" + +To use multiple statements in the then or else branches you must use parentheses: +> # WRONG +> if 1 + 1 == 2 then +> x := y +> y := z +> # RIGHT +> if 1 + 1 == 2 then ( +> x := y +> y := z +> ) + +--Loop statement (@for each@)-- + +To iterate over all elements in a [[type:list]] the @for each@ construct can be used + +> for each variable in list do expression + +If list is a list of items, for example set.cards, the expression is evaluated for each item in that list. +The variable becomes set to that each item in succession. +The results of the expression are combined using the @+@ [[script:operators|operator]]: + +> for each x in ["a","b","c"] do x == "abc" +> for each x in ["a","b","c"] do [x+x] == ["aa","bb","cc"] + + +When iterating over a [[type:map]] the key is also available: + +>> for each key:variable in list do expression + +For example: + +> (for each k:v in [name:"Thing", rank:"High"] do +> "Its {k} is {v}. " +> ) == "Its name is Thing. Its rank is High. " + +When iterating over a list, the key is the index in the list, starting with @0@: +> (for each k:v in ["a","b","c"] do +> ["element {k} is {v}"] +> ) == ["element 0 is a","element 1 is b","element 2 is c"] + + +It is also possible to iterate over a range of values: + +> for variable from begin to end do expression + +The expression is evaluated for each number from begin to end (including begin, not including end). The variable becomes set to that each number in succession. Again, the results of the expression are combined using +. + +--Summary-- + +! Syntax Description +| @if a then b else c@ If @a@ is @true@ evaluates to @b@, otherwise evaluates to @c@. +| @for each x in list do something@ Does @something@ for each element in a list, adding the results +| @for each k:v in list do something@ Does @something@ for each element in a map using the key/index in the map. +| @for x from 1 to 100 do something@ Does @something@ for all numbers from 1 to 100. diff --git a/doc/script/default_arguments.txt b/doc/script/default_arguments.txt index 3e64715e..3f039bc9 100644 --- a/doc/script/default_arguments.txt +++ b/doc/script/default_arguments.txt @@ -1,41 +1,41 @@ -Default arguments - -DOC_MSE_VERSION: since 0.3.7 - -It is possible to declare default arguments for functions using the @@@@ operator. -> function := { "argument was: " + arg }@(arg:"default") -If this function is called without the @arg@ argument, then the default value @"default"@ is used instead. -For example: -> function() == "argument was: default" -> function(arg: "something else") == "argument was: something else" - -For determining whether the argument is set only explicit arguments count, not everything in scope, so -> arg := "something else" -> function() == "argument was: default" - -Defaults are evaluated at the time the @@@@ operator is evaluated, they will not be overriden later -> default := "old default" -> function := { "argument was: " + arg }@(arg: default) -> default := "new default" -> function() == "argument was: old default" - ---Rule functions-- - -DOC_MSE_VERSION: until 0.3.6 - -In earlier versions of MSE some functions were available in a special ''rule form''. -A call to for example @replace_rule(match:"abc",replace:"xyz")@ is equivalent to @replace@@(match:"abc",replace:"xyz")@ . -For backwards compatability these functions are still available, but they should not be used for new templates. - -Programming in a ''rule style'' is still very useful. -A rule is like a normal function with all parameters given, except for the @input@. -These rules can then be combined using the @+@ operator, for example: -> # First all "a"s are replaced, then all "b"s. -> remove_as_and_bs := replace@(match: "a", replace: "") + -> replace@(match: "b", replace: "") -> -> text_with_as_and_bs := "bla bla bla" -> text_without_as_and_bs := remove_as_and_bs(text_with_as_and_bs) - - -
+Default arguments + +DOC_MSE_VERSION: since 0.3.7 + +It is possible to declare default arguments for functions using the @@@@ operator. +> function := { "argument was: " + arg }@(arg:"default") +If this function is called without the @arg@ argument, then the default value @"default"@ is used instead. +For example: +> function() == "argument was: default" +> function(arg: "something else") == "argument was: something else" + +For determining whether the argument is set only explicit arguments count, not everything in scope, so +> arg := "something else" +> function() == "argument was: default" + +Defaults are evaluated at the time the @@@@ operator is evaluated, they will not be overriden later +> default := "old default" +> function := { "argument was: " + arg }@(arg: default) +> default := "new default" +> function() == "argument was: old default" + +--Rule functions-- + +DOC_MSE_VERSION: until 0.3.6 + +In earlier versions of MSE some functions were available in a special ''rule form''. +A call to for example @replace_rule(match:"abc",replace:"xyz")@ is equivalent to @replace@@(match:"abc",replace:"xyz")@ . +For backwards compatability these functions are still available, but they should not be used for new templates. + +Programming in a ''rule style'' is still very useful. +A rule is like a normal function with all parameters given, except for the @input@. +These rules can then be combined using the @+@ operator, for example: +> # First all "a"s are replaced, then all "b"s. +> remove_as_and_bs := replace@(match: "a", replace: "") + +> replace@(match: "b", replace: "") +> +> text_with_as_and_bs := "bla bla bla" +> text_without_as_and_bs := remove_as_and_bs(text_with_as_and_bs) + + + diff --git a/doc/script/functions.txt b/doc/script/functions.txt index 834fb513..d5ed46d6 100644 --- a/doc/script/functions.txt +++ b/doc/script/functions.txt @@ -1,32 +1,32 @@ -Functions - -It is possible to define your own functions in MSE script. -The syntax for this is very simple, code in curly braces defines a function: -> { code goes here } - -To be able to refer to the function it is usually assigned to a variable: -> function := { code goes here } - -Calling a function is done using parentheses: -> { code }() -> function() -this has the effect of evaluating the code inside the curly braces. - ---Parameters-- - -When calling a function, parameters can be specified inside the parentheses of the function call: -> fun := { "xyz is {xyz}" } -> fun(xyz: "a parameter") == "xyz is a parameter" -These assignments are ''only'' visible to the called function. -> xyz := "outside" -> fun(xyz: "a parameter") -> # xyz is still "outside" - -The syntax for parameters is @name: value@. -Multiple parameters are separated by commas. - -The special syntax @value@ (without a name) means that the variable @input@ is used: -> fun := { input + var2 } -> fun(var2: "yes", "no") == "noyes" - - +Functions + +It is possible to define your own functions in MSE script. +The syntax for this is very simple, code in curly braces defines a function: +> { code goes here } + +To be able to refer to the function it is usually assigned to a variable: +> function := { code goes here } + +Calling a function is done using parentheses: +> { code }() +> function() +this has the effect of evaluating the code inside the curly braces. + +--Parameters-- + +When calling a function, parameters can be specified inside the parentheses of the function call: +> fun := { "xyz is {xyz}" } +> fun(xyz: "a parameter") == "xyz is a parameter" +These assignments are ''only'' visible to the called function. +> xyz := "outside" +> fun(xyz: "a parameter") +> # xyz is still "outside" + +The syntax for parameters is @name: value@. +Multiple parameters are separated by commas. + +The special syntax @value@ (without a name) means that the variable @input@ is used: +> fun := { input + var2 } +> fun(var2: "yes", "no") == "noyes" + + diff --git a/doc/script/index.txt b/doc/script/index.txt index e36e22a8..513cd887 100644 --- a/doc/script/index.txt +++ b/doc/script/index.txt @@ -1,56 +1,56 @@ -Scripting language - -MSE uses a custom scripting language to add complicated behaviour to [[type:field]]s and [[type:style]]s. - ---Topics-- -* [[script:introduction|Introduction to scripting]] -* [[script:Operators]] -* [[script:Variables]] -* [[script:Functions]] -* [[script:Default arguments]] -* [[script:Control structures]] -* [[script:Predefined variables]] -* [[script:Best practices]] -See also: -* [[type:index|Data types used]] -* [[fun:index|Built in functions]] - ---Syntax index-- -| @#comment@ Comments ignored by the parser -| @123@ [[type:int|A literal number]] -| @"stuff"@ [[type:string|A literal string]] -| @[a,b,c]@ [[type:list|A literal list]] -| @[a:b, c:d]@ [[type:map|A literal map]] -| @{ expr }@ [[script:functions|Function definition]] -| @fun(a:b, c:d)@ [[script:functions|Function call]] -| @fun(value)@ [[script:functions|Function call with '@input@' argument]] -| @fun@@(a:b)@ [[script:default_arguments|Default arguments]] -| @a.b@ [[script:operators|Property 'b' of 'a']] -| @a[b]@ [[script:operators|Property 'value of b' of 'a']] -| @-a@ [[script:operators|Negation]] -| @a + b@ [[script:operators|Addition / concatenation]] -| @a - b@ [[script:operators|Subtraction]] -| @a * b@ [[script:operators|Multiplication]] -| @a / b@ [[script:operators|Floating point division]] -| @a div b@ [[script:operators|Integer division]] -| @a mod b@ [[script:operators|Remainder]] -| @a ^ b@ [[script:operators|Exponentiation]] -| @not a@ [[type:boolean|Boolean not]] -| @a and b@ [[type:boolean|Boolean conjunction]] -| @a or b@ [[type:boolean|Boolean disjunction]] -| @a xor b@ [[type:boolean|Boolean xor]] -| @a == b@ [[script:operators|Comparison for equality]] -| @a != b@ [[script:operators|Comparison for inequality]] -| @a < b@ [[script:operators|Comparison]] -| @a > b@ [[script:operators|Comparison]] -| @a <= b@ [[script:operators|Comparison]] -| @a >= b@ [[script:operators|Comparison]] -| @a or else b@ Use @a@ unless it is an error, then use @b@ instead. -| @min(a,b,c,...)@ [[script:operators|Smallest of the values]] -| @max(a,b,c,...)@ [[script:operators|Largest of the values]] -| @rgb(r,g,b)@ [[type:color|A color value]] -| @rgba(r,g,b)@ [[type:color|A color value with transparency]] -| @if x then y@ [[script:control structures|Conditional expresion]] -| @if x then y else z@ [[script:control structures|Conditional expresion]] -| @for x in list do y@ [[script:control structures|Loop over elements in a list]] -| @for x from a to b do y@ [[script:control structures|Loop over numbers from a to b]] +Scripting language + +MSE uses a custom scripting language to add complicated behaviour to [[type:field]]s and [[type:style]]s. + +--Topics-- +* [[script:introduction|Introduction to scripting]] +* [[script:Operators]] +* [[script:Variables]] +* [[script:Functions]] +* [[script:Default arguments]] +* [[script:Control structures]] +* [[script:Predefined variables]] +* [[script:Best practices]] +See also: +* [[type:index|Data types used]] +* [[fun:index|Built in functions]] + +--Syntax index-- +| @#comment@ Comments ignored by the parser +| @123@ [[type:int|A literal number]] +| @"stuff"@ [[type:string|A literal string]] +| @[a,b,c]@ [[type:list|A literal list]] +| @[a:b, c:d]@ [[type:map|A literal map]] +| @{ expr }@ [[script:functions|Function definition]] +| @fun(a:b, c:d)@ [[script:functions|Function call]] +| @fun(value)@ [[script:functions|Function call with '@input@' argument]] +| @fun@@(a:b)@ [[script:default_arguments|Default arguments]] +| @a.b@ [[script:operators|Property 'b' of 'a']] +| @a[b]@ [[script:operators|Property 'value of b' of 'a']] +| @-a@ [[script:operators|Negation]] +| @a + b@ [[script:operators|Addition / concatenation]] +| @a - b@ [[script:operators|Subtraction]] +| @a * b@ [[script:operators|Multiplication]] +| @a / b@ [[script:operators|Floating point division]] +| @a div b@ [[script:operators|Integer division]] +| @a mod b@ [[script:operators|Remainder]] +| @a ^ b@ [[script:operators|Exponentiation]] +| @not a@ [[type:boolean|Boolean not]] +| @a and b@ [[type:boolean|Boolean conjunction]] +| @a or b@ [[type:boolean|Boolean disjunction]] +| @a xor b@ [[type:boolean|Boolean xor]] +| @a == b@ [[script:operators|Comparison for equality]] +| @a != b@ [[script:operators|Comparison for inequality]] +| @a < b@ [[script:operators|Comparison]] +| @a > b@ [[script:operators|Comparison]] +| @a <= b@ [[script:operators|Comparison]] +| @a >= b@ [[script:operators|Comparison]] +| @a or else b@ Use @a@ unless it is an error, then use @b@ instead. +| @min(a,b,c,...)@ [[script:operators|Smallest of the values]] +| @max(a,b,c,...)@ [[script:operators|Largest of the values]] +| @rgb(r,g,b)@ [[type:color|A color value]] +| @rgba(r,g,b)@ [[type:color|A color value with transparency]] +| @if x then y@ [[script:control structures|Conditional expresion]] +| @if x then y else z@ [[script:control structures|Conditional expresion]] +| @for x in list do y@ [[script:control structures|Loop over elements in a list]] +| @for x from a to b do y@ [[script:control structures|Loop over numbers from a to b]] diff --git a/doc/script/introduction.txt b/doc/script/introduction.txt index 4ec20585..40d7e0f3 100644 --- a/doc/script/introduction.txt +++ b/doc/script/introduction.txt @@ -1,34 +1,34 @@ -Scripting introduction - -MSE uses a custom scripting language to add complicated behaviour to [[type:field]]s and [[type:style]]s. - -This documentation assumes that the reader has some programming experience. -In particular it is assumed that you know what 'functions', 'variables' and 'operators' are. - -Scripts in MSE are usually small, just a few lines. -A piece of script code is also called an ''expression''. -Expressions can be ''evaluated'' to give a result. -For example the expression @1 + 1@ will evaluate to @2@. - -An important idea behind MSE is that it tries to be ''pure'', -there are no global variables and there is no way to change properties of objects. -This means that when you evaluate an expression the result is always the same (unless it contains variable assignments). - -Basic elements of scripts are ''constants''. -A constant is something with a fixed value. -Possible constants are: -! Syntax Type -| @nil@ Nothing -| @true@, @false@ [[type:boolean]] -| @123@ [[type:int]] -| @123.5@ [[type:double]] -| @"abc"@ [[type:string]] -| @rgb(255,0,0)@ [[type:color]] -| @rgba(0,0,0,0)@ [[type:color]] -| @[a,b,c]@ [[type:list]] -Note: Strings, list and colors don't have to be constants, they can contain other code. - -The @nil@ value has a special meaning, it is 'nothing'. -Adding @nil@ to something has no effect (it returns 'something'), calling @nil@ as a function just returns the input, etc. - - +Scripting introduction + +MSE uses a custom scripting language to add complicated behaviour to [[type:field]]s and [[type:style]]s. + +This documentation assumes that the reader has some programming experience. +In particular it is assumed that you know what 'functions', 'variables' and 'operators' are. + +Scripts in MSE are usually small, just a few lines. +A piece of script code is also called an ''expression''. +Expressions can be ''evaluated'' to give a result. +For example the expression @1 + 1@ will evaluate to @2@. + +An important idea behind MSE is that it tries to be ''pure'', +there are no global variables and there is no way to change properties of objects. +This means that when you evaluate an expression the result is always the same (unless it contains variable assignments). + +Basic elements of scripts are ''constants''. +A constant is something with a fixed value. +Possible constants are: +! Syntax Type +| @nil@ Nothing +| @true@, @false@ [[type:boolean]] +| @123@ [[type:int]] +| @123.5@ [[type:double]] +| @"abc"@ [[type:string]] +| @rgb(255,0,0)@ [[type:color]] +| @rgba(0,0,0,0)@ [[type:color]] +| @[a,b,c]@ [[type:list]] +Note: Strings, list and colors don't have to be constants, they can contain other code. + +The @nil@ value has a special meaning, it is 'nothing'. +Adding @nil@ to something has no effect (it returns 'something'), calling @nil@ as a function just returns the input, etc. + + diff --git a/doc/script/operators.txt b/doc/script/operators.txt index 7c121717..9fe5ed65 100644 --- a/doc/script/operators.txt +++ b/doc/script/operators.txt @@ -1,114 +1,114 @@ -Operators - -To get more complicated expressions you combine them using operators. - ---Basic mathematics-- -MSE script supports most basic mathamatical operators: -! Operator Example Description -| @a + b@ @3 + 2 == 5@
Add two numbers, - @"3" + "2" == "32"@ concatenate two strings or compose two functions (see below) -| @a - b@ @3 - 2 == 1@ Substract two numbers -| @a * b@ @3 * 2 == 6@ Multiply two numbers -| @a / b@ @3 / 2 == 1.5@ Divide two numbers. Does not round, always produces a [[type:double]]. -| @a div b@ @3 div 2 == 1@ DOC_MSE_VERSION: since 0.3.7 - Divide two numbers. Rounds towards zero, producing an [[type:int]]. -| @a mod b@ @3 mod 2 == 1@ Take the remainder after integer division (modulo) -| @a ^ b@ @3 ^ 2 == 9@ DOC_MSE_VERSION: since 0.3.7 - Exponentation, raise a to the power b.
The numbers can be [[type:double]]s, so to calculate a square root use @2^0.5 == 1.41421356237@. -| @-a@ @-(3 + 2) == -5@ Negate a number (make it negative if positive and vice versa) - -===The + operator=== -The @+@ operator has four functions -* It adds [[type:int]]s (also [[type:double]]s), @1+1 == 2@ -* It concatenates strings, @"1" + "1" == "11"@ -* It concatenates lists, @[1] + [1] == [1,1]@ -* It composes [[type:function]]s @(f + g) () == g( input: f() )@ - ---Comparison-- -It is also possible to compare values. All comparisons evaluate to either @true@ or @false@. -! Operator Example Description -| @a == b@ @1 + 1 == 2@
- @"x" == "x"@
- @1 + 1 == "2"@ Are two numbers or strings the same? @=@ can also be used instead. -| @a != b@ @1 + 1 != 3@
- @"x" != "y"@ Are two numbers or strings different? -| @a < b@ @1 < 2@
- @"x" < "y"@ Is a less than b? Uses [[http://en.wikipedia.org/wiki/Lexicographical_order|lexicographic order]] for strings. -| @a > b@ @2 > 1@
- @"y" > "x"@ Is a greater than b? -| @a <= b@ @1 <= 1@
- @"x" <= "y"@ Is a less than b or are they equal? -| @a >= b@ @2 >= 1@
- @"x" >= "x"@ Is a greater than b or are they equal? -| @min(a,b)@ @min(1,2) == 1@ Returns the smallest of two or more values. -| @max(a,b)@ @max(1,2) == 2@ Returns the largest of two or more values. - ---Booleans-- -[[type:Boolean]]s (for example from comparisons) can be combined using: -| @a and b@ Are both @a@ and @b@ true? -| @a or b@ Is at least one of @a@ and @b@ true? -| @a xor b@ Is exactly one of @a@ and @b@ true? -| @not a@ Is @a@ false? -In a table: -! @a@ @b@ a or b a and b a xor b -| @false@ @false@ @false@ @false@ @false@ -| @false@ @true@ @true@ @false@ @true@ -| @true@ @false@ @true@ @false@ @true@ -| @true@ @true@ @true@ @true@ @false@ - -The @and@ and @or@ operators use [[http://en.wikipedia.org/wiki/Short-circuit_evaluation|short-circuit evaluation]], which means that the second argument is only evaluated if the first argument does not suffice to determine the value of the expression. -For example -> true or card.field_that_does_not_exist -evaluates to @true@ instead of giving an error. - ---Grouping and order-- - -Operators are ordered as usual, so -> 1 + 2 * 3 == 1 + (2 * 3) == 7 -Operators can be grouped differently using parentheses. -> (1 + 2) * 3 == 3 * 3 == 9 - -The exact order of precedence is given in the following table, -higher in the table means that this operator binds tighter to its arguments, @*@ binds tighter then @+@. -| @a(...)@, @a.b@, @a[b]@ Function calls, property access, see below -| @-a@, @not@ Unary operators -| @^@ Exponentiation -| @*@, @/@, @div@, @mod@ Multiplication and division -| @+@, @-@ Addition and substraction -| @==@, @!=@, @<@, @>@, @<=@, @>=@ Comparisons -| @and@, @or@, @xor@ Boolean operators -| @:=@ Assignement, see below -| @;@ Sequence, see below - ---Properties-- -Properties of types, as described in the [[type:index|data type section]] of the documentation, can be accessed using the @.@ operator: -> set.cards # retrieve the 'cards' property of a set -The @[]@ operator has a similair purpose, only the property retrieved is determined by a string, so it can be changed: -> set["cards"] # same as above -> c := "cards" -> set[c] # again, the same - -Multiple uses of these operators can be combined, for example: -> set.cards[0].card_color # the card color of the first card in the set - -Note that a property named @card color@ is refered to as @card_color@ when using the @.@ operator, all spaces become underscores. -> style.padding left # syntax error -> style.padding_left # use this instead - ---Assignment and sequence-- -Values can be assigned to [[script:variables]] using the @:=@ operator: -> variable := 1 + 1 -The result of this expression is the value assigned, this can be used to assign to multiple variables: -> var1 := var2 := 1 + 1 -> # now var1 == 2 and var2 == 2 - -To combine multiple assignments into a single expression the ''sequencing operator'', @;@ can be used. -This first executes an expression, discards the result and then evaluates another one: -> var1 := 1 + 1 # assign -> ; # discard the result (i.e. 2) -> var1 * 2 # retrieve the value again, returns 4 -Semicolons at the end of a line can be omitted, so the above can also be written simply as: -> var1 := 1 + 1 -> var1 * 2 - - +Operators + +To get more complicated expressions you combine them using operators. + +--Basic mathematics-- +MSE script supports most basic mathamatical operators: +! Operator Example Description +| @a + b@ @3 + 2 == 5@
Add two numbers, + @"3" + "2" == "32"@ concatenate two strings or compose two functions (see below) +| @a - b@ @3 - 2 == 1@ Substract two numbers +| @a * b@ @3 * 2 == 6@ Multiply two numbers +| @a / b@ @3 / 2 == 1.5@ Divide two numbers. Does not round, always produces a [[type:double]]. +| @a div b@ @3 div 2 == 1@ DOC_MSE_VERSION: since 0.3.7 + Divide two numbers. Rounds towards zero, producing an [[type:int]]. +| @a mod b@ @3 mod 2 == 1@ Take the remainder after integer division (modulo) +| @a ^ b@ @3 ^ 2 == 9@ DOC_MSE_VERSION: since 0.3.7 + Exponentation, raise a to the power b.
The numbers can be [[type:double]]s, so to calculate a square root use @2^0.5 == 1.41421356237@. +| @-a@ @-(3 + 2) == -5@ Negate a number (make it negative if positive and vice versa) + +===The + operator=== +The @+@ operator has four functions +* It adds [[type:int]]s (also [[type:double]]s), @1+1 == 2@ +* It concatenates strings, @"1" + "1" == "11"@ +* It concatenates lists, @[1] + [1] == [1,1]@ +* It composes [[type:function]]s @(f + g) () == g( input: f() )@ + +--Comparison-- +It is also possible to compare values. All comparisons evaluate to either @true@ or @false@. +! Operator Example Description +| @a == b@ @1 + 1 == 2@
+ @"x" == "x"@
+ @1 + 1 == "2"@ Are two numbers or strings the same? @=@ can also be used instead. +| @a != b@ @1 + 1 != 3@
+ @"x" != "y"@ Are two numbers or strings different? +| @a < b@ @1 < 2@
+ @"x" < "y"@ Is a less than b? Uses [[http://en.wikipedia.org/wiki/Lexicographical_order|lexicographic order]] for strings. +| @a > b@ @2 > 1@
+ @"y" > "x"@ Is a greater than b? +| @a <= b@ @1 <= 1@
+ @"x" <= "y"@ Is a less than b or are they equal? +| @a >= b@ @2 >= 1@
+ @"x" >= "x"@ Is a greater than b or are they equal? +| @min(a,b)@ @min(1,2) == 1@ Returns the smallest of two or more values. +| @max(a,b)@ @max(1,2) == 2@ Returns the largest of two or more values. + +--Booleans-- +[[type:Boolean]]s (for example from comparisons) can be combined using: +| @a and b@ Are both @a@ and @b@ true? +| @a or b@ Is at least one of @a@ and @b@ true? +| @a xor b@ Is exactly one of @a@ and @b@ true? +| @not a@ Is @a@ false? +In a table: +! @a@ @b@ a or b a and b a xor b +| @false@ @false@ @false@ @false@ @false@ +| @false@ @true@ @true@ @false@ @true@ +| @true@ @false@ @true@ @false@ @true@ +| @true@ @true@ @true@ @true@ @false@ + +The @and@ and @or@ operators use [[http://en.wikipedia.org/wiki/Short-circuit_evaluation|short-circuit evaluation]], which means that the second argument is only evaluated if the first argument does not suffice to determine the value of the expression. +For example +> true or card.field_that_does_not_exist +evaluates to @true@ instead of giving an error. + +--Grouping and order-- + +Operators are ordered as usual, so +> 1 + 2 * 3 == 1 + (2 * 3) == 7 +Operators can be grouped differently using parentheses. +> (1 + 2) * 3 == 3 * 3 == 9 + +The exact order of precedence is given in the following table, +higher in the table means that this operator binds tighter to its arguments, @*@ binds tighter then @+@. +| @a(...)@, @a.b@, @a[b]@ Function calls, property access, see below +| @-a@, @not@ Unary operators +| @^@ Exponentiation +| @*@, @/@, @div@, @mod@ Multiplication and division +| @+@, @-@ Addition and substraction +| @==@, @!=@, @<@, @>@, @<=@, @>=@ Comparisons +| @and@, @or@, @xor@ Boolean operators +| @:=@ Assignement, see below +| @;@ Sequence, see below + +--Properties-- +Properties of types, as described in the [[type:index|data type section]] of the documentation, can be accessed using the @.@ operator: +> set.cards # retrieve the 'cards' property of a set +The @[]@ operator has a similair purpose, only the property retrieved is determined by a string, so it can be changed: +> set["cards"] # same as above +> c := "cards" +> set[c] # again, the same + +Multiple uses of these operators can be combined, for example: +> set.cards[0].card_color # the card color of the first card in the set + +Note that a property named @card color@ is refered to as @card_color@ when using the @.@ operator, all spaces become underscores. +> style.padding left # syntax error +> style.padding_left # use this instead + +--Assignment and sequence-- +Values can be assigned to [[script:variables]] using the @:=@ operator: +> variable := 1 + 1 +The result of this expression is the value assigned, this can be used to assign to multiple variables: +> var1 := var2 := 1 + 1 +> # now var1 == 2 and var2 == 2 + +To combine multiple assignments into a single expression the ''sequencing operator'', @;@ can be used. +This first executes an expression, discards the result and then evaluates another one: +> var1 := 1 + 1 # assign +> ; # discard the result (i.e. 2) +> var1 * 2 # retrieve the value again, returns 4 +Semicolons at the end of a line can be omitted, so the above can also be written simply as: +> var1 := 1 + 1 +> var1 * 2 + + diff --git a/doc/script/predefined_variables.txt b/doc/script/predefined_variables.txt index 3134a656..af3c545a 100644 --- a/doc/script/predefined_variables.txt +++ b/doc/script/predefined_variables.txt @@ -1,16 +1,16 @@ -Predefined variables - -When evaluating scripts several variables are predefined containing useful information. -Aside from the [[fun:index|built in functions]] the following variables are provided: -! Variable Type When available? Description -| @game@ [[type:game]] always The current game, the same as @set.game@ -| @set@ [[type:set]] always The current set. -| @stylesheet@ [[type:stylesheet]] not in the @init script@ of the game - The current stylesheet -| @card@ [[type:card]] not in @init script@s or when exporting - The current card. -| @card_style@ [[type:indexmap]] of [[type:style]]s where @card@ is available Style properties for the current card, the same as @stylesheet.card_style@. -| @styling@ [[type:indexmap]] of [[type:value]]s where @card@ is available Styling options for the stylesheet/card. -| @value@ [[type:value]] when evaluating a [[type:field]]'s @script@ or @default@ script Current value in the field. -| @options@ [[type:indexmap]] of [[type:value]]s when exporting Options of the [[type:export template]]. -Variables are only available where they make sense. +Predefined variables + +When evaluating scripts several variables are predefined containing useful information. +Aside from the [[fun:index|built in functions]] the following variables are provided: +! Variable Type When available? Description +| @game@ [[type:game]] always The current game, the same as @set.game@ +| @set@ [[type:set]] always The current set. +| @stylesheet@ [[type:stylesheet]] not in the @init script@ of the game + The current stylesheet +| @card@ [[type:card]] not in @init script@s or when exporting + The current card. +| @card_style@ [[type:indexmap]] of [[type:style]]s where @card@ is available Style properties for the current card, the same as @stylesheet.card_style@. +| @styling@ [[type:indexmap]] of [[type:value]]s where @card@ is available Styling options for the stylesheet/card. +| @value@ [[type:value]] when evaluating a [[type:field]]'s @script@ or @default@ script Current value in the field. +| @options@ [[type:indexmap]] of [[type:value]]s when exporting Options of the [[type:export template]]. +Variables are only available where they make sense. diff --git a/doc/script/variables.txt b/doc/script/variables.txt index 343e99fd..cd4e816c 100644 --- a/doc/script/variables.txt +++ b/doc/script/variables.txt @@ -1,49 +1,49 @@ -Variables - -MSE script has the notion of ''variables''. -A variable is a name holding a value, assigned using the @:=@ operator: -> variable := 1 + 1 -From now on (until another value is assigned) @variable@ evaluates to @2@ in the rest of the script. - ---Scope-- - -Assignments to variables are ''local'' to the current function. -Consider: -> function := { -> x := "something else" -> # here x is something else -> } -> x := 1 -> function() -> # here x is still 1 - -Unlike most programming languages MSE script uses [[http://en.wikipedia.org/wiki/Dynamic_scoping#Dynamic_scoping|dynamic scoping]]. -This means that assignments done in the calling function are visible in the called function: -> fun := { "xyz is {xyz}" } -> one := { -> xyz := 1 -> fun() -> } -> two := { -> xyz := "two" -> fun() -> } -> one() == "xyz is 1" -> two() == "xyz is two" - -This can be very useful for variables like @card@, which are used by many functions. - ---Overriding functions-- -Like custom functions, the [[fun:index|built in functions]] are also stored in variables. -It is possible to overwrite them: -> to_upper := { input } -> to_upper("xyz") == "xyz" # Not what it used to do - -A neat trick is adding 'extra' behaviour to functions. -This can be done by first making a copy, and calling that: -> real_to_upper := to_upper -> to_upper := { "upper case: " + real_to_upper() } -> to_upper("xyz") == "upper case: XYZ" -Note that @real_to_upper@ is called without extra parameters, the @input@ variable is still set from the outer call to the new @to_upper@ itself. - -
previous: ← Operators | next: Functions →
+Variables + +MSE script has the notion of ''variables''. +A variable is a name holding a value, assigned using the @:=@ operator: +> variable := 1 + 1 +From now on (until another value is assigned) @variable@ evaluates to @2@ in the rest of the script. + +--Scope-- + +Assignments to variables are ''local'' to the current function. +Consider: +> function := { +> x := "something else" +> # here x is something else +> } +> x := 1 +> function() +> # here x is still 1 + +Unlike most programming languages MSE script uses [[http://en.wikipedia.org/wiki/Dynamic_scoping#Dynamic_scoping|dynamic scoping]]. +This means that assignments done in the calling function are visible in the called function: +> fun := { "xyz is {xyz}" } +> one := { +> xyz := 1 +> fun() +> } +> two := { +> xyz := "two" +> fun() +> } +> one() == "xyz is 1" +> two() == "xyz is two" + +This can be very useful for variables like @card@, which are used by many functions. + +--Overriding functions-- +Like custom functions, the [[fun:index|built in functions]] are also stored in variables. +It is possible to overwrite them: +> to_upper := { input } +> to_upper("xyz") == "xyz" # Not what it used to do + +A neat trick is adding 'extra' behaviour to functions. +This can be done by first making a copy, and calling that: +> real_to_upper := to_upper +> to_upper := { "upper case: " + real_to_upper() } +> to_upper("xyz") == "upper case: XYZ" +Note that @real_to_upper@ is called without extra parameters, the @input@ variable is still set from the outer call to the new @to_upper@ itself. + +
previous: ← Operators | next: Functions →
diff --git a/doc/tutorial/index.txt b/doc/tutorial/index.txt index 179fd993..2311f303 100644 --- a/doc/tutorial/index.txt +++ b/doc/tutorial/index.txt @@ -1,4 +1,4 @@ -Templating tutorial - -This space is reserved for a tutorial on making new templates for MSE. -An announcement will be posted in the forum when the tutorial becomes available. +Templating tutorial + +This space is reserved for a tutorial on making new templates for MSE. +An announcement will be posted in the forum when the tutorial becomes available. diff --git a/doc/type/add_cards_script.txt b/doc/type/add_cards_script.txt index 93aaad1a..170f725c 100644 --- a/doc/type/add_cards_script.txt +++ b/doc/type/add_cards_script.txt @@ -1,31 +1,31 @@ -Data type: add cards script - -DOC_MSE_VERSION: since 0.3.7 - ---Overview-- - -A script to add multiple cards to the set at once. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] Name of this script; appears in the menu. -| @description@ [[type:string]] @""@ Description of this script; appears in the status bar. -| @enabled@ [[type:scriptable]] [[type:boolean]] @true@ Is this script enabled? -| @script@ [[type:script]] Script that produces the cards.
- This script should return a [[type:list]] of [[type:card]]s. - The [[fun:new_card]] function can be used to make new cards. - ---Example-- ->add cards script: -> name: &Basic Lands -> description: Adds 5 basic lands to the set. -> script: -> [ new_card([name: "Plains", super_type: "Basic Land", sub_type: "Plains"]) -> , new_card([name: "Island", super_type: "Basic Land", sub_type: "Island"]) -> , new_card([name: "Swamp", super_type: "Basic Land", sub_type: "Swamp"]) -> , new_card([name: "Mountain", super_type: "Basic Land", sub_type: "Mountain"]) -> , new_card([name: "Forest", super_type: "Basic Land", sub_type: "Forest"]) -> ] - -When invoked, this script will add the five basic lands to the set. - +Data type: add cards script + +DOC_MSE_VERSION: since 0.3.7 + +--Overview-- + +A script to add multiple cards to the set at once. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] Name of this script; appears in the menu. +| @description@ [[type:string]] @""@ Description of this script; appears in the status bar. +| @enabled@ [[type:scriptable]] [[type:boolean]] @true@ Is this script enabled? +| @script@ [[type:script]] Script that produces the cards.
+ This script should return a [[type:list]] of [[type:card]]s. + The [[fun:new_card]] function can be used to make new cards. + +--Example-- +>add cards script: +> name: &Basic Lands +> description: Adds 5 basic lands to the set. +> script: +> [ new_card([name: "Plains", super_type: "Basic Land", sub_type: "Plains"]) +> , new_card([name: "Island", super_type: "Basic Land", sub_type: "Island"]) +> , new_card([name: "Swamp", super_type: "Basic Land", sub_type: "Swamp"]) +> , new_card([name: "Mountain", super_type: "Basic Land", sub_type: "Mountain"]) +> , new_card([name: "Forest", super_type: "Basic Land", sub_type: "Forest"]) +> ] + +When invoked, this script will add the five basic lands to the set. + diff --git a/doc/type/alignment.txt b/doc/type/alignment.txt index 02a5a462..e4277892 100644 --- a/doc/type/alignment.txt +++ b/doc/type/alignment.txt @@ -1,37 +1,37 @@ -Enumeration: alignment - -DOC_MSE_VERSION: changed in 0.3.8 - -Specifies how text and images are aligned in boxes. -An alignment consists of: -* horizontal alignment -* vertical alignment -* (optional) how to fill the text box -* (optional) when to fill the text box - ---Script syntax-- -In scripts, alignment is passed around as a string. - ---Possible values-- -The value is a combination of one or more flags, separated by spaces. -These flags can appear in any order. -! Value Description -| @left@ Horizontally, align at the left -| @center@ Horizontally, align in the middle -| @right@ Horizontally, align at the right -| @top@ Vertically, align at the top -| @middle@ Vertically, align in the middle -| @bottom@ Vertically, align at the bottom -| @justify@ Fill the box exactly, by moving words apart/together. -| @justify-all@ Fill the box exactly, by moving individual characters apart/together. -| @stretch@ Fill the box exactly, by stretching the text.
- For images: stretch them, but preserve the aspect ratio. -| @if-overflow@ Only apply @justify@, @justify-all@ and @stretch@ when the box is overfull. -| @force@ Also justify text at the end of a line in a multiline text field.
- Normally only lines ending in a soft line break are justified. - ---Examples-- -> alignment: top left -> alignment: middle center -> alignment: top left force justify if-overflow -> alignment: { "middle" + " " + "left" } +Enumeration: alignment + +DOC_MSE_VERSION: changed in 0.3.8 + +Specifies how text and images are aligned in boxes. +An alignment consists of: +* horizontal alignment +* vertical alignment +* (optional) how to fill the text box +* (optional) when to fill the text box + +--Script syntax-- +In scripts, alignment is passed around as a string. + +--Possible values-- +The value is a combination of one or more flags, separated by spaces. +These flags can appear in any order. +! Value Description +| @left@ Horizontally, align at the left +| @center@ Horizontally, align in the middle +| @right@ Horizontally, align at the right +| @top@ Vertically, align at the top +| @middle@ Vertically, align in the middle +| @bottom@ Vertically, align at the bottom +| @justify@ Fill the box exactly, by moving words apart/together. +| @justify-all@ Fill the box exactly, by moving individual characters apart/together. +| @stretch@ Fill the box exactly, by stretching the text.
+ For images: stretch them, but preserve the aspect ratio. +| @if-overflow@ Only apply @justify@, @justify-all@ and @stretch@ when the box is overfull. +| @force@ Also justify text at the end of a line in a multiline text field.
+ Normally only lines ending in a soft line break are justified. + +--Examples-- +> alignment: top left +> alignment: middle center +> alignment: top left force justify if-overflow +> alignment: { "middle" + " " + "left" } diff --git a/doc/type/boolean.txt b/doc/type/boolean.txt index c3e2f849..21f7d0cc 100644 --- a/doc/type/boolean.txt +++ b/doc/type/boolean.txt @@ -1,26 +1,26 @@ -Primitive type: boolean - -A boolean is either @true@ or @false@. - -In a script, numbers are implicitly converted to booleans, a non-zero number is @true@, 0 is @false@. - -When converted to a number, @true@ becomes @1@ and @false@ becomes @0@. - -The strings @"yes"@ and @"no"@ can also be converted to booleans. - ---File syntax-- -> boolean: true -> boolean: false - ---Script syntax-- -> true or false - -The operators @or@, @and@ and @xor@ combine two booleans: -! @a@ @b@ a or b a and b a xor b -| @false@ @false@ @false@ @false@ @false@ -| @false@ @true@ @true@ @false@ @true@ -| @true@ @false@ @true@ @false@ @true@ -| @true@ @true@ @true@ @true@ @false@ - ---See also-- -| [[fun:to_boolean]] Convert a value to a boolean +Primitive type: boolean + +A boolean is either @true@ or @false@. + +In a script, numbers are implicitly converted to booleans, a non-zero number is @true@, 0 is @false@. + +When converted to a number, @true@ becomes @1@ and @false@ becomes @0@. + +The strings @"yes"@ and @"no"@ can also be converted to booleans. + +--File syntax-- +> boolean: true +> boolean: false + +--Script syntax-- +> true or false + +The operators @or@, @and@ and @xor@ combine two booleans: +! @a@ @b@ a or b a and b a xor b +| @false@ @false@ @false@ @false@ @false@ +| @false@ @true@ @true@ @false@ @true@ +| @true@ @false@ @true@ @false@ @true@ +| @true@ @true@ @true@ @true@ @false@ + +--See also-- +| [[fun:to_boolean]] Convert a value to a boolean diff --git a/doc/type/card.txt b/doc/type/card.txt index c2b55e1d..5469a1ad 100644 --- a/doc/type/card.txt +++ b/doc/type/card.txt @@ -1,39 +1,39 @@ -Data type: card - ---Overview-- - -A '''card''' in a [[type:set]]. - ---Properties-- -! Property Type Default Description -| @stylesheet@ Name of a [[type:stylesheet]] ''none'' Use a different stylesheet for this card than the [[type:set]]'s default. -| @has styling@ [[type:boolean]] false This card has styling data different from the set's default. -| @styling data@ [[type:indexmap]] of [[type:value]]s false Styling data, based on the [[type:stylesheet]]'s @style fields@. -| @notes@ [[type:tagged string]] @""@ Notes for this card. -| @time created@ [[type:date]] ''now'' Time at which the card was created. -| @time modified@ [[type:date]] ''now'' Time at which the card was last modified. -| @extra data@ [[type:map]] of [[type:indexmap]]s of [[type:value]]s - Data for the 'extra card fields' of the stylesheet.
- This is first indexed by stylesheet name, then by field name. -| ''remaining keys'' [[type:indexmap]] of [[type:value]]s The remaining keys contain the data for the game's @card fields@.
- So for example @card.some_field@ corresponds to the value of the card field @some field@. - ---Examples-- - -With the following game: ->card field: -> type: text -> name: title ->card field: -> type: color -> name: card color - -A card could look like: ->card: -> stylesheet: new -> has styling: false -> notes: This card is not finished yet! -> styling data: -> extra large cards: true -> title: My Card -> card color: rgb(0,128,255) +Data type: card + +--Overview-- + +A '''card''' in a [[type:set]]. + +--Properties-- +! Property Type Default Description +| @stylesheet@ Name of a [[type:stylesheet]] ''none'' Use a different stylesheet for this card than the [[type:set]]'s default. +| @has styling@ [[type:boolean]] false This card has styling data different from the set's default. +| @styling data@ [[type:indexmap]] of [[type:value]]s false Styling data, based on the [[type:stylesheet]]'s @style fields@. +| @notes@ [[type:tagged string]] @""@ Notes for this card. +| @time created@ [[type:date]] ''now'' Time at which the card was created. +| @time modified@ [[type:date]] ''now'' Time at which the card was last modified. +| @extra data@ [[type:map]] of [[type:indexmap]]s of [[type:value]]s + Data for the 'extra card fields' of the stylesheet.
+ This is first indexed by stylesheet name, then by field name. +| ''remaining keys'' [[type:indexmap]] of [[type:value]]s The remaining keys contain the data for the game's @card fields@.
+ So for example @card.some_field@ corresponds to the value of the card field @some field@. + +--Examples-- + +With the following game: +>card field: +> type: text +> name: title +>card field: +> type: color +> name: card color + +A card could look like: +>card: +> stylesheet: new +> has styling: false +> notes: This card is not finished yet! +> styling data: +> extra large cards: true +> title: My Card +> card color: rgb(0,128,255) diff --git a/doc/type/choice.txt b/doc/type/choice.txt index 21be8b29..266d7bbf 100644 --- a/doc/type/choice.txt +++ b/doc/type/choice.txt @@ -1,43 +1,43 @@ -Data type: choice for a choice field - -A possible choice for a choice [[type:field]]. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''Required'' Name of this choice, displayed in the drop down list. -| @line below@ [[type:boolean]] @false@ Display a line below this item? -| @group choice@ [[type:string]] ''no'' Can this submenu of choices itself be selected? -| @choices@ [[type:list]] of [[type:choice]]s Submenu of choices. -| @enabled@ [[type:scriptable]] [[type:boolean]] Is this choice selectable? -| @type@ @"check"@ or @"radio"@ @"check"@ How should this choice be displayed? As a checkbox or a radio box?
- Only applies to multiple choice fields. - -A choice can also be given in a short form, in that case only the name is specified. - ---Names-- - -The full name of a choice is that of the choice and its parents, separated by spaces. -This is the value actually stored in values and manipulated by scripts. - -For example ->field: -> type: choice -> choice: -> name: large -> choice: red -> choice: blue -> choice: -> name: small -> group choice: just small -> choice: green -> choice: yellow - -The choice red is called @"large red"@, while green is @"small green"@. -The group choice 'just small' gets the name of the group, @"small"@. - ---Example-- -In short form: ->choice: apples -Is the same as: ->choice: -> name: apples +Data type: choice for a choice field + +A possible choice for a choice [[type:field]]. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''Required'' Name of this choice, displayed in the drop down list. +| @line below@ [[type:boolean]] @false@ Display a line below this item? +| @group choice@ [[type:string]] ''no'' Can this submenu of choices itself be selected? +| @choices@ [[type:list]] of [[type:choice]]s Submenu of choices. +| @enabled@ [[type:scriptable]] [[type:boolean]] Is this choice selectable? +| @type@ @"check"@ or @"radio"@ @"check"@ How should this choice be displayed? As a checkbox or a radio box?
+ Only applies to multiple choice fields. + +A choice can also be given in a short form, in that case only the name is specified. + +--Names-- + +The full name of a choice is that of the choice and its parents, separated by spaces. +This is the value actually stored in values and manipulated by scripts. + +For example +>field: +> type: choice +> choice: +> name: large +> choice: red +> choice: blue +> choice: +> name: small +> group choice: just small +> choice: green +> choice: yellow + +The choice red is called @"large red"@, while green is @"small green"@. +The group choice 'just small' gets the name of the group, @"small"@. + +--Example-- +In short form: +>choice: apples +Is the same as: +>choice: +> name: apples diff --git a/doc/type/choice_render_style.txt b/doc/type/choice_render_style.txt index 6a0e174b..c07d6bca 100644 --- a/doc/type/choice_render_style.txt +++ b/doc/type/choice_render_style.txt @@ -1,31 +1,31 @@ -Enumeration: render style - -A way to render a choice [[type:field]], see [[type:style]]. - ---Possible values-- -! Value Sketch Description -| @text@ - Rendered as text -| @image@ - Rendered as an image -| @both@ - Both an image and text -| @hidden@ - The box is hidden, but the value can still be edited. -| @image hidden@ - The box is hidden, but the value can still be edited. -| @checklist@ - A list of checkboxes, for multiple choice styles. -| @image checklist@ - A list of checkboxes with images instead of text. -| @both checklist@ - A list of checkboxes with both images and text. -| @text list@ - A list of the selected items, for multiple choice styles. -| @image list@ - A list of the selected items with images instead of text. -| @both list@ - A list of the selected items with both images and text. - ---Examples-- -> render style: image +Enumeration: render style + +A way to render a choice [[type:field]], see [[type:style]]. + +--Possible values-- +! Value Sketch Description +| @text@ + Rendered as text +| @image@ + Rendered as an image +| @both@ + Both an image and text +| @hidden@ + The box is hidden, but the value can still be edited. +| @image hidden@ + The box is hidden, but the value can still be edited. +| @checklist@ + A list of checkboxes, for multiple choice styles. +| @image checklist@ + A list of checkboxes with images instead of text. +| @both checklist@ + A list of checkboxes with both images and text. +| @text list@ + A list of the selected items, for multiple choice styles. +| @image list@ + A list of the selected items with images instead of text. +| @both list@ + A list of the selected items with both images and text. + +--Examples-- +> render style: image diff --git a/doc/type/color.txt b/doc/type/color.txt index 908a0c0c..5b23f310 100644 --- a/doc/type/color.txt +++ b/doc/type/color.txt @@ -1,32 +1,32 @@ -Primitive type: color - ---Syntax-- -In files and scritps a color can be represented as -
rgb(red_component, green_component, blue_component)
-where red_component, green_component and blue_component are numbers between 0 and 255 (inclusive). - -In some places MSE also supports colors with a transparency value, notated as -
rgba(red_component, green_component, blue_component, alpha_component)
-An alpha value of @0@ indicates a transparent color, an alpha value of @255@ is completely opaque. - ---Named colors-- -MSE also supports named colors, for instance @"white"@ is the same as @rgb(255,255,255)@. -For a full list of supported colors, see [[http://www.wxwidgets.org/manuals/stable/wx_wxcolourdatabase.html|the wxWidgets documentation]]. -In addition, the named color @"transparent"@ stands for the completely transparent color, @rgba(0,0,0,0)@. - -In scripts named colors are represented as [[type:string]]s. - ---Examples-- -For example: -! Code Represents <<< -| @rgb(255,255,255)@ white
-| @rgb(0,0,0)@ black
-| @rgb(255,0,0)@ red
-| @rgb(0,255,0)@ green
-| @rgb(0,0,255)@ blue
-| @rgba(0,0,0,0)@ transparent
over
-| @rgba(255,0,0,128)@ transparent red
over
-| @rgba(0,0,255,192)@ transparent blue
over
- ---See also-- -| [[fun:to_color]] Convert any value to a color +Primitive type: color + +--Syntax-- +In files and scritps a color can be represented as +
rgb(red_component, green_component, blue_component)
+where red_component, green_component and blue_component are numbers between 0 and 255 (inclusive). + +In some places MSE also supports colors with a transparency value, notated as +
rgba(red_component, green_component, blue_component, alpha_component)
+An alpha value of @0@ indicates a transparent color, an alpha value of @255@ is completely opaque. + +--Named colors-- +MSE also supports named colors, for instance @"white"@ is the same as @rgb(255,255,255)@. +For a full list of supported colors, see [[http://www.wxwidgets.org/manuals/stable/wx_wxcolourdatabase.html|the wxWidgets documentation]]. +In addition, the named color @"transparent"@ stands for the completely transparent color, @rgba(0,0,0,0)@. + +In scripts named colors are represented as [[type:string]]s. + +--Examples-- +For example: +! Code Represents <<< +| @rgb(255,255,255)@ white
+| @rgb(0,0,0)@ black
+| @rgb(255,0,0)@ red
+| @rgb(0,255,0)@ green
+| @rgb(0,0,255)@ blue
+| @rgba(0,0,0,0)@ transparent
over
+| @rgba(255,0,0,128)@ transparent red
over
+| @rgba(0,0,255,192)@ transparent blue
over
+ +--See also-- +| [[fun:to_color]] Convert any value to a color diff --git a/doc/type/color_choice.txt b/doc/type/color_choice.txt index d5742a9c..93005957 100644 --- a/doc/type/color_choice.txt +++ b/doc/type/color_choice.txt @@ -1,13 +1,13 @@ -Data type: choice for a color field - -A possible choice for a color [[type:field]]. - ---Properties-- -! Property Type Description -| @name@ [[type:string]] Name of this choice, displayed in the drop down list. -| @color@ opaque [[type:color]] Color this choice corresponds with. - ---Example-- ->choice: -> name: red -> color: rgb(255,0,0) +Data type: choice for a color field + +A possible choice for a color [[type:field]]. + +--Properties-- +! Property Type Description +| @name@ [[type:string]] Name of this choice, displayed in the drop down list. +| @color@ opaque [[type:color]] Color this choice corresponds with. + +--Example-- +>choice: +> name: red +> color: rgb(255,0,0) diff --git a/doc/type/combine.txt b/doc/type/combine.txt index 4994475c..436d12e4 100644 --- a/doc/type/combine.txt +++ b/doc/type/combine.txt @@ -1,41 +1,41 @@ -Enumeration: 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. - -The formula's are from [[http://www.pegtop.net/delphi/articles/blendmodes/]]. - ---Script syntax-- -In scripts, combine modes are stored as a string. - ---Possible values-- -! Value Description -| @normal@ Normal behaviour, don't combine. -| @add@ -| @subtract@ -| @stamp@ -| @difference@ -| @negation@ -| @multiply@ -| @darken@ -| @lighten@ -| @color dodge@ -| @color burn@ -| @screen@ -| @overlay@ -| @hard light@ -| @soft light@ -| @reflect@ -| @glow@ -| @freeze@ -| @heat@ -| and Bitwise and -| or Bitwise or -| xor Bitwise xot -| @shadow@ Dark colors normally, white colors darken the background. -| @symmetric overlay@ @(overlay(a,b) + overlay(b,a)) / 2@ - ---Examples-- -> combine: overlay -> combine_image(image1: ..., image2: ..., combine: "shadow") - +Enumeration: 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. + +The formula's are from [[http://www.pegtop.net/delphi/articles/blendmodes/]]. + +--Script syntax-- +In scripts, combine modes are stored as a string. + +--Possible values-- +! Value Description +| @normal@ Normal behaviour, don't combine. +| @add@ +| @subtract@ +| @stamp@ +| @difference@ +| @negation@ +| @multiply@ +| @darken@ +| @lighten@ +| @color dodge@ +| @color burn@ +| @screen@ +| @overlay@ +| @hard light@ +| @soft light@ +| @reflect@ +| @glow@ +| @freeze@ +| @heat@ +| and Bitwise and +| or Bitwise or +| xor Bitwise xot +| @shadow@ Dark colors normally, white colors darken the background. +| @symmetric overlay@ @(overlay(a,b) + overlay(b,a)) / 2@ + +--Examples-- +> combine: overlay +> combine_image(image1: ..., image2: ..., combine: "shadow") + diff --git a/doc/type/control_point.txt b/doc/type/control_point.txt index 4a81bf52..4e0a7d2c 100644 --- a/doc/type/control_point.txt +++ b/doc/type/control_point.txt @@ -1,24 +1,24 @@ -Data type: symbol control point - ---Overview-- - -A single [[http://en.wikipedia.org/wiki/Bezier_curve|Bézier curve]] control point in a [[type:symbol part|symbol shape]]. - -A control point is a point on the polygon. -It also optionally has two 'handles' corresponding to the boxes attached with dotted lines in the editor. - -The control points of a shape are circular, the point after the last point in the list is the first point. - ---Properties-- -! Property Type Default Description -| @position@ [[type:vector2d]] Position of the control point. -| @lock@ @free@, @direction@ or @size@ @"free"@ - Is this point 'locked', i.e. is the relation between the two handles fixed?
- If @lock@ is @"direction"@ then the two handles must lie on a line.
- If @lock@ is @"direction"@ then the two handles must lie exactly oppisite each other on the same distance from the point. -| @line after@ @line@ or @curve@ @"line"@ Is the segment between this control point and the next one in the list a straight line or a cubic Bézier curve? -| @handle before@ [[type:vector2d]] Position of the handle for the segment between this point and the previous one, relative to the point's @position@.
Only when that point's @line after == "curve"@. -| @handle after@ [[type:vector2d]] Position of the handle for the segment between this point and the next one, relative to the point's @position@.
Only when @line after == "curve"@. - ---Example-- -Look at a symbol file made with the program. +Data type: symbol control point + +--Overview-- + +A single [[http://en.wikipedia.org/wiki/Bezier_curve|Bézier curve]] control point in a [[type:symbol part|symbol shape]]. + +A control point is a point on the polygon. +It also optionally has two 'handles' corresponding to the boxes attached with dotted lines in the editor. + +The control points of a shape are circular, the point after the last point in the list is the first point. + +--Properties-- +! Property Type Default Description +| @position@ [[type:vector2d]] Position of the control point. +| @lock@ @free@, @direction@ or @size@ @"free"@ + Is this point 'locked', i.e. is the relation between the two handles fixed?
+ If @lock@ is @"direction"@ then the two handles must lie on a line.
+ If @lock@ is @"direction"@ then the two handles must lie exactly oppisite each other on the same distance from the point. +| @line after@ @line@ or @curve@ @"line"@ Is the segment between this control point and the next one in the list a straight line or a cubic Bézier curve? +| @handle before@ [[type:vector2d]] Position of the handle for the segment between this point and the previous one, relative to the point's @position@.
Only when that point's @line after == "curve"@. +| @handle after@ [[type:vector2d]] Position of the handle for the segment between this point and the next one, relative to the point's @position@.
Only when @line after == "curve"@. + +--Example-- +Look at a symbol file made with the program. diff --git a/doc/type/date.txt b/doc/type/date.txt index 09056472..4f292d65 100644 --- a/doc/type/date.txt +++ b/doc/type/date.txt @@ -1,13 +1,13 @@ -Primitive type: date and time - -DOC_MSE_VERSION: since 0.3.8 - -A point in time, consisting of a date and a time. -The file syntax uses [[http://en.wikipedia.org/wiki/ISO_8601|ISO 8601]] notation. - ---File syntax-- -> something: 2008-12-31 23:59:59 - ---See also-- -| [[fun:to_date]] Convert a value to a date -| [[fun:to_string]] Convert dates to strings +Primitive type: date and time + +DOC_MSE_VERSION: since 0.3.8 + +A point in time, consisting of a date and a time. +The file syntax uses [[http://en.wikipedia.org/wiki/ISO_8601|ISO 8601]] notation. + +--File syntax-- +> something: 2008-12-31 23:59:59 + +--See also-- +| [[fun:to_date]] Convert a value to a date +| [[fun:to_string]] Convert dates to strings diff --git a/doc/type/dependency.txt b/doc/type/dependency.txt index 774570aa..6f7c803b 100644 --- a/doc/type/dependency.txt +++ b/doc/type/dependency.txt @@ -1,21 +1,21 @@ -Data type: dependency - ---Overview-- - -[[type:Package]]s can depend on other packages. -For example a [[type:stylesheet]] needs a particular version of the corresponding [[type:game]] package, and maybe some additional [[type:include]]s. - ---Properties-- -! Property Type Description -| @package@ [[type:string]] Filename of the package this package depends on. -| @version@ [[type:version]] Minimal version of that package that is required. - -The two properties can also be written on a single line, separated by a space (see the examples). - ---Example-- -The magic-new stylesheet depends on a particular version of the game file: ->depends on: -> package: magic.mse-game -> version: 2007-06-06 -This can be written more compactly as ->depends on: magic.mse-game 2007-06-06 +Data type: dependency + +--Overview-- + +[[type:Package]]s can depend on other packages. +For example a [[type:stylesheet]] needs a particular version of the corresponding [[type:game]] package, and maybe some additional [[type:include]]s. + +--Properties-- +! Property Type Description +| @package@ [[type:string]] Filename of the package this package depends on. +| @version@ [[type:version]] Minimal version of that package that is required. + +The two properties can also be written on a single line, separated by a space (see the examples). + +--Example-- +The magic-new stylesheet depends on a particular version of the game file: +>depends on: +> package: magic.mse-game +> version: 2007-06-06 +This can be written more compactly as +>depends on: magic.mse-game 2007-06-06 diff --git a/doc/type/direction.txt b/doc/type/direction.txt index 5a3e1c9f..3375ba58 100644 --- a/doc/type/direction.txt +++ b/doc/type/direction.txt @@ -1,20 +1,20 @@ -Enumeration: direction - -Specifies the direction of text flow in a text box. - ---Script syntax-- -In scripts, direction is passed around as a string. - ---Possible values-- -! Value Description -| @left to right@ Text starts at the left. -| @right to left@ Text starts at the right ''(currently not implemented)'' -| @top to bottom@ Text starts at the top, each character is on a new line. -| @bottom to top@ Text starts at the bottom ''(currently not implemented)'' -| @horizontal@ Same as @left to right@. -| @vertical@ Same as @top to bottom@. - ---Examples-- -> direction: horizontal -> direction: top to bottom - +Enumeration: direction + +Specifies the direction of text flow in a text box. + +--Script syntax-- +In scripts, direction is passed around as a string. + +--Possible values-- +! Value Description +| @left to right@ Text starts at the left. +| @right to left@ Text starts at the right ''(currently not implemented)'' +| @top to bottom@ Text starts at the top, each character is on a new line. +| @bottom to top@ Text starts at the bottom ''(currently not implemented)'' +| @horizontal@ Same as @left to right@. +| @vertical@ Same as @top to bottom@. + +--Examples-- +> direction: horizontal +> direction: top to bottom + diff --git a/doc/type/double.txt b/doc/type/double.txt index 5a7c16ec..3bdcb107 100644 --- a/doc/type/double.txt +++ b/doc/type/double.txt @@ -1,16 +1,16 @@ -Primitive type: real number - -Real or floating point numbers are numbers with a decimal point. - -Conversion from integer to real numbers happens automatically in scripting. - ---File syntax-- -> something: 123 -> something: 0.5 - ---Script syntax-- -> 123.1 + 456 * -1 - ---See also-- -| [[type:int]] Integer numbers -| [[fun:to_real]] Convert a value to a real number +Primitive type: real number + +Real or floating point numbers are numbers with a decimal point. + +Conversion from integer to real numbers happens automatically in scripting. + +--File syntax-- +> something: 123 +> something: 0.5 + +--Script syntax-- +> 123.1 + 456 * -1 + +--See also-- +| [[type:int]] Integer numbers +| [[fun:to_real]] Convert a value to a real number diff --git a/doc/type/export_template.txt b/doc/type/export_template.txt index aafcae3d..ff186b54 100644 --- a/doc/type/export_template.txt +++ b/doc/type/export_template.txt @@ -1,52 +1,52 @@ -File type: Export template - ---Overview-- - -An export template describes a way for a set to be exported to a HTML or other text files. - ---Package format-- -An export template is described in a [[file:package]] with the .mse-export-template file extension. -Its name should begin with game- where game is the name of the game the template is made for. -It should contain a [[file:format|data file]] called export-template with the following properties. - ---Properties-- -! Property Type Default Description -| '''Common to all packages''' <<< <<< <<< -| @mse version@ [[type:version]] ''required'' Version of MSE this export template is made for. -| @short name@ [[type:string]] file name A short name of this export template, for the 'new set' and style panel lists. -| @full name@ [[type:string]] file name A longer name of this export template. -| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this export template, for the 'export to HTML' dialog. -| @position hint@ [[type:int]] ∞ Where to place this item in the list? Lower numbers come first. -| @version@ [[type:version]] @0.0.0@ Version number of this package. -| @depends on@ [[type:list]] of [[type:dependency]]s - Packages this package depends on. - -| '''Specific to export template''' <<< <<< <<< -| @game@ Name of a [[type:game]] ''required'' Game this export template is made for -| @file type@ [[type:string]] @"HTML files (*.html)|*.html"@ - File type to use, this is a list separated by @|@ characters. - Alternatingly, a human description and a file pattern to match are given. -| @create directory@ [[type:boolean]] @false@ Should a directory for data files be created? This is required for some script function. -| @option fields@ [[type:list]] of [[type:field]]s Fields for additional options to show. -| @option style@ [[type:indexmap]] of [[type:style]]s Styling for the @option fields@. -| @script@ [[type:script]] Script that generates the text that will be written to the exported file. - -During the evaluation of the script the following variables are available: -| @game@ The current game. -| @style@ The current stylesheet. -| @set@ The set being exported. -| @cards@ The cards selected by the user. -| @options@ The values of the @option fields@. -| @directory@ Name of the directory created (if @create directory@ is set). - ---See also-- -The following functions are made specifically for exporting to html: -| [[fun:to_html]] Convert [[type:tagged text]] to html. -| [[fun:symbols_to_html]] Convert text to html using a [[type:symbol font]]. -| [[fun:to_text]] Remove all tags from tagged text. -| [[fun:copy_file]] Copy a file from the [[type:export template]] to the output directory. -| [[fun:write_text_file]] Write a text file to the output directory. -| [[fun:write_image_file]] Write an image file to the output directory. - ---Example-- -Look at the @"magic-spoiler.mse-export-template"@ for an example. +File type: Export template + +--Overview-- + +An export template describes a way for a set to be exported to a HTML or other text files. + +--Package format-- +An export template is described in a [[file:package]] with the .mse-export-template file extension. +Its name should begin with game- where game is the name of the game the template is made for. +It should contain a [[file:format|data file]] called export-template with the following properties. + +--Properties-- +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this export template is made for. +| @short name@ [[type:string]] file name A short name of this export template, for the 'new set' and style panel lists. +| @full name@ [[type:string]] file name A longer name of this export template. +| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this export template, for the 'export to HTML' dialog. +| @position hint@ [[type:int]] ∞ Where to place this item in the list? Lower numbers come first. +| @version@ [[type:version]] @0.0.0@ Version number of this package. +| @depends on@ [[type:list]] of [[type:dependency]]s + Packages this package depends on. + +| '''Specific to export template''' <<< <<< <<< +| @game@ Name of a [[type:game]] ''required'' Game this export template is made for +| @file type@ [[type:string]] @"HTML files (*.html)|*.html"@ + File type to use, this is a list separated by @|@ characters. + Alternatingly, a human description and a file pattern to match are given. +| @create directory@ [[type:boolean]] @false@ Should a directory for data files be created? This is required for some script function. +| @option fields@ [[type:list]] of [[type:field]]s Fields for additional options to show. +| @option style@ [[type:indexmap]] of [[type:style]]s Styling for the @option fields@. +| @script@ [[type:script]] Script that generates the text that will be written to the exported file. + +During the evaluation of the script the following variables are available: +| @game@ The current game. +| @style@ The current stylesheet. +| @set@ The set being exported. +| @cards@ The cards selected by the user. +| @options@ The values of the @option fields@. +| @directory@ Name of the directory created (if @create directory@ is set). + +--See also-- +The following functions are made specifically for exporting to html: +| [[fun:to_html]] Convert [[type:tagged text]] to html. +| [[fun:symbols_to_html]] Convert text to html using a [[type:symbol font]]. +| [[fun:to_text]] Remove all tags from tagged text. +| [[fun:copy_file]] Copy a file from the [[type:export template]] to the output directory. +| [[fun:write_text_file]] Write a text file to the output directory. +| [[fun:write_image_file]] Write an image file to the output directory. + +--Example-- +Look at the @"magic-spoiler.mse-export-template"@ for an example. diff --git a/doc/type/field.txt b/doc/type/field.txt index 4ea22878..5d319061 100644 --- a/doc/type/field.txt +++ b/doc/type/field.txt @@ -1,129 +1,129 @@ -Data type: field - ---Overview-- - -A field is a description of a kind of 'container' to hold a value. - -For example the [[type:value]] of a 'text field' is a piece of text, that of a 'color field' a [[type:color]], etc. - -Things that are fields are, "card color" and "card name". -Not a particular color or name, but a description of what a card color and a card name are for a particular [[type:game]]. - -Fields are part of the [[file:style triangle]]: -| Description Looks Data -| [[type:Game]] [[type:Stylesheet]] [[type:Set]] -| '''Field''' [[type:Style]] [[type:Value]] - ---Properties-- -! Property Type Default Description -| @type@ One of: ''required'' Type of field. - * @text@ - * @choice@ - * @multiple choice@ - * @package choice@ - * @boolean@ - * @image@ - * @symbol@ - * @color@ - * @info@ -| @name@ [[type:string]] ''required'' Name of the field. -| @description@ [[type:string]] @""@ Description of the field, shown in the status bar when the mouse is over the field. -| @icon@ [[type:filename]] Filename of an icon for this field, used for automatically generated [[type:statistics category]]s. -| @editable@ [[type:boolean]] @true@ Can values of this field be edited? -| @save value@ [[type:boolean]] @true@ Should values of this field be saved to files? Should be disabled for values that are generated by scripts. -| @show statistics@ [[type:boolean]] @true@ Should a [[type:statistics dimension]] and [[type:statistics category|category]] be made for this field, - causing it to be listed on the statistics panel? -| @identifying@ [[type:boolean]] @false@ Does this field give the name of the [[type:card]] or [[type:set]]? -| @card list column@ [[type:int]] @0@ On what position in the card list should this field be put? -| @card list width@ [[type:int]] @100@ Width of the card list column in pixels. -| @card list visible@ [[type:boolean]] @false@ Should this field be shown in the card list by default? -| @card list allow@ [[type:boolean]] @true@ Should this field be allowed in the card list at all? -| @card list name@ [[type:string]] field name Alternate name to use for the card list, for example an abbreviation. -| @card list alignment@ [[type:alignment]] @left@ Alignment of the card list column. -| @sort script@ [[type:script]] Alternate way to sort the card list when using this column to sort the list. - -The @type@ determines what values of this field contain: -! Type Values contain Displayed as -| @text@ Text with markup (a [[type:tagged string]]) Text -| @choice@ A choice from a list Text or an image -| @multiple choice@ Zero or more choices from a list A single image or multiple images -| @package choice@ A choice from a list of installed [[type:package]]s Text and/or an image -| @boolean@ @yes@ or @no@ Text or an image or both -| @color@ Any color or a restricted selection from a list A box filled with the color -| @image@ Any image The image -| @symbol@ A [[type:symbol]] edited with the symbol editor The image -| @info@ An informational message, for example to group fields together. A box containing the label - -Additional properties are available, depending on the type of field: - -! Type Property Type Default Description -| @"text"@ @script@ [[type:script]] Script to apply to values of this field after each change.
- If the script evaluates to a constant (i.e. doesn't use @value@) then values in this field can effectively not be edited. -| ^^^ @default@ [[type:script]] Script to determine the value when it is in the default state (not edited). -| ^^^ @default name@ [[type:string]] @"Default"@ Name of the default state, currently not used. -| ^^^ @multi line@ [[type:boolean]] @false@ Can values of this field contain line breaks? - -| @"choice"@ @script@ [[type:script]] Script to apply to values of this field after each change.
- If the script evaluates to a constant (i.e. doesn't use @value@) then values in this field can effectively not be edited. -| ^^^ @default@ [[type:script]] Script to determine the value when it is in the default state (not edited). -| ^^^ @initial@ [[type:string]] Initial value for new values for this field. -| ^^^ @default name@ [[type:string]] @"Default"@ Name of the default state. -| ^^^ @choices@ [[type:list]] of [[type:choice]]s Possible values for this field. -| ^^^ @choice colors@ [[type:map]] of opaque [[type:color]]s Colors of the choices for statistics graphs. -| ^^^ @choice colors cardlist@ [[type:map]] of opaque [[type:color]]s Colors of the choices for lines in the card list,
see also the @card list color script@ property of [[type:game]]s. - -| @"multiple choice"@ <<< <<< <<< - '' Multiple choice fields have the same attributes as normal choice fields.''
- To refer to a combination of values in the initial attribute use @choice1, choice2, choice3@.
- These choices must appear in the same order as they do in the @choices@ property. - -| @"boolean"@ ''A boolean field is a choice field with the choices @"yes"@ and @"no"@.'' <<< <<< <<< - -| @"package choice"@ - @script@ [[type:script]] Script to apply to values of this field after each change.
- If the script evaluates to a constant (i.e. doesn't use @value@) then values in this field can effectively not be edited. -| ^^^ @match@ [[type:string]] ''required'' Filenames of the packages to match, can include wildcards @"*"@. For example @"magic-mana-*.mse-symbol-font"@. -| ^^^ @initial@ [[type:string]] ''required'' Initial package for new values for this field. -| ^^^ @reqired@ [[type:boolean]] @true@ Must a package always be selected? Or is it allowed to select nothing? -| ^^^ @empty name@ [[type:string]] @"None"@ Name of the empty state. Applies only if @required: false@. - -| @"color"@ @script@ [[type:script]] Script to apply to values of this field after each change.
- If the script evaluates to a constant (i.e. doesn't use @value@) then values in this field can effectively not be edited. -| ^^^ @default@ [[type:script]] Script to determine the value when it is in the default state (not edited). -| ^^^ @initial@ [[type:string]] Initial color for new values for this field. -| ^^^ @default name@ [[type:string]] @"Default"@ Name of the default state. -| ^^^ @allow custom@ [[type:boolean]] @true@ Are colors other then those from the choices allowed? -| ^^^ @choices@ [[type:list]] of [[type:color choice]]s Possible values for this field. - -| @"image"@ ''no extra properties'' <<< <<< <<< - -| @"symbol"@ ''no extra properties'' <<< <<< <<< - -| @"info"@ @script@ [[type:script]] Script to determine the value to show. - ---Example-- -The @title@ field gives the title of a set: ->set field: -> type: text -> name: title -> identifying: true - -The border color of cards can be selected from a list of choices, but other values are also possible. -The default is based on a set field. Statistics don't make much sense for the border color. ->card field: -> type: color -> name: border color -> default: set.border_color -> choice: -> name: black -> color: rgb(0,0,0) -> choice: -> name: white -> color: rgb(255,255,255) -> choice: -> name: silver -> color: rgb(128,128,128) -> choice: -> name: gold -> color: rgb(200,180,0) -> show statistics: false +Data type: field + +--Overview-- + +A field is a description of a kind of 'container' to hold a value. + +For example the [[type:value]] of a 'text field' is a piece of text, that of a 'color field' a [[type:color]], etc. + +Things that are fields are, "card color" and "card name". +Not a particular color or name, but a description of what a card color and a card name are for a particular [[type:game]]. + +Fields are part of the [[file:style triangle]]: +| Description Looks Data +| [[type:Game]] [[type:Stylesheet]] [[type:Set]] +| '''Field''' [[type:Style]] [[type:Value]] + +--Properties-- +! Property Type Default Description +| @type@ One of: ''required'' Type of field. + * @text@ + * @choice@ + * @multiple choice@ + * @package choice@ + * @boolean@ + * @image@ + * @symbol@ + * @color@ + * @info@ +| @name@ [[type:string]] ''required'' Name of the field. +| @description@ [[type:string]] @""@ Description of the field, shown in the status bar when the mouse is over the field. +| @icon@ [[type:filename]] Filename of an icon for this field, used for automatically generated [[type:statistics category]]s. +| @editable@ [[type:boolean]] @true@ Can values of this field be edited? +| @save value@ [[type:boolean]] @true@ Should values of this field be saved to files? Should be disabled for values that are generated by scripts. +| @show statistics@ [[type:boolean]] @true@ Should a [[type:statistics dimension]] and [[type:statistics category|category]] be made for this field, + causing it to be listed on the statistics panel? +| @identifying@ [[type:boolean]] @false@ Does this field give the name of the [[type:card]] or [[type:set]]? +| @card list column@ [[type:int]] @0@ On what position in the card list should this field be put? +| @card list width@ [[type:int]] @100@ Width of the card list column in pixels. +| @card list visible@ [[type:boolean]] @false@ Should this field be shown in the card list by default? +| @card list allow@ [[type:boolean]] @true@ Should this field be allowed in the card list at all? +| @card list name@ [[type:string]] field name Alternate name to use for the card list, for example an abbreviation. +| @card list alignment@ [[type:alignment]] @left@ Alignment of the card list column. +| @sort script@ [[type:script]] Alternate way to sort the card list when using this column to sort the list. + +The @type@ determines what values of this field contain: +! Type Values contain Displayed as +| @text@ Text with markup (a [[type:tagged string]]) Text +| @choice@ A choice from a list Text or an image +| @multiple choice@ Zero or more choices from a list A single image or multiple images +| @package choice@ A choice from a list of installed [[type:package]]s Text and/or an image +| @boolean@ @yes@ or @no@ Text or an image or both +| @color@ Any color or a restricted selection from a list A box filled with the color +| @image@ Any image The image +| @symbol@ A [[type:symbol]] edited with the symbol editor The image +| @info@ An informational message, for example to group fields together. A box containing the label + +Additional properties are available, depending on the type of field: + +! Type Property Type Default Description +| @"text"@ @script@ [[type:script]] Script to apply to values of this field after each change.
+ If the script evaluates to a constant (i.e. doesn't use @value@) then values in this field can effectively not be edited. +| ^^^ @default@ [[type:script]] Script to determine the value when it is in the default state (not edited). +| ^^^ @default name@ [[type:string]] @"Default"@ Name of the default state, currently not used. +| ^^^ @multi line@ [[type:boolean]] @false@ Can values of this field contain line breaks? + +| @"choice"@ @script@ [[type:script]] Script to apply to values of this field after each change.
+ If the script evaluates to a constant (i.e. doesn't use @value@) then values in this field can effectively not be edited. +| ^^^ @default@ [[type:script]] Script to determine the value when it is in the default state (not edited). +| ^^^ @initial@ [[type:string]] Initial value for new values for this field. +| ^^^ @default name@ [[type:string]] @"Default"@ Name of the default state. +| ^^^ @choices@ [[type:list]] of [[type:choice]]s Possible values for this field. +| ^^^ @choice colors@ [[type:map]] of opaque [[type:color]]s Colors of the choices for statistics graphs. +| ^^^ @choice colors cardlist@ [[type:map]] of opaque [[type:color]]s Colors of the choices for lines in the card list,
see also the @card list color script@ property of [[type:game]]s. + +| @"multiple choice"@ <<< <<< <<< + '' Multiple choice fields have the same attributes as normal choice fields.''
+ To refer to a combination of values in the initial attribute use @choice1, choice2, choice3@.
+ These choices must appear in the same order as they do in the @choices@ property. + +| @"boolean"@ ''A boolean field is a choice field with the choices @"yes"@ and @"no"@.'' <<< <<< <<< + +| @"package choice"@ + @script@ [[type:script]] Script to apply to values of this field after each change.
+ If the script evaluates to a constant (i.e. doesn't use @value@) then values in this field can effectively not be edited. +| ^^^ @match@ [[type:string]] ''required'' Filenames of the packages to match, can include wildcards @"*"@. For example @"magic-mana-*.mse-symbol-font"@. +| ^^^ @initial@ [[type:string]] ''required'' Initial package for new values for this field. +| ^^^ @reqired@ [[type:boolean]] @true@ Must a package always be selected? Or is it allowed to select nothing? +| ^^^ @empty name@ [[type:string]] @"None"@ Name of the empty state. Applies only if @required: false@. + +| @"color"@ @script@ [[type:script]] Script to apply to values of this field after each change.
+ If the script evaluates to a constant (i.e. doesn't use @value@) then values in this field can effectively not be edited. +| ^^^ @default@ [[type:script]] Script to determine the value when it is in the default state (not edited). +| ^^^ @initial@ [[type:string]] Initial color for new values for this field. +| ^^^ @default name@ [[type:string]] @"Default"@ Name of the default state. +| ^^^ @allow custom@ [[type:boolean]] @true@ Are colors other then those from the choices allowed? +| ^^^ @choices@ [[type:list]] of [[type:color choice]]s Possible values for this field. + +| @"image"@ ''no extra properties'' <<< <<< <<< + +| @"symbol"@ ''no extra properties'' <<< <<< <<< + +| @"info"@ @script@ [[type:script]] Script to determine the value to show. + +--Example-- +The @title@ field gives the title of a set: +>set field: +> type: text +> name: title +> identifying: true + +The border color of cards can be selected from a list of choices, but other values are also possible. +The default is based on a set field. Statistics don't make much sense for the border color. +>card field: +> type: color +> name: border color +> default: set.border_color +> choice: +> name: black +> color: rgb(0,0,0) +> choice: +> name: white +> color: rgb(255,255,255) +> choice: +> name: silver +> color: rgb(128,128,128) +> choice: +> name: gold +> color: rgb(200,180,0) +> show statistics: false diff --git a/doc/type/filename.txt b/doc/type/filename.txt index bb0942b5..b40f3bc1 100644 --- a/doc/type/filename.txt +++ b/doc/type/filename.txt @@ -1,20 +1,20 @@ -Primitve type: filename - -Filenames are regular [[type:string]]s, pointing to a file. -There are two types of filenames, relative and absolute: -! Syntax Description -| path/to/file A relative file, this is retrieved from the current package. - i.e. for a filename in a stylesheet, the file is retrieved from that stylesheet. -| /package/path/to/file An absolute filename includes the name of the package. This is a package somewhere in the MSE data directory. - -Don't forget the double quotes (@""@) in scripts. - ---Dependencies-- -When using an absolute filename to refer to a file from another [[file:package]], -the [[type:dependency]] on that package must be declared. -For example, ->include file: /common.mse-include/something -Will give a warning message, unless the file also lists ->depends on: -> package: common.mse-include -> version: 2007-01-01 +Primitve type: filename + +Filenames are regular [[type:string]]s, pointing to a file. +There are two types of filenames, relative and absolute: +! Syntax Description +| path/to/file A relative file, this is retrieved from the current package. + i.e. for a filename in a stylesheet, the file is retrieved from that stylesheet. +| /package/path/to/file An absolute filename includes the name of the package. This is a package somewhere in the MSE data directory. + +Don't forget the double quotes (@""@) in scripts. + +--Dependencies-- +When using an absolute filename to refer to a file from another [[file:package]], +the [[type:dependency]] on that package must be declared. +For example, +>include file: /common.mse-include/something +Will give a warning message, unless the file also lists +>depends on: +> package: common.mse-include +> version: 2007-01-01 diff --git a/doc/type/font.txt b/doc/type/font.txt index ea3c24f3..2492d065 100644 --- a/doc/type/font.txt +++ b/doc/type/font.txt @@ -1,29 +1,29 @@ -Data type: font - ---Overview-- - -A reference to a normal [[type:font]] for drawing text. - ---Properties-- -! Property Type Default Description -| @name@ [[type:scriptable]] [[type:string]] ''required'' Name of the font as it appears in most text programs. -| @italic name@ [[type:scriptable]] [[type:string]] Optionally, a different font to use for italic text instead of the normal italic version of the font. -| @size@ [[type:scriptable]] [[type:double]] ''required'' Size of the font in points on a 96 DPI display. -| @scale down to@ [[type:double]] ∞ Minimum size in points to scale the size down to. -| @max stretch@ [[type:double]] @1.0@ Maximum multiplier by which the width of the text is compressed, so @max width: 0.5@ means the text can be compressed to half the normal width. -| @weight@ [[type:scriptable]] font weight @"normal"@ Weight of the font, one of @"normal"@ or @"bold"@. This can be changed locally by [[type:tagged string|tags]]. -| @style@ [[type:scriptable]] font style @"normal"@ Style of the font, one of @"normal"@ or @"italic"@. This can be changed locally by [[type:tagged string|tags]]. -| @underline@ [[type:scriptable]] [[type:boolean]] @false@ Should the font be underlined? -| @color@ [[type:scriptable]] [[type:color]] @rgb(0,0,0)@ What color should text be drawn in? -| @shadow color@ [[type:scriptable]] [[type:color]] @"transparent"@ Color for a shadow below the text. -| @shadow displacement x@ [[type:double]] @0@ Relative position of the shadow in pixels. -| @shadow displacement y@ [[type:double]] @0@ ^^^ -| @shadow blur@ [[type:double]] @0@ How much should the shadow be blurred? -| @separator color@ [[type:color]] @rgba(0,0,0,128)@ Color for @@ tags inserted by the [[fun:combined_editor]] function. - ---Example-- ->font: -> name: Times new Roman -> size: 17 -> weight: bold -> color: rgb(0,0,0) +Data type: font + +--Overview-- + +A reference to a normal [[type:font]] for drawing text. + +--Properties-- +! Property Type Default Description +| @name@ [[type:scriptable]] [[type:string]] ''required'' Name of the font as it appears in most text programs. +| @italic name@ [[type:scriptable]] [[type:string]] Optionally, a different font to use for italic text instead of the normal italic version of the font. +| @size@ [[type:scriptable]] [[type:double]] ''required'' Size of the font in points on a 96 DPI display. +| @scale down to@ [[type:double]] ∞ Minimum size in points to scale the size down to. +| @max stretch@ [[type:double]] @1.0@ Maximum multiplier by which the width of the text is compressed, so @max width: 0.5@ means the text can be compressed to half the normal width. +| @weight@ [[type:scriptable]] font weight @"normal"@ Weight of the font, one of @"normal"@ or @"bold"@. This can be changed locally by [[type:tagged string|tags]]. +| @style@ [[type:scriptable]] font style @"normal"@ Style of the font, one of @"normal"@ or @"italic"@. This can be changed locally by [[type:tagged string|tags]]. +| @underline@ [[type:scriptable]] [[type:boolean]] @false@ Should the font be underlined? +| @color@ [[type:scriptable]] [[type:color]] @rgb(0,0,0)@ What color should text be drawn in? +| @shadow color@ [[type:scriptable]] [[type:color]] @"transparent"@ Color for a shadow below the text. +| @shadow displacement x@ [[type:double]] @0@ Relative position of the shadow in pixels. +| @shadow displacement y@ [[type:double]] @0@ ^^^ +| @shadow blur@ [[type:double]] @0@ How much should the shadow be blurred? +| @separator color@ [[type:color]] @rgba(0,0,0,128)@ Color for @@ tags inserted by the [[fun:combined_editor]] function. + +--Example-- +>font: +> name: Times new Roman +> size: 17 +> weight: bold +> color: rgb(0,0,0) diff --git a/doc/type/function.txt b/doc/type/function.txt index cabaeea9..9daee8bf 100644 --- a/doc/type/function.txt +++ b/doc/type/function.txt @@ -1,20 +1,20 @@ -Primitive type: function - ---Overview-- -The [[script:index|scripting language]] allows you to define custom functions. - ---Syntax-- -A piece of code enclosed in curly braces defines a function. - -A function can be called using parentheses, for example @function(argument:value)@. - ---Composition-- -Functions can be composed using the @+@ operator, evaluating @a + b@ first evaluates @a@ and uses its result as @input@ for @b@: -> example := to_upper + { "result == {input}" } -> example("xyz") == "result == XYZ" - -Multiple functions can be changed together like this, this is especially convenient in combination with [[script:default arguments]]. - ---Example-- -> example := { a + b } -> example(a: 1, b: 2) == 3 +Primitive type: function + +--Overview-- +The [[script:index|scripting language]] allows you to define custom functions. + +--Syntax-- +A piece of code enclosed in curly braces defines a function. + +A function can be called using parentheses, for example @function(argument:value)@. + +--Composition-- +Functions can be composed using the @+@ operator, evaluating @a + b@ first evaluates @a@ and uses its result as @input@ for @b@: +> example := to_upper + { "result == {input}" } +> example("xyz") == "result == XYZ" + +Multiple functions can be changed together like this, this is especially convenient in combination with [[script:default arguments]]. + +--Example-- +> example := { a + b } +> example(a: 1, b: 2) == 3 diff --git a/doc/type/game.txt b/doc/type/game.txt index ce2d5088..9ae201d8 100644 --- a/doc/type/game.txt +++ b/doc/type/game.txt @@ -1,51 +1,51 @@ -File type: Game - ---Overview-- - -Games are part of the [[file:style triangle]]: -| Description Looks Data -| '''Game''' [[type:Stylesheet]] [[type:Set]] -| [[type:Field]] [[type:Style]] [[type:Value]] - -Games provide the ''description'', i.e. what kinds of things are on a card. - ---Package format-- - -A game is described in a [[file:package]] with the .mse-game file extension. -Such a package contains a [[file:format|data file]] called game that has the following properties. - ---Properties-- -! Property Type Default Description -| '''Common to all packages''' <<< <<< <<< -| @mse version@ [[type:version]] ''required'' Version of MSE this game is made for. -| @short name@ [[type:string]] file name A short name of this game, for the 'new set' list. -| @full name@ [[type:string]] file name A longer name of this game. -| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this game, for the 'new set' list. -| @position hint@ [[type:int]] ∞ Where to place this item in the 'new set' list? Lower numbers come first. -| @version@ [[type:version]] @0.0.0@ Version number of this package. -| @depends on@ [[type:list]] of [[type:dependency]]s - Packages this package depends on. - -| '''Specific to games''' <<< <<< <<< -| @init script@ [[type:script]] @;@ Script to run when this game is loaded,
can set variables - to be used by other scripts in this game or stylesheets using it. -| @set fields@ [[type:list]] of [[type:field]]s Fields for the styling panel. -| @default set style@ [[type:indexmap]] of [[type:style]]s Default style for the set fields, can be overridden by the stylesheet. -| @card fields@ [[type:list]] of [[type:field]]s Fields for each card. -| @card list color script@ [[type:script]] from fields Script that determines the color of an item in the card list.
If not set uses the @card list colors@ property of the first card field that has it. -| @statistics dimensions@ [[type:list]] of [[type:statistics dimension]]s from fields Dimensions for statistics, a dimension is roughly the same as an axis.
By default all card fields with 'show statistics' set to true are used. -| @statistics categories@ [[type:list]] of [[type:statistics category]]s from dimensions DOC_MSE_VERSION: not used since 0.3.6 - Choices shown on the statistics panel.
By default all statistics dimensions are used. -| @pack types@ [[type:list]] of [[type:pack type]]s DOC_MSE_VERSION: since 0.3.7 - The types of card packs that will be listed on the random booster panel. -| @has keywords@ [[type:boolean]] @false@ Does this game use keywords? Should the keywords tab be available? -| @keyword match script@ [[type:script]] @;@ Script to apply to the @match@ property of keywords. -| @keyword modes@ [[type:list]] of [[type:keyword mode]]s Choices for the 'mode' property of keywords. -| @keyword parameter types@ [[type:list]] of [[type:keyword param type]]s Types of parameters available to keywords. -| @keywords@ [[type:list]] of [[type:keyword]]s Standard keywords for this game. -| @word lists@ [[type:list]] of [[type:word list]]s Word lists that can be used by text fields. -| @add cards script@ [[type:list]] of [[type:add cards script]]s DOC_MSE_VERSION: since 0.3.7 - A list of scripts for conveniently adding multiple cards to a set. - ---Examples-- -Look at the game files in the standard MSE distribution for examples. +File type: Game + +--Overview-- + +Games are part of the [[file:style triangle]]: +| Description Looks Data +| '''Game''' [[type:Stylesheet]] [[type:Set]] +| [[type:Field]] [[type:Style]] [[type:Value]] + +Games provide the ''description'', i.e. what kinds of things are on a card. + +--Package format-- + +A game is described in a [[file:package]] with the .mse-game file extension. +Such a package contains a [[file:format|data file]] called game that has the following properties. + +--Properties-- +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this game is made for. +| @short name@ [[type:string]] file name A short name of this game, for the 'new set' list. +| @full name@ [[type:string]] file name A longer name of this game. +| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this game, for the 'new set' list. +| @position hint@ [[type:int]] ∞ Where to place this item in the 'new set' list? Lower numbers come first. +| @version@ [[type:version]] @0.0.0@ Version number of this package. +| @depends on@ [[type:list]] of [[type:dependency]]s + Packages this package depends on. + +| '''Specific to games''' <<< <<< <<< +| @init script@ [[type:script]] @;@ Script to run when this game is loaded,
can set variables + to be used by other scripts in this game or stylesheets using it. +| @set fields@ [[type:list]] of [[type:field]]s Fields for the styling panel. +| @default set style@ [[type:indexmap]] of [[type:style]]s Default style for the set fields, can be overridden by the stylesheet. +| @card fields@ [[type:list]] of [[type:field]]s Fields for each card. +| @card list color script@ [[type:script]] from fields Script that determines the color of an item in the card list.
If not set uses the @card list colors@ property of the first card field that has it. +| @statistics dimensions@ [[type:list]] of [[type:statistics dimension]]s from fields Dimensions for statistics, a dimension is roughly the same as an axis.
By default all card fields with 'show statistics' set to true are used. +| @statistics categories@ [[type:list]] of [[type:statistics category]]s from dimensions DOC_MSE_VERSION: not used since 0.3.6 + Choices shown on the statistics panel.
By default all statistics dimensions are used. +| @pack types@ [[type:list]] of [[type:pack type]]s DOC_MSE_VERSION: since 0.3.7 + The types of card packs that will be listed on the random booster panel. +| @has keywords@ [[type:boolean]] @false@ Does this game use keywords? Should the keywords tab be available? +| @keyword match script@ [[type:script]] @;@ Script to apply to the @match@ property of keywords. +| @keyword modes@ [[type:list]] of [[type:keyword mode]]s Choices for the 'mode' property of keywords. +| @keyword parameter types@ [[type:list]] of [[type:keyword param type]]s Types of parameters available to keywords. +| @keywords@ [[type:list]] of [[type:keyword]]s Standard keywords for this game. +| @word lists@ [[type:list]] of [[type:word list]]s Word lists that can be used by text fields. +| @add cards script@ [[type:list]] of [[type:add cards script]]s DOC_MSE_VERSION: since 0.3.7 + A list of scripts for conveniently adding multiple cards to a set. + +--Examples-- +Look at the game files in the standard MSE distribution for examples. diff --git a/doc/type/graph_type.txt b/doc/type/graph_type.txt index 4994a5f0..a1a4f43e 100644 --- a/doc/type/graph_type.txt +++ b/doc/type/graph_type.txt @@ -1,21 +1,21 @@ -Enumeration: graph type - -Types of graphs for the statistics panel. - ---Possible values-- -The value is one of the following options: -! Value Dimensions Sketch Description -| @bar@ 1 bar graph - One bar for each value on the axis, the height represent the number of cards with that value. -| @pie@ 1 pie graph - A pie graph, the size of the slice represents the numer of cards with a particular value. -| @stack@ 2 stack graph - One bar for each value on the first axis, bars for each value on axis2 are stacked on top of each other. -| @scatter@ 2 scatter graph - Scatter plot, the size of the circles corresponds to the number of cards with those two values. -| @scatter pie@ 3 scatter-pie graph - Scatter plot, the size of the circles corresponds to the number of cards with those two values. - Each circle is a small pie graph for the third axis. - ---Examples-- -> type: bar +Enumeration: graph type + +Types of graphs for the statistics panel. + +--Possible values-- +The value is one of the following options: +! Value Dimensions Sketch Description +| @bar@ 1 bar graph + One bar for each value on the axis, the height represent the number of cards with that value. +| @pie@ 1 pie graph + A pie graph, the size of the slice represents the numer of cards with a particular value. +| @stack@ 2 stack graph + One bar for each value on the first axis, bars for each value on axis2 are stacked on top of each other. +| @scatter@ 2 scatter graph + Scatter plot, the size of the circles corresponds to the number of cards with those two values. +| @scatter pie@ 3 scatter-pie graph + Scatter plot, the size of the circles corresponds to the number of cards with those two values. + Each circle is a small pie graph for the third axis. + +--Examples-- +> type: bar diff --git a/doc/type/image.txt b/doc/type/image.txt index b28eb775..0d3fbf09 100644 --- a/doc/type/image.txt +++ b/doc/type/image.txt @@ -1,28 +1,28 @@ -Primitive type: image - -Images are generated using scripts. - -It is either given using a [[type:filename]] or as the output of a function. - ---File syntax-- -The syntax for files is similair to that of [[type:scriptable]] properties: -> image: image.png -> image: { "image.png" } -> image: { linear_blend(...) } - ---Script syntax-- -[[type:Filename]]s are implicitly converted to images as needed. - ---See also-- -The following functions transform 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:crop]] Crop an image, giving only a small subset of 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. +Primitive type: image + +Images are generated using scripts. + +It is either given using a [[type:filename]] or as the output of a function. + +--File syntax-- +The syntax for files is similair to that of [[type:scriptable]] properties: +> image: image.png +> image: { "image.png" } +> image: { linear_blend(...) } + +--Script syntax-- +[[type:Filename]]s are implicitly converted to images as needed. + +--See also-- +The following functions transform 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:crop]] Crop an image, giving only a small subset of 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. diff --git a/doc/type/include.txt b/doc/type/include.txt index d8d79f82..00a15541 100644 --- a/doc/type/include.txt +++ b/doc/type/include.txt @@ -1,22 +1,22 @@ -File type: Include package - ---Overview-- - -An include package contains files used by other packages, for example scripts or images. - ---Package format-- -An include package is described in a [[file:package]] with the .mse-include file extension. -It should contain a [[file:format|data file]] called include with the following properties. - ---Properties-- -! Property Type Default Description -| '''Common to all packages''' <<< <<< <<< -| @mse version@ [[type:version]] ''required'' Version of MSE this include package is made for. -| @short name@ [[type:string]] file name A short name of this include package, currently not used. -| @full name@ [[type:string]] file name A longer name of this include package, currently not used. -| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this export template, currently not used. -| @version@ [[type:version]] @0.0.0@ Version number of this package. -| @depends on@ [[type:list]] of [[type:dependency]]s - Packages this package depends on. - -No additional properties are available. +File type: Include package + +--Overview-- + +An include package contains files used by other packages, for example scripts or images. + +--Package format-- +An include package is described in a [[file:package]] with the .mse-include file extension. +It should contain a [[file:format|data file]] called include with the following properties. + +--Properties-- +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this include package is made for. +| @short name@ [[type:string]] file name A short name of this include package, currently not used. +| @full name@ [[type:string]] file name A longer name of this include package, currently not used. +| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this export template, currently not used. +| @version@ [[type:version]] @0.0.0@ Version number of this package. +| @depends on@ [[type:list]] of [[type:dependency]]s + Packages this package depends on. + +No additional properties are available. diff --git a/doc/type/index.txt b/doc/type/index.txt index 0e94f6ac..02ac89f0 100644 --- a/doc/type/index.txt +++ b/doc/type/index.txt @@ -1,69 +1,69 @@ -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. - ---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:Stylesheet]] 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:keyword mode]] A possible mode for keywords. -| [[type:keyword param type]] A type of parameters for keywords. -| [[type:statistics dimension]] A dimension for the statistics panel. -| [[type:statistics category]] A category for the statistics panel. -| [[type:word list]] A list of words that can be used for a drop down list in text fields. -| [[type:add cards script]] A script for convienently adding multiple cards to a set. -| [[type:font]] Description of a font. -| [[type:symbol part]] Part of a [[type:symbol]]. -| [[type:control point]] A point on in a symbol part. - ---Collection types-- -| [[type:list]] Lists of items - * item - * item - * item -| [[type:indexmap]] Lists indexed by field name - -
name:someone
type:something
-| [[type:map]] Lists indexed by other text - ---Script related-- -| [[type:script]] A script to execute to update a field, or for initialization. -| [[type:scriptable]] A primitive type whose value can depend on a script. -| [[type:image]] An image defined by a script. -| [[type:function]] Functions in scripts. These have no direct representation in a file. - ---Enumerations-- -| [[type:alignment]] Alignment of text and images. -| [[type:direction]] Direction of text. -| [[type:combine]] How to combine images with the background. -| [[type:symbol combine]] How to combine [[type:symbol part|symbol shapes]] with the background. -| [[type:graph type]] Type of statistics graphs. - ---Primitive types-- -| [[type:string]] Text, @"abc"@ -| [[type:tagged string]] Text with tags -| [[type:filename]] Filenames -| [[type:regex]] Regular expression strings -| [[type:boolean]] @true@ or @false@ -| [[type:int]] Integer numbers, @1, 2, 100@ -| [[type:double]] Real numbers, @1, 0.5, 21.3@ -| [[type:version]] Version numbers -| [[type:color]] Colors -| [[type:date]] Dates/times +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. + +--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:Stylesheet]] 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:keyword mode]] A possible mode for keywords. +| [[type:keyword param type]] A type of parameters for keywords. +| [[type:statistics dimension]] A dimension for the statistics panel. +| [[type:statistics category]] A category for the statistics panel. +| [[type:word list]] A list of words that can be used for a drop down list in text fields. +| [[type:add cards script]] A script for convienently adding multiple cards to a set. +| [[type:font]] Description of a font. +| [[type:symbol part]] Part of a [[type:symbol]]. +| [[type:control point]] A point on in a symbol part. + +--Collection types-- +| [[type:list]] Lists of items + * item + * item + * item +| [[type:indexmap]] Lists indexed by field name + +
name:someone
type:something
+| [[type:map]] Lists indexed by other text + +--Script related-- +| [[type:script]] A script to execute to update a field, or for initialization. +| [[type:scriptable]] A primitive type whose value can depend on a script. +| [[type:image]] An image defined by a script. +| [[type:function]] Functions in scripts. These have no direct representation in a file. + +--Enumerations-- +| [[type:alignment]] Alignment of text and images. +| [[type:direction]] Direction of text. +| [[type:combine]] How to combine images with the background. +| [[type:symbol combine]] How to combine [[type:symbol part|symbol shapes]] with the background. +| [[type:graph type]] Type of statistics graphs. + +--Primitive types-- +| [[type:string]] Text, @"abc"@ +| [[type:tagged string]] Text with tags +| [[type:filename]] Filenames +| [[type:regex]] Regular expression strings +| [[type:boolean]] @true@ or @false@ +| [[type:int]] Integer numbers, @1, 2, 100@ +| [[type:double]] Real numbers, @1, 0.5, 21.3@ +| [[type:version]] Version numbers +| [[type:color]] Colors +| [[type:date]] Dates/times diff --git a/doc/type/indexmap.txt b/doc/type/indexmap.txt index d9a19577..00daf399 100644 --- a/doc/type/indexmap.txt +++ b/doc/type/indexmap.txt @@ -1,33 +1,33 @@ -Collection type: field map - ---Overview-- - -A 'field map' is a [[type:map]], but indexed by [[type:field]]s. - -For instance if a game specifies the fields: ->field: -> type: text -> name: field1 ->field: -> type: color -> name: field2 - -Then the a field map of ''things'' for those fields would look like: ->field1: thing ->field2: thing - -A field map of [[type:style]]s would be: ->field1: # some text style for field1 goes here ->field2: # some color style for field2 goes here - -And a field map of [[type:value]]s would be: ->field1: text goes here ->field2: rgb(1,2,3) - ---Script syntax-- - -In a script field maps can be accessed like normal [[type:map]]s based on the field name. -So: ->card.field1 # retrieve the value of field1 ->card["field" + 1] # the same thing ->card_style.field2 # retrieve the styling for field2 +Collection type: field map + +--Overview-- + +A 'field map' is a [[type:map]], but indexed by [[type:field]]s. + +For instance if a game specifies the fields: +>field: +> type: text +> name: field1 +>field: +> type: color +> name: field2 + +Then the a field map of ''things'' for those fields would look like: +>field1: thing +>field2: thing + +A field map of [[type:style]]s would be: +>field1: # some text style for field1 goes here +>field2: # some color style for field2 goes here + +And a field map of [[type:value]]s would be: +>field1: text goes here +>field2: rgb(1,2,3) + +--Script syntax-- + +In a script field maps can be accessed like normal [[type:map]]s based on the field name. +So: +>card.field1 # retrieve the value of field1 +>card["field" + 1] # the same thing +>card_style.field2 # retrieve the styling for field2 diff --git a/doc/type/insert_symbol_menu.txt b/doc/type/insert_symbol_menu.txt index bca4bebf..61f0df5c 100644 --- a/doc/type/insert_symbol_menu.txt +++ b/doc/type/insert_symbol_menu.txt @@ -1,44 +1,44 @@ -Data type: "insert symbol" menu. - ---Overview-- - -A description of the "Insert symbol" menu for a specific [[type:symbol font]]. - -The menu consists of a number of entries, either items, separators or submenus. - ---Properties-- -! Property Type Default Description -| @type@ One of: @"code"@ or @"submenu"@ What type of menu item is this? - * @code@, inserts a symbol with the given code. - * @custom@, pops up a dialog where the user can choose a code to insert. - * @line@, a separating line. - * @submenu@, a submenu. -| @name@ [[type:string]] ''required'' Name of this menu item, corresponding to the code to insert. -| @items@ [[type:list]] of [[type:insert symbol menu|submenu items]] Items in the submenu, when items are present the @type@ is set to @"submenu"@. - -In the user interface the items are shown as @"menu item {name}"@, the [[type:locale]] should be used to give a beter label. - -For custom items the dialog will be titled @"title {name}"@ and have message text @"message {name}"@, again this should be changed in the locale. - ---Examples-- -A menu for magic mana symbols (simplified). Containing all types of items. ->insert symbol menu: -> item: -> type: custom -> name: colorless -> item: -> type: line -> item: W -> item: U -> item: B -> item: R -> item: G -> item: -> type: line -> item: -> name: hybrid -> item: W/U -> item: U/B -> item: B/R -> item: R/G -> item: G/W +Data type: "insert symbol" menu. + +--Overview-- + +A description of the "Insert symbol" menu for a specific [[type:symbol font]]. + +The menu consists of a number of entries, either items, separators or submenus. + +--Properties-- +! Property Type Default Description +| @type@ One of: @"code"@ or @"submenu"@ What type of menu item is this? + * @code@, inserts a symbol with the given code. + * @custom@, pops up a dialog where the user can choose a code to insert. + * @line@, a separating line. + * @submenu@, a submenu. +| @name@ [[type:string]] ''required'' Name of this menu item, corresponding to the code to insert. +| @items@ [[type:list]] of [[type:insert symbol menu|submenu items]] Items in the submenu, when items are present the @type@ is set to @"submenu"@. + +In the user interface the items are shown as @"menu item {name}"@, the [[type:locale]] should be used to give a beter label. + +For custom items the dialog will be titled @"title {name}"@ and have message text @"message {name}"@, again this should be changed in the locale. + +--Examples-- +A menu for magic mana symbols (simplified). Containing all types of items. +>insert symbol menu: +> item: +> type: custom +> name: colorless +> item: +> type: line +> item: W +> item: U +> item: B +> item: R +> item: G +> item: +> type: line +> item: +> name: hybrid +> item: W/U +> item: U/B +> item: B/R +> item: R/G +> item: G/W diff --git a/doc/type/int.txt b/doc/type/int.txt index 42d9554f..08dac006 100644 --- a/doc/type/int.txt +++ b/doc/type/int.txt @@ -1,14 +1,14 @@ -Primitive type: integer number - -Integer numbers are numbers without a decimal point. -In many cases negative numbers don't make sense, but the program never complains about them. - ---File syntax-- -> something: 123 - ---Script syntax-- -> 123 + 456 * -1 - ---See also-- -| [[type:double]] Number type that can contain fractional values. -| [[fun:to_int]] Convert a value to an integer number +Primitive type: integer number + +Integer numbers are numbers without a decimal point. +In many cases negative numbers don't make sense, but the program never complains about them. + +--File syntax-- +> something: 123 + +--Script syntax-- +> 123 + 456 * -1 + +--See also-- +| [[type:double]] Number type that can contain fractional values. +| [[fun:to_int]] Convert a value to an integer number diff --git a/doc/type/keyword.txt b/doc/type/keyword.txt index 6489b8fe..d5fa7ed0 100644 --- a/doc/type/keyword.txt +++ b/doc/type/keyword.txt @@ -1,27 +1,27 @@ -Data type: keyword - ---Overview-- - -A keyword in a [[type:set]] or a [[type:game]]. - -A keyword is something that matches a piece of text, and optionally some kind of reminder text can be shown. - ---Properties-- -! Property Type Default Description -| @keyword@ [[type:string]] ''required'' Name of the keyword. -| @match@ [[type:string]] ''required'' String to match. -| @reminder@ [[type:scriptable]] [[type:string]] ''required'' Script to generate the reminder text of this keyword. -| @rules@ [[type:string]] @""@ Explanation or additional rules for this keyword. -| @mode@ Name of a [[type:keyword mode]] Mode of this keyword. - -The match string can include parameters, @"type"@ where @"type"@ is the name of a [[type:keyword param type|keyword parameter type]] in the game. -These will match according to the @match@ property of that parameter type. - -When expanding the reminder text @param1@ refers to the first parameter in the match string, @param2@ to the second, etc. - ---Example-- ->keyword: -> keyword: Equip -> match: Equip cost -> mode: core -> reminder: {param1}: Attach to target creature you control. Equip only as a sorcery. +Data type: keyword + +--Overview-- + +A keyword in a [[type:set]] or a [[type:game]]. + +A keyword is something that matches a piece of text, and optionally some kind of reminder text can be shown. + +--Properties-- +! Property Type Default Description +| @keyword@ [[type:string]] ''required'' Name of the keyword. +| @match@ [[type:string]] ''required'' String to match. +| @reminder@ [[type:scriptable]] [[type:string]] ''required'' Script to generate the reminder text of this keyword. +| @rules@ [[type:string]] @""@ Explanation or additional rules for this keyword. +| @mode@ Name of a [[type:keyword mode]] Mode of this keyword. + +The match string can include parameters, @"type"@ where @"type"@ is the name of a [[type:keyword param type|keyword parameter type]] in the game. +These will match according to the @match@ property of that parameter type. + +When expanding the reminder text @param1@ refers to the first parameter in the match string, @param2@ to the second, etc. + +--Example-- +>keyword: +> keyword: Equip +> match: Equip cost +> mode: core +> reminder: {param1}: Attach to target creature you control. Equip only as a sorcery. diff --git a/doc/type/keyword_mode.txt b/doc/type/keyword_mode.txt index 4bb11288..16064c48 100644 --- a/doc/type/keyword_mode.txt +++ b/doc/type/keyword_mode.txt @@ -1,22 +1,22 @@ -Data type: keyword mode - ---Overview-- - -A mode for [[type:keyword]]s. - -This becomes a choice in the 'mode' box on the keywords panel. - -The idea behind modes is that a mode indicates what type of keyword it is, for example an "official" keyword, a "simple" keyword or a "custom" keyword. -This information can then be used to determine whether to expand the reminder text. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''required'' Name of the mode, this is shown in the box and used in scripts. -| @description@ [[type:string]] @""@ A description of this mode. -| @is default@ [[type:boolean]] @false@ Is this the default mode for new keywords? - ---Example-- ->keyword mode: -> name: custom -> description: Custom keywords -> is default: true +Data type: keyword mode + +--Overview-- + +A mode for [[type:keyword]]s. + +This becomes a choice in the 'mode' box on the keywords panel. + +The idea behind modes is that a mode indicates what type of keyword it is, for example an "official" keyword, a "simple" keyword or a "custom" keyword. +This information can then be used to determine whether to expand the reminder text. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''required'' Name of the mode, this is shown in the box and used in scripts. +| @description@ [[type:string]] @""@ A description of this mode. +| @is default@ [[type:boolean]] @false@ Is this the default mode for new keywords? + +--Example-- +>keyword mode: +> name: custom +> description: Custom keywords +> is default: true diff --git a/doc/type/keyword_param_reference_script.txt b/doc/type/keyword_param_reference_script.txt index 59919b87..968b8c34 100644 --- a/doc/type/keyword_param_reference_script.txt +++ b/doc/type/keyword_param_reference_script.txt @@ -1,25 +1,25 @@ -Data type: keyword parameter reference script - ---Overview-- - -A way to use a [[type:keyword param type|keyword parameter]] in a [[type:keyword]]'s reminder text. - -Usually the parameters are included as @"{param1}"@, etc. -But in some cases for instance a function should be applied, @"{fun(param1)}"@. - -To make this easy for the user, a menu of choices is provided, this type describes such a choice. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''required'' Name of the parameter type. -| @description@ [[type:string]] ''required'' A description of the reference script. -| @script@ [[type:script]] ''required'' Script that generates the code using the parameter.
- This means you will likely need to do some escaping.
- In the script, @input@ refers to the name of the parameter, for example @"param1"@. - ---Example-- -Apply the [[fun:english_number]] function to the parameter: ->refer script: -> name: as words -> description: (one, two, three) -> script: \{english_number({input})\} +Data type: keyword parameter reference script + +--Overview-- + +A way to use a [[type:keyword param type|keyword parameter]] in a [[type:keyword]]'s reminder text. + +Usually the parameters are included as @"{param1}"@, etc. +But in some cases for instance a function should be applied, @"{fun(param1)}"@. + +To make this easy for the user, a menu of choices is provided, this type describes such a choice. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''required'' Name of the parameter type. +| @description@ [[type:string]] ''required'' A description of the reference script. +| @script@ [[type:script]] ''required'' Script that generates the code using the parameter.
+ This means you will likely need to do some escaping.
+ In the script, @input@ refers to the name of the parameter, for example @"param1"@. + +--Example-- +Apply the [[fun:english_number]] function to the parameter: +>refer script: +> name: as words +> description: (one, two, three) +> script: \{english_number({input})\} diff --git a/doc/type/keyword_param_type.txt b/doc/type/keyword_param_type.txt index 52829d7e..fe6ab706 100644 --- a/doc/type/keyword_param_type.txt +++ b/doc/type/keyword_param_type.txt @@ -1,40 +1,40 @@ -Data type: keyword parameter type - ---Overview-- - -A type of parameter that can be used in a [[type:keyword]]. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''required'' Name of the parameter type. -| @description@ [[type:string]] ''required'' Description of the parameter type. -| @placeholder@ [[type:string]] @name@ of this param type Placeholder to use for empty parameters, the name is used if this is empty. -| @optional@ [[type:boolean]] @true@ Is a placeholder used when a keyword is encountered with no parameter,
for example @"Cycling "@ would become @"Cycling cost"@. -| @match@ [[type:regex]] ''required'' Regular expression that this param type matches. -| @separator before is@ [[type:regex]] @""@ Regular expression of separator before parameters of this type. -| @separator after is@ [[type:regex]] @""@ Regular expression of separator after parameters of this type. -| @eat separator@ [[type:boolean]] @true@ Allow the user to 'type over' the separator.
- For example if the separator is @" "@ in the keyword @"Cycling"@, and the user types @"Cycling"@, - a space and a placeholder is automatically inserted, making @"Cycling "@. - If the user now presses space the cursor is only moved, no additional space is inserted, the space is 'eaten'. -| @script@ [[type:script]] Script to apply to parameters of this type before substituting them back into the text. -| @reminder script@ [[type:script]] Script to apply to parameters of this type before using them in the reminder text. -| @example@ [[type:string]] Example for in the keyword editor, currently not used. -| @refer scripts@ [[type:list]] of [[type:keyword param reference script]]s - Scripts for inserting parameters of this type into the reminder text. - To make this easy for the user, a menu of ways to use a parameter is provided. - ---Example-- -The 'number' parameter type. It matches a sequence of digits. -It can be included in the reminder text directly, or by applying some function first. ->keyword parameter type: -> name: number -> match: [0-9]+ -> refer script: -> name: normal -> description: (1,2,3) -> script: \{{input}\} -> refer script: -> name: as words -> description: (one, two, three) -> script: \{english_number({input})\} +Data type: keyword parameter type + +--Overview-- + +A type of parameter that can be used in a [[type:keyword]]. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''required'' Name of the parameter type. +| @description@ [[type:string]] ''required'' Description of the parameter type. +| @placeholder@ [[type:string]] @name@ of this param type Placeholder to use for empty parameters, the name is used if this is empty. +| @optional@ [[type:boolean]] @true@ Is a placeholder used when a keyword is encountered with no parameter,
for example @"Cycling "@ would become @"Cycling cost"@. +| @match@ [[type:regex]] ''required'' Regular expression that this param type matches. +| @separator before is@ [[type:regex]] @""@ Regular expression of separator before parameters of this type. +| @separator after is@ [[type:regex]] @""@ Regular expression of separator after parameters of this type. +| @eat separator@ [[type:boolean]] @true@ Allow the user to 'type over' the separator.
+ For example if the separator is @" "@ in the keyword @"Cycling"@, and the user types @"Cycling"@, + a space and a placeholder is automatically inserted, making @"Cycling "@. + If the user now presses space the cursor is only moved, no additional space is inserted, the space is 'eaten'. +| @script@ [[type:script]] Script to apply to parameters of this type before substituting them back into the text. +| @reminder script@ [[type:script]] Script to apply to parameters of this type before using them in the reminder text. +| @example@ [[type:string]] Example for in the keyword editor, currently not used. +| @refer scripts@ [[type:list]] of [[type:keyword param reference script]]s + Scripts for inserting parameters of this type into the reminder text. + To make this easy for the user, a menu of ways to use a parameter is provided. + +--Example-- +The 'number' parameter type. It matches a sequence of digits. +It can be included in the reminder text directly, or by applying some function first. +>keyword parameter type: +> name: number +> match: [0-9]+ +> refer script: +> name: normal +> description: (1,2,3) +> script: \{{input}\} +> refer script: +> name: as words +> description: (one, two, three) +> script: \{english_number({input})\} diff --git a/doc/type/list.txt b/doc/type/list.txt index addf7c94..613c96e6 100644 --- a/doc/type/list.txt +++ b/doc/type/list.txt @@ -1,35 +1,35 @@ -Collection type: List - ---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 -> list[0+0] # The same thing - -It is possible to iterate over lists using the @for each@ construct: -> for each x in [1,2,3] do "x = {x}. " -evaluates to: -> "x = 1. x = 2. x = 3. " - ---Functions-- -There are several functions for working with lists: -| [[fun:position]] Find the position of an element in a list -| [[fun:number_of_items]] Return 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 +Collection type: List + +--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 +> list[0+0] # The same thing + +It is possible to iterate over lists using the @for each@ construct: +> for each x in [1,2,3] do "x = {x}. " +evaluates to: +> "x = 1. x = 2. x = 3. " + +--Functions-- +There are several functions for working with lists: +| [[fun:position]] Find the position of an element in a list +| [[fun:number_of_items]] Return 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 diff --git a/doc/type/locale.txt b/doc/type/locale.txt index e4378330..d74dc264 100644 --- a/doc/type/locale.txt +++ b/doc/type/locale.txt @@ -1,62 +1,62 @@ -File type: Locale - ---Overview-- - -A locale gives a translation of the user interface of the program. - ---Package format-- - -A locale is described in a [[file:package]] with the .mse-locale file extension. -Such a package contains a data file called locale that has the following properties. -There are usually no other files in the package. - ---Properties-- -! Property Type Default Description -| '''Common to all packages''' <<< <<< <<< -| @mse version@ [[type:version]] ''required'' Version of MSE this locale is made for. -| @short name@ [[type:string]] file name A short name of this locale, for the options dialog. -| @full name@ [[type:string]] file name A longer name of this locale. -| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this locale, currently not used. -| @version@ [[type:version]] @0.0.0@ Version number of this package. - -| '''Specific to locales''' <<< <<< <<< -| @menu@ [[type:map]] of [[type:string]]s Translations of menu items.
- Menu items can contain shortcut keys (like Ctrl+C for copy) by using a ''single'' TAB between the text and the shortcut key.
- Keys to use with Alt+Something (displayed underlined) can be specified &
- For example - >>>new set: &New... Ctrl+N -| @help@ [[type:map]] of [[type:string]]s Translations of help texts for the status bar. -| @tool@ [[type:map]] of [[type:string]]s Translations of toolbar item texts. -| @tooltip@ [[type:map]] of [[type:string]]s Translations of tooltips for toolbar items. -| @label@ [[type:map]] of [[type:string]]s Labels of controls in the GUI. -| @button@ [[type:map]] of [[type:string]]s Labels of buttons in the GUI. -| @title@ [[type:map]] of [[type:string]]s Titles of windows. -| @action@ [[type:map]] of [[type:string]]s Names of actions for undo/redo, things like "typing" and "add card". -| @error@ [[type:map]] of [[type:string]]s Error messages. -| @type@ [[type:map]] of [[type:string]]s Types of objects for error messages. -| @game@ [[type:map]] of [[type:map]] of [[type:string]]s - Translations for specific [[type:game]]s.
- Field names and field descriptions are looked up in the locale, if they are found the translation is used, otherwise the value from the game file.
- Extra keys not present in the English locale can be added here. -| @stylesheet@ [[type:map]] of [[type:map]] of [[type:string]]s - Translations for specific [[type:stylesheet]]s. -| @symbol font@ [[type:map]] of [[type:map]] of [[type:string]]s - Translations for specific [[type:symbol font]]s, in particular the "insert symbol" menu. - -Some of the items can contain placeholders for other values, for example: -> undo: &Undo%s Ctrl+Z -The @%s@ is replaced by the name of the action to undo. -This @%s@ should be used in exactly those entries that also contain it in the English locale. - ---Examples-- -Look at the @"en.mse-locale"@ file in the standard MSE distribution for an example. - ---Translating MSE-- -To translate the MSE user interface: -* Create a copy of the @"en.mse-locale"@ directory, name it @"**.mse-locale"@, where @"**"@ is a two or three letter [[http://en.wikipedia.org/wiki/ISO_language_code|ISO language code]]. -* Open the @"locale"@ file with Notepad (or another program that supports UTF-8), and translate the strings. -* Add new keys for game, stylesheet or symbol font specific keys as described above. -* Save the file, select the new locale from Edit->Preferences. -* Restart MSE, and make sure everything looks right. -* Submit the new locale to the [[http://magicseteditor.sourceforge.net/forum/7|MSE forum]. -* Maintain the locale when new versions of MSE come out. A new version may have new user interface items and therefore new keys. +File type: Locale + +--Overview-- + +A locale gives a translation of the user interface of the program. + +--Package format-- + +A locale is described in a [[file:package]] with the .mse-locale file extension. +Such a package contains a data file called locale that has the following properties. +There are usually no other files in the package. + +--Properties-- +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this locale is made for. +| @short name@ [[type:string]] file name A short name of this locale, for the options dialog. +| @full name@ [[type:string]] file name A longer name of this locale. +| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this locale, currently not used. +| @version@ [[type:version]] @0.0.0@ Version number of this package. + +| '''Specific to locales''' <<< <<< <<< +| @menu@ [[type:map]] of [[type:string]]s Translations of menu items.
+ Menu items can contain shortcut keys (like Ctrl+C for copy) by using a ''single'' TAB between the text and the shortcut key.
+ Keys to use with Alt+Something (displayed underlined) can be specified &
+ For example + >>>new set: &New... Ctrl+N +| @help@ [[type:map]] of [[type:string]]s Translations of help texts for the status bar. +| @tool@ [[type:map]] of [[type:string]]s Translations of toolbar item texts. +| @tooltip@ [[type:map]] of [[type:string]]s Translations of tooltips for toolbar items. +| @label@ [[type:map]] of [[type:string]]s Labels of controls in the GUI. +| @button@ [[type:map]] of [[type:string]]s Labels of buttons in the GUI. +| @title@ [[type:map]] of [[type:string]]s Titles of windows. +| @action@ [[type:map]] of [[type:string]]s Names of actions for undo/redo, things like "typing" and "add card". +| @error@ [[type:map]] of [[type:string]]s Error messages. +| @type@ [[type:map]] of [[type:string]]s Types of objects for error messages. +| @game@ [[type:map]] of [[type:map]] of [[type:string]]s + Translations for specific [[type:game]]s.
+ Field names and field descriptions are looked up in the locale, if they are found the translation is used, otherwise the value from the game file.
+ Extra keys not present in the English locale can be added here. +| @stylesheet@ [[type:map]] of [[type:map]] of [[type:string]]s + Translations for specific [[type:stylesheet]]s. +| @symbol font@ [[type:map]] of [[type:map]] of [[type:string]]s + Translations for specific [[type:symbol font]]s, in particular the "insert symbol" menu. + +Some of the items can contain placeholders for other values, for example: +> undo: &Undo%s Ctrl+Z +The @%s@ is replaced by the name of the action to undo. +This @%s@ should be used in exactly those entries that also contain it in the English locale. + +--Examples-- +Look at the @"en.mse-locale"@ file in the standard MSE distribution for an example. + +--Translating MSE-- +To translate the MSE user interface: +* Create a copy of the @"en.mse-locale"@ directory, name it @"**.mse-locale"@, where @"**"@ is a two or three letter [[http://en.wikipedia.org/wiki/ISO_language_code|ISO language code]]. +* Open the @"locale"@ file with Notepad (or another program that supports UTF-8), and translate the strings. +* Add new keys for game, stylesheet or symbol font specific keys as described above. +* Save the file, select the new locale from Edit->Preferences. +* Restart MSE, and make sure everything looks right. +* Submit the new locale to the [[http://magicseteditor.sourceforge.net/forum/7|MSE forum]. +* Maintain the locale when new versions of MSE come out. A new version may have new user interface items and therefore new keys. diff --git a/doc/type/map.txt b/doc/type/map.txt index 9dca952d..e104aef2 100644 --- a/doc/type/map.txt +++ b/doc/type/map.txt @@ -1,26 +1,26 @@ -Collection type: Map - -A map is like a [[type:list]] with [[type:string]] keys. - ---File syntax-- -In files a map is represented as key/value pairs. -For instance a map of [[type:color]]s could be: ->some map: -> red: rgb(255,0,0) -> green: rgb(0,255,0) -> blue: rgb(0,0,255) - ---Script syntax-- -In a script maps can be declared using square brackets. -> [] # An empty map -> [key:1] # A map with a single element, the value 1 under the key "key" -> [red:rgb(255,0,0), green:rgb(0,255,0)] # A map with two elements - -Like lists, maps can be accessed using either the bracket operator, or the dot operator. -> map.key # The elment named "key" -> map["k"+"ey"] # The same thing - -It is possible to iterate over the values maps using the @for@ construct: -> for each x in [one: 1, two: 2] do "x = {x}. " -evaluates to: -> "x = 1. x = 2. " +Collection type: Map + +A map is like a [[type:list]] with [[type:string]] keys. + +--File syntax-- +In files a map is represented as key/value pairs. +For instance a map of [[type:color]]s could be: +>some map: +> red: rgb(255,0,0) +> green: rgb(0,255,0) +> blue: rgb(0,0,255) + +--Script syntax-- +In a script maps can be declared using square brackets. +> [] # An empty map +> [key:1] # A map with a single element, the value 1 under the key "key" +> [red:rgb(255,0,0), green:rgb(0,255,0)] # A map with two elements + +Like lists, maps can be accessed using either the bracket operator, or the dot operator. +> map.key # The elment named "key" +> map["k"+"ey"] # The same thing + +It is possible to iterate over the values maps using the @for@ construct: +> for each x in [one: 1, two: 2] do "x = {x}. " +evaluates to: +> "x = 1. x = 2. " diff --git a/doc/type/pack_item.txt b/doc/type/pack_item.txt index f4b8291d..ccbfcb4e 100644 --- a/doc/type/pack_item.txt +++ b/doc/type/pack_item.txt @@ -1,25 +1,25 @@ -Data type: card pack item - -DOC_MSE_VERSION: since 0.3.8 - ---Overview-- - -A reference to another [[type:pack type]], from which one or more cards are chosen. - ---Properties-- -! Property Type Default Description -| @name@ Name of a [[type:pack item]] ''required'' Name of the pack item to include in this pack. -| @amount@ [[type:scriptable]] [[type:int]] 1 How many of those cards are in the pack? -| @weight@ [[type:scriptable]] [[type:double]] 1 How 'important' is this item? - Items with a higher weight will be chosen more often. - Cards from @filter@ will have a weight of 1. - ---Examples-- ->item: -> name: common -> amount: 11 - -Include 11 commons in this [[type:pack type|pack]]. - ->item: common -Short form. Include a single common in this pack. +Data type: card pack item + +DOC_MSE_VERSION: since 0.3.8 + +--Overview-- + +A reference to another [[type:pack type]], from which one or more cards are chosen. + +--Properties-- +! Property Type Default Description +| @name@ Name of a [[type:pack item]] ''required'' Name of the pack item to include in this pack. +| @amount@ [[type:scriptable]] [[type:int]] 1 How many of those cards are in the pack? +| @weight@ [[type:scriptable]] [[type:double]] 1 How 'important' is this item? + Items with a higher weight will be chosen more often. + Cards from @filter@ will have a weight of 1. + +--Examples-- +>item: +> name: common +> amount: 11 + +Include 11 commons in this [[type:pack type|pack]]. + +>item: common +Short form. Include a single common in this pack. diff --git a/doc/type/pack_type.txt b/doc/type/pack_type.txt index 27e4d328..6c6d94f5 100644 --- a/doc/type/pack_type.txt +++ b/doc/type/pack_type.txt @@ -1,109 +1,109 @@ -Data type: card pack type - -DOC_MSE_VERSION: since 0.3.8 - ---Overview-- - -A type of card packs. For instance "booster" and "tournament pack" are card pack types. - -A pack type contains either: -* a filter for selecting the desired kind of cards from the set. -* one or more [[type:pack item]]s, indicating what kinds and how many cards are in the pack. -* a combination of the above. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] Name of this card pack type. - Other pack types can refer to this name. -| @select@ see below see below How are instances of this pack generated? -| @enabled@ [[type:scriptable]] [[type:boolean]] @true@ Is this pack type enabled, i.e. can the user select it? -| @selectable@ [[type:boolean]] @true@ Is this pack selectable from the list of packs in the user interface? -| @summary@ [[type:boolean]] @true@ Is a summary of the total number of cards shown in the second panel in the user interface?
- Note: this only applies to pack types that have the @filter@ property set. -| @filter@ [[type:script]] ''optional'' Condition that a card must satisfy to be included in this pack type. -| @items@ [[type:list]] of [[type:pack item]]s The items to include in this pack. - ---Selection-- - -The @select@ property specifies how instances of this pack are generated. -When the user selects that he wants 3 copies of pack X, then MSE will generate three ''instances'' of that pack. -How that happens depends on the @select@ property: - -! @select@ Description -| @all@ Each instance of this pack type contains all of the filtered cards and @items@.
- In general, @select: all@ is used for the selectable pack types, while other @select@ types are used for the rest of the packs.
- This is the default for pack types with @items@. -| @replace@ Each instance of this pack type contains a single card or @item@, chosen at random with replacement. - The probability of picking an item is proportional to its @weight@, all filtered cards have weight 1. -| @no replace@ Each instance of this pack type contains a single card or @item@, chosen at random without replacement. - This means that the same card or item will not be chosen twice (if the set is large enough).
- This is the default for pack types with a @filter@. -| @proportional@ Each instance of this pack type contains a single filtered card or @item@, chosen with probability proportional to the number of choices for the card/item. - The choice is made with replacement. -| @nonempty@ Each instance of this pack type contains a single filtered card or @item@, - but items that contain no cards will be ignored. - The choice is made with replacement. -| @equal@ Instead of choosing cards and items at random, they are chosen to make their numbers as equal as possible. -| @equal proportional@ A combination of @equal@ and @proportional@. -| @equal nonempty@ A combination of @equal@ and @nonempty@. -| @first@ If there are any cards, the first is always chosen, otherwise the first ''nonempty'' item is used.
- @select: first@ can be used to make a kind of if statement: "If there are any X cards then use those, otherwise use Y cards". - ---Examples-- ->pack item: -> name: rare -> select: no replace # this is optional, 'no replace' is the default -> filter: card.rarity == "rare" - -Rare cards are those with the rarity value of @"rare"@. -The cards are chosen without replacement, so in a single pack the same rare will not occur twice. - ->pack item: -> name: basic land -> select: equal -> filter: card.rarity == "basic land" - -Basic land cards are selected in equal amounts: -Say a set contains two basic lands: "Good Land" and "Bad Land". -Then if 6 basic lands are selected, there will always be exactly 3 "Good Lands" and 3 "Bad Lands". -If an odd number of basic lands are selected then the amounts will be as close as possible to being equal. - - ->pack type: -> name: booster pack -> select: all # this is optional, 'all' is the default -> item: -> name: rare -> amount: 1 -> item: -> name: uncommon -> amount: 3 -> item: -> name: common -> amount: 11 - -A Magic booster pack contains 1 rare, 3 uncommons and 11 commons. - ->pack type: -> name: special or else common -> select: first -> item: special -> item: common - -If there are any special cards in the set, then "special or else common" will be a special card, otherwise it will be a common. - ->pack type: -> name: rare or mythic rare -> select: proportional -> item: -> name: rare -> weight: 2 -> item: -> name: mythic rare -> weight: 1 - -In Magic, individual "mythic rares" are twice as rare as normal rare cards. -Since there are also less mythic rares, this does not mean that each booster pack has a 33% percent chance of containing a mythic rare. -Instead the probability of a mythic rare is -@number_of_mythics / (number_of_rares * 2 + number_of_mythics)@. -So, for example if there are 20 rares in a set and only 5 mythic rares, then one in 9 "rare or mythic rare" cards will be a mythic rare. +Data type: card pack type + +DOC_MSE_VERSION: since 0.3.8 + +--Overview-- + +A type of card packs. For instance "booster" and "tournament pack" are card pack types. + +A pack type contains either: +* a filter for selecting the desired kind of cards from the set. +* one or more [[type:pack item]]s, indicating what kinds and how many cards are in the pack. +* a combination of the above. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] Name of this card pack type. + Other pack types can refer to this name. +| @select@ see below see below How are instances of this pack generated? +| @enabled@ [[type:scriptable]] [[type:boolean]] @true@ Is this pack type enabled, i.e. can the user select it? +| @selectable@ [[type:boolean]] @true@ Is this pack selectable from the list of packs in the user interface? +| @summary@ [[type:boolean]] @true@ Is a summary of the total number of cards shown in the second panel in the user interface?
+ Note: this only applies to pack types that have the @filter@ property set. +| @filter@ [[type:script]] ''optional'' Condition that a card must satisfy to be included in this pack type. +| @items@ [[type:list]] of [[type:pack item]]s The items to include in this pack. + +--Selection-- + +The @select@ property specifies how instances of this pack are generated. +When the user selects that he wants 3 copies of pack X, then MSE will generate three ''instances'' of that pack. +How that happens depends on the @select@ property: + +! @select@ Description +| @all@ Each instance of this pack type contains all of the filtered cards and @items@.
+ In general, @select: all@ is used for the selectable pack types, while other @select@ types are used for the rest of the packs.
+ This is the default for pack types with @items@. +| @replace@ Each instance of this pack type contains a single card or @item@, chosen at random with replacement. + The probability of picking an item is proportional to its @weight@, all filtered cards have weight 1. +| @no replace@ Each instance of this pack type contains a single card or @item@, chosen at random without replacement. + This means that the same card or item will not be chosen twice (if the set is large enough).
+ This is the default for pack types with a @filter@. +| @proportional@ Each instance of this pack type contains a single filtered card or @item@, chosen with probability proportional to the number of choices for the card/item. + The choice is made with replacement. +| @nonempty@ Each instance of this pack type contains a single filtered card or @item@, + but items that contain no cards will be ignored. + The choice is made with replacement. +| @equal@ Instead of choosing cards and items at random, they are chosen to make their numbers as equal as possible. +| @equal proportional@ A combination of @equal@ and @proportional@. +| @equal nonempty@ A combination of @equal@ and @nonempty@. +| @first@ If there are any cards, the first is always chosen, otherwise the first ''nonempty'' item is used.
+ @select: first@ can be used to make a kind of if statement: "If there are any X cards then use those, otherwise use Y cards". + +--Examples-- +>pack item: +> name: rare +> select: no replace # this is optional, 'no replace' is the default +> filter: card.rarity == "rare" + +Rare cards are those with the rarity value of @"rare"@. +The cards are chosen without replacement, so in a single pack the same rare will not occur twice. + +>pack item: +> name: basic land +> select: equal +> filter: card.rarity == "basic land" + +Basic land cards are selected in equal amounts: +Say a set contains two basic lands: "Good Land" and "Bad Land". +Then if 6 basic lands are selected, there will always be exactly 3 "Good Lands" and 3 "Bad Lands". +If an odd number of basic lands are selected then the amounts will be as close as possible to being equal. + + +>pack type: +> name: booster pack +> select: all # this is optional, 'all' is the default +> item: +> name: rare +> amount: 1 +> item: +> name: uncommon +> amount: 3 +> item: +> name: common +> amount: 11 + +A Magic booster pack contains 1 rare, 3 uncommons and 11 commons. + +>pack type: +> name: special or else common +> select: first +> item: special +> item: common + +If there are any special cards in the set, then "special or else common" will be a special card, otherwise it will be a common. + +>pack type: +> name: rare or mythic rare +> select: proportional +> item: +> name: rare +> weight: 2 +> item: +> name: mythic rare +> weight: 1 + +In Magic, individual "mythic rares" are twice as rare as normal rare cards. +Since there are also less mythic rares, this does not mean that each booster pack has a 33% percent chance of containing a mythic rare. +Instead the probability of a mythic rare is +@number_of_mythics / (number_of_rares * 2 + number_of_mythics)@. +So, for example if there are 20 rares in a set and only 5 mythic rares, then one in 9 "rare or mythic rare" cards will be a mythic rare. diff --git a/doc/type/regex.txt b/doc/type/regex.txt index f9d1ca81..22854fe7 100644 --- a/doc/type/regex.txt +++ b/doc/type/regex.txt @@ -1,10 +1,10 @@ -Primitive type: regular expression - -Regular expressions (regexes) are things that can match parts of [[type:string]]s. - -Regexes are represented by normal [[type:string]]s. -Note that to escape something in a regex the backslash is used, in script code this also needs to be escaped. -For example, in a script, the regex matching a single backslash is @"\\\\"@. - -For more information, see -[[http://www.wxwidgets.org/manuals/stable/wx_wxresyn.html|the wxWidgets regular expression documentation]]. +Primitive type: regular expression + +Regular expressions (regexes) are things that can match parts of [[type:string]]s. + +Regexes are represented by normal [[type:string]]s. +Note that to escape something in a regex the backslash is used, in script code this also needs to be escaped. +For example, in a script, the regex matching a single backslash is @"\\\\"@. + +For more information, see +[[http://www.wxwidgets.org/manuals/stable/wx_wxresyn.html|the wxWidgets regular expression documentation]]. diff --git a/doc/type/script.txt b/doc/type/script.txt index 171605a5..5fc231a6 100644 --- a/doc/type/script.txt +++ b/doc/type/script.txt @@ -1,19 +1,19 @@ -Data type: script - ---Overview-- - -A script object is a piece of code written in the [[script:index|MSE scripting language]]. - ---File syntax-- - -A script is given in the same way as a [[type:string]]. - ---Example-- -A simple [[type:field]] script that converts everything to upper case: ->script: to_upper(value) - -A larger script, changes @"y"@s to @"x"@s and @"a"@s to @"b"@s: ->script: -> new_value := replace(value, match: "x", replace: "y") -> new_value := replace(value, match: "a", replace: "b") -> new_value +Data type: script + +--Overview-- + +A script object is a piece of code written in the [[script:index|MSE scripting language]]. + +--File syntax-- + +A script is given in the same way as a [[type:string]]. + +--Example-- +A simple [[type:field]] script that converts everything to upper case: +>script: to_upper(value) + +A larger script, changes @"y"@s to @"x"@s and @"a"@s to @"b"@s: +>script: +> new_value := replace(value, match: "x", replace: "y") +> new_value := replace(value, match: "a", replace: "b") +> new_value diff --git a/doc/type/scriptable.txt b/doc/type/scriptable.txt index b0f4e973..79efedd2 100644 --- a/doc/type/scriptable.txt +++ b/doc/type/scriptable.txt @@ -1,34 +1,34 @@ -Data type: scriptable - ---Overview-- - -Many [[type:style]] properties are ''scriptable''; their value can be changed by a script. - -Consider for example: ->left: 123 -This defines that the left coordinate of a field is 123 pixels. -To script this you can write: ->left: { if card.name == "" then 100 else 123 } -Now the left position depends on whether or not the name is empty. - ---File syntax-- -A 'scriptable something' can take three forms: -# It can be a regular 'something' - >something: 123 -# It can be a script that produces 'something', enclosed in curly braces: - >something: {100 + 23} -# It can be a script that produces 'something', indented and preceded by @script:@: - >something: - > script: 100 + 23 - -Note: To use a multiline script the following does not work: ->something: { 100 + -> 23 } -If the script has multiple lines, it must start on a new line, and be indented with a TAB: ->something: -> { 100 + -> 23 } -or ->something: -> script: 100 + -> 23 +Data type: scriptable + +--Overview-- + +Many [[type:style]] properties are ''scriptable''; their value can be changed by a script. + +Consider for example: +>left: 123 +This defines that the left coordinate of a field is 123 pixels. +To script this you can write: +>left: { if card.name == "" then 100 else 123 } +Now the left position depends on whether or not the name is empty. + +--File syntax-- +A 'scriptable something' can take three forms: +# It can be a regular 'something' + >something: 123 +# It can be a script that produces 'something', enclosed in curly braces: + >something: {100 + 23} +# It can be a script that produces 'something', indented and preceded by @script:@: + >something: + > script: 100 + 23 + +Note: To use a multiline script the following does not work: +>something: { 100 + +> 23 } +If the script has multiple lines, it must start on a new line, and be indented with a TAB: +>something: +> { 100 + +> 23 } +or +>something: +> script: 100 + +> 23 diff --git a/doc/type/set.txt b/doc/type/set.txt index bbf9e0f2..c5ccf49b 100644 --- a/doc/type/set.txt +++ b/doc/type/set.txt @@ -1,64 +1,64 @@ -File type: Set - ---Overview-- - -Sets are part of the [[file:style triangle]]: -| Description Looks Data -| [[type:Game]] [[type:Stylesheet]] '''Set''' -| [[type:Field]] [[type:Style]] [[type:Value]] - ---Package format-- -A set is described in a [[file:package]] with the .mse-set file extension, -such a package contains a data file called set. - ---Properties-- -! Property Type Default Description -| '''Common to all packages''' <<< <<< <<< -| @mse version@ [[type:version]] ''required'' Version of MSE this set is made with. -| @short name@ [[type:string]] file name Name of this set. -| @depends on@ [[type:list]] of [[type:dependency]]s - Packages this package depends on. - -| '''Specific to sets''' <<< <<< <<< -| @game@ Name of a [[type:game]] ''required'' The game this set is made for. -| @stylesheet@ Name of a [[type:stylesheet]] ''required'' The default style for drawing cards in this set.
- This is without the game name or extension, so @"new"@ refers to the package @"gamename-new.mse-style"@. -| @set info@ [[type:indexmap]] of [[type:value]]s The data for the [[prop:game:set fields]] defined in the game. -| @styling@ [[type:map]] of [[type:indexmap]]s of [[type:value]]s - Data for the 'extra fields' of the stylesheet.
- This is first indexed by stylesheet name, then by field name.
- Data is given not only for the set's stylesheet but also for those of cards. -| @cards@ [[type:list] of [[type:card]]s The cards in the set. -| @keywords@ [[type:list] of [[type:keyword]]s The custom keywords in the set. -| @pack types@ [[type:list]] of [[type:pack type]]s DOC_MSE_VERSION: since 0.3.8 - The custom card pack types in the set. - ---Example-- - -If the game looks like: ->mse version: 0.3.4 ->name: my game ->set field: -> name: copyright -> type: text ->card field: -> name: card name -> type: text ->card field: -> name: power -> type: text -The the a set file would looks like: ->mse version: 0.3.4 ->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 +File type: Set + +--Overview-- + +Sets are part of the [[file:style triangle]]: +| Description Looks Data +| [[type:Game]] [[type:Stylesheet]] '''Set''' +| [[type:Field]] [[type:Style]] [[type:Value]] + +--Package format-- +A set is described in a [[file:package]] with the .mse-set file extension, +such a package contains a data file called set. + +--Properties-- +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this set is made with. +| @short name@ [[type:string]] file name Name of this set. +| @depends on@ [[type:list]] of [[type:dependency]]s + Packages this package depends on. + +| '''Specific to sets''' <<< <<< <<< +| @game@ Name of a [[type:game]] ''required'' The game this set is made for. +| @stylesheet@ Name of a [[type:stylesheet]] ''required'' The default style for drawing cards in this set.
+ This is without the game name or extension, so @"new"@ refers to the package @"gamename-new.mse-style"@. +| @set info@ [[type:indexmap]] of [[type:value]]s The data for the [[prop:game:set fields]] defined in the game. +| @styling@ [[type:map]] of [[type:indexmap]]s of [[type:value]]s + Data for the 'extra fields' of the stylesheet.
+ This is first indexed by stylesheet name, then by field name.
+ Data is given not only for the set's stylesheet but also for those of cards. +| @cards@ [[type:list] of [[type:card]]s The cards in the set. +| @keywords@ [[type:list] of [[type:keyword]]s The custom keywords in the set. +| @pack types@ [[type:list]] of [[type:pack type]]s DOC_MSE_VERSION: since 0.3.8 + The custom card pack types in the set. + +--Example-- + +If the game looks like: +>mse version: 0.3.4 +>name: my game +>set field: +> name: copyright +> type: text +>card field: +> name: card name +> type: text +>card field: +> name: power +> type: text +The the a set file would looks like: +>mse version: 0.3.4 +>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 diff --git a/doc/type/settings.txt b/doc/type/settings.txt index 87a7850b..2c79a538 100644 --- a/doc/type/settings.txt +++ b/doc/type/settings.txt @@ -1,13 +1,13 @@ -File type: Settings - ---Overview-- - -The MSE settings are stored in a separate file. - ---Location-- - -On Windows XP the settings are located in: -> "C:\Documents and Settings\Application Data\Magic Set Editor\mse8.config" - ---Properties-- -See the settings file for the properties. +File type: Settings + +--Overview-- + +The MSE settings are stored in a separate file. + +--Location-- + +On Windows XP the settings are located in: +> "C:\Documents and Settings\Application Data\Magic Set Editor\mse8.config" + +--Properties-- +See the settings file for the properties. diff --git a/doc/type/statistics_category.txt b/doc/type/statistics_category.txt index 619f95c5..4b5e3d16 100644 --- a/doc/type/statistics_category.txt +++ b/doc/type/statistics_category.txt @@ -1,29 +1,29 @@ -Data type: statistics category - -DOC_MSE_VERSION: not used since 0.3.6 - ---Overview-- - -A category in the statistics panel. -This is a single choice in the list on the left of that panel. - -Statistics dimensions are automatically generated for all [[type:statistics dimension]]s a [[type:game]]. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''required'' Name of this category. -| @description@ [[type:string]] @""@ A description of the category, currently not used. -| @position hint@ [[type:string]] @0@ Hint for ordering category, lower numbers are at the top of the list. -| @icon@ [[type:filename]] Filename of an icon for this category, the image should be 21x21 pixels. -| @type@ [[type:graph type]] @"bar"@ Type of graph to use. -| @dimensions@ [[type:list]] of names of [[type:statistics dimension]]s - Dimensions for the axes of the graph.
- The number of dimensions must be the same as that needed for the [[type:graph type]]. - ---Example-- -A graph with power on the horizontal axis, toughness on the vertical axis: ->statistics category: -> name: power/toughness -> type: scatter -> dimension: power -> dimension: toughness +Data type: statistics category + +DOC_MSE_VERSION: not used since 0.3.6 + +--Overview-- + +A category in the statistics panel. +This is a single choice in the list on the left of that panel. + +Statistics dimensions are automatically generated for all [[type:statistics dimension]]s a [[type:game]]. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''required'' Name of this category. +| @description@ [[type:string]] @""@ A description of the category, currently not used. +| @position hint@ [[type:string]] @0@ Hint for ordering category, lower numbers are at the top of the list. +| @icon@ [[type:filename]] Filename of an icon for this category, the image should be 21x21 pixels. +| @type@ [[type:graph type]] @"bar"@ Type of graph to use. +| @dimensions@ [[type:list]] of names of [[type:statistics dimension]]s + Dimensions for the axes of the graph.
+ The number of dimensions must be the same as that needed for the [[type:graph type]]. + +--Example-- +A graph with power on the horizontal axis, toughness on the vertical axis: +>statistics category: +> name: power/toughness +> type: scatter +> dimension: power +> dimension: toughness diff --git a/doc/type/statistics_dimension.txt b/doc/type/statistics_dimension.txt index ae6f800c..e244d8a1 100644 --- a/doc/type/statistics_dimension.txt +++ b/doc/type/statistics_dimension.txt @@ -1,48 +1,48 @@ -Data type: statistics dimension - ---Overview-- - -A dimension or axis for the statistics panel. - -One or more dimensions are combined in a graph, these combinations are called [[type:statistics category]]s. - -Statistics dimensions are automatically generated for all card fields in a [[type:game]] that don't set @show statistics@ to @false@. - -Categories are also automatically generated from dimensions. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''required'' Name of this dimension, used as an axis label and a label for automatically generated categories. -| @description@ [[type:string]] @""@ A description of the dimension, currently not used. -| @position hint@ [[type:string]] @0@ Hint for ordering dimensions. -| @icon@ [[type:filename]] Filename of an icon for this dimension. -| @script@ [[type:script]] ''required'' Script that generates a value for each card in the set. -| @numeric@ [[type:boolean]] @false@ Is the value always a number? -| @bin size@ [[type:double]] ''none'' For numeric dimensions: group numbers together into bins this large.
- For example with @bin size: 5@, values @1@ and @3@ both get put under @"1-5"@. -| @show empty@ [[type:boolean]] @false@ Should cards with the value @""@ be included? -| @split list@ [[type:boolean]] @false@ Indicates the value is a list of the form @"item1, item2"@. The card is put under both items. -| @colors@ [[type:map]] of opaque [[type:color]]s Colors to use for specific values -| @groups@ [[type:list]] of [[type:string]]s Values to always show, and the order to show them in. - ---Example-- -Automatically generated statistics dimensions look like this: ->statistics dimension: -> name: power -> script: card.power - -Specify a specific order and color of values, otherwise they are ordered alphabeticaly and groups with no cards are not shown: ->statistics dimension: -> name: color -> script: card.color -> group: white -> group: blue -> group: black -> group: red -> group: green -> colors: -> white: rgb(255,255,255) -> blue: rgb(0,0,255) -> black: rgb(0,0,0) -> red: rgb(255,0,0) -> green: rgb(0,255,0) +Data type: statistics dimension + +--Overview-- + +A dimension or axis for the statistics panel. + +One or more dimensions are combined in a graph, these combinations are called [[type:statistics category]]s. + +Statistics dimensions are automatically generated for all card fields in a [[type:game]] that don't set @show statistics@ to @false@. + +Categories are also automatically generated from dimensions. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''required'' Name of this dimension, used as an axis label and a label for automatically generated categories. +| @description@ [[type:string]] @""@ A description of the dimension, currently not used. +| @position hint@ [[type:string]] @0@ Hint for ordering dimensions. +| @icon@ [[type:filename]] Filename of an icon for this dimension. +| @script@ [[type:script]] ''required'' Script that generates a value for each card in the set. +| @numeric@ [[type:boolean]] @false@ Is the value always a number? +| @bin size@ [[type:double]] ''none'' For numeric dimensions: group numbers together into bins this large.
+ For example with @bin size: 5@, values @1@ and @3@ both get put under @"1-5"@. +| @show empty@ [[type:boolean]] @false@ Should cards with the value @""@ be included? +| @split list@ [[type:boolean]] @false@ Indicates the value is a list of the form @"item1, item2"@. The card is put under both items. +| @colors@ [[type:map]] of opaque [[type:color]]s Colors to use for specific values +| @groups@ [[type:list]] of [[type:string]]s Values to always show, and the order to show them in. + +--Example-- +Automatically generated statistics dimensions look like this: +>statistics dimension: +> name: power +> script: card.power + +Specify a specific order and color of values, otherwise they are ordered alphabeticaly and groups with no cards are not shown: +>statistics dimension: +> name: color +> script: card.color +> group: white +> group: blue +> group: black +> group: red +> group: green +> colors: +> white: rgb(255,255,255) +> blue: rgb(0,0,255) +> black: rgb(0,0,0) +> red: rgb(255,0,0) +> green: rgb(0,255,0) diff --git a/doc/type/string.txt b/doc/type/string.txt index 52bce929..dd238539 100644 --- a/doc/type/string.txt +++ b/doc/type/string.txt @@ -1,41 +1,41 @@ -Primitive type: character string - -A string is just a piece of text. - ---File syntax-- -In files, strings are written just as their value: -> string: this is some string -The whitespace at the beginning is removed by the program. -Multiline strings are written on a new line, indented by a TAB: -> string: -> This is a very long string -> It contains a line break. - ---Script syntax-- -In scripts, strings are written between double quotes, @"this is a string"@. -The backslash character is used to escape values: -! Code Represents -| @\"@ A " character -| @\{@ A { character -| @\n@ A newline character (line break) -| @\\@ A backslash -| @\<@ An escaped < for [[type:tagged string]]s. - -Sections between curly braces are interpreted as script code, that is concatentated with the string, for example -> "ab{1 + 1}c" == "ab2c" -This can be nested arbitrarily. - -The @+@ operator concatenates strings. Numbers and most other values are automatically converted to strings when needed. This conversion can be forced with the [[fun:to_string]] function. - -Using the @[]@ or @.@ operator characters in a string can be selected. 0 is the first character: -> "xyz"[0] == "x" -> "xyz".0 == "x" # same thing -> "xyz".1 == "y" -> "xyz".2 == "z" -It is an error to select characters outside the string -> "xyz".10 # error - ---See also-- -| [[type:tagged string]] A string containg tags. -| [[fun:to_string]] Convert any value to a [[type:string]] - +Primitive type: character string + +A string is just a piece of text. + +--File syntax-- +In files, strings are written just as their value: +> string: this is some string +The whitespace at the beginning is removed by the program. +Multiline strings are written on a new line, indented by a TAB: +> string: +> This is a very long string +> It contains a line break. + +--Script syntax-- +In scripts, strings are written between double quotes, @"this is a string"@. +The backslash character is used to escape values: +! Code Represents +| @\"@ A " character +| @\{@ A { character +| @\n@ A newline character (line break) +| @\\@ A backslash +| @\<@ An escaped < for [[type:tagged string]]s. + +Sections between curly braces are interpreted as script code, that is concatentated with the string, for example +> "ab{1 + 1}c" == "ab2c" +This can be nested arbitrarily. + +The @+@ operator concatenates strings. Numbers and most other values are automatically converted to strings when needed. This conversion can be forced with the [[fun:to_string]] function. + +Using the @[]@ or @.@ operator characters in a string can be selected. 0 is the first character: +> "xyz"[0] == "x" +> "xyz".0 == "x" # same thing +> "xyz".1 == "y" +> "xyz".2 == "z" +It is an error to select characters outside the string +> "xyz".10 # error + +--See also-- +| [[type:tagged string]] A string containg tags. +| [[fun:to_string]] Convert any value to a [[type:string]] + diff --git a/doc/type/style.txt b/doc/type/style.txt index a622ba94..57b6662b 100644 --- a/doc/type/style.txt +++ b/doc/type/style.txt @@ -1,167 +1,167 @@ -Data type: style - ---Overview-- - -A style specifies how a [[type:field]] should look, -things like position, size, fonts, colors, etc. - -Styles are part of the [[file:style triangle]]: -| Description Looks Data -| [[type:Game]] [[type:Stylesheet]] [[type:Set]] -| [[type:Field]] '''Style''' [[type:Value]] - ---Positioning-- - - -A style specifies the position of a box for the content. -To specify the horizontal location ''two'' of @left@, @width@ and @right@ must be specified. - -For example: -> left: 10 -> width: 20 -Implies that @right@ is 30 pixels. - -Similarly: -> left: 10 -> right: 30 -Implies the @width@ is 20. - -The same holds for the vertical location and size; @top@, @height@ and @bottom@. - ---Rotation-- -Rotating a box can be done with the @angle@ property. -The angle gives a counter clockwise rotation in degrees of the box. -The box is rotated such that the corner for which the position is specified is at the correct position after rotating. - -Here are some examples: - -| - >red box: - > width: 30 - > height: 25 - > left: 10 - > top: 20 - > angle: 30 - - >green box: - > width: 25 - > height: 30 - > left: 10 - > top: 80 - > angle: 90 - - >blue box: - > width: 30 - > height: 25 - > right: 90 - > bottom: 30 - > angle: 30 - - >yellow box: - > width: 20 - > height: 35 - > right: 60 - > bottom: 60 - > angle: 180 - - ---Properties-- -! Property Type Default Description -| @z index@ [[type:int]] @0@ Stacking of this box, fields with a higher @z index@ are placed on top of those with a lower index. -| @tab index@ [[type:int]] @0@ Index for moving through the fields with the tab key, fields with a lower tab index come first. Otherwise the order is from top to bottom and then left to right. -| @left@ [[type:scriptable]] [[type:double]] ''Required'' Distance between left edge of the box and the left of the card in pixels. -| @width@ [[type:scriptable]] [[type:double]] ''Required'' Width of the box in pixels. -| @right@ [[type:scriptable]] [[type:double]] ''Required'' Distance between right edge of the box and the ''left'' of the card in pixels. -| @top@ [[type:scriptable]] [[type:double]] ''Required'' Distance between top edge of the box and the top of the card in pixels. -| @height@ [[type:scriptable]] [[type:double]] ''Required'' Height of the box in pixels. -| @bottom@ [[type:scriptable]] [[type:double]] ''Required'' Distance between bottom edge of the box and the ''top'' of the card in pixels. -| @angle@ [[type:scriptable]] [[type:int]] @0@ Rotation of this box, in degrees counter clockwise. -| @visible@ [[type:scriptable]] [[type:boolean]] @true@ Is this field visible at all? -| @mask@ [[type:image|scriptable image]] ''none'' A mask to apply to the box, black areas in the mask become transparent, similar to [[fun:set_mask]]. - -The rest of the properties depend on the type of [[type:field]] this style is for. -! Type Property Type Default Description -| @"text"@ @font@ [[type:font]] ''Required'' Font to render the text. -| ^^^ @symbol font@ [[type:symbol font]] Font to render symbols in the text (optional). -| ^^^ @always symbol@ [[type:boolean]] @false@ Should all text be rendered with symbols?
- Text that is not supported by the symbol font is still rendered as normal text. -| ^^^ @allow formating@ [[type:boolean]] @true@ Is custom formating (bold, italic) allowed? -| ^^^ @alignment@ [[type:scriptable]] [[type:alignment]] @top left@ Alignment of the text. -| ^^^ @direction@ [[type:direction]] @"left to right"@ Direction in which the text flows. If set to @"vertical"@ it is as if a line break is inserted after each character. -| ^^^ @padding left@ [[type:scriptable]] [[type:double]] @0@ Padding between the text and the border of the box, in pixels. -| ^^^ @padding right@ ^^^ ^^^ ^^^ -| ^^^ @padding top@ ^^^ ^^^ ^^^ -| ^^^ @padding bottom@ ^^^ ^^^ ^^^ -| ^^^ @padding left min@ [[type:scriptable]] [[type:double]] ∞ Minimal padding around the field.
When the text is scaled down the padding is scaled as well, but it becomes no smaller than this. -| ^^^ @padding right min@ ^^^ ^^^ ^^^ -| ^^^ @padding top min@ ^^^ ^^^ ^^^ -| ^^^ @padding bottom min@ ^^^ ^^^ ^^^ -| ^^^ @line height soft@ [[type:scriptable]] [[type:double]] @1@ Multiplier for the line height of 'soft' line breaks. These are breaks caused by wrapping around lines that are too long.
- A line height of @0@ means all lines are in the same position, @1@ is normal behaviour, @2@ skips a line, etc. -| ^^^ @line height hard@ [[type:scriptable]] [[type:double]] @1@ Multiplier for the line height of 'hard' line breaks. These are breaks caused by the enter key. -| ^^^ @line height line@ [[type:scriptable]] [[type:double]] @1@ Multiplier for the line height of 'soft' line breaks. These are breaks caused by @"\n"@ tags. -| ^^^ @line height soft max@ [[type:scriptable]] [[type:double]] ''disabled'' When there is still vertical room in the text box, increase the line heights to at most these values to spread the text more evenly. -| ^^^ @line height hard max@ ^^^ ^^^ ^^^ -| ^^^ @line height line max@ ^^^ ^^^ ^^^ -| ^^^ @paragraph height@ [[type:double]] ''flexible'' The height of paragraphs. If specified, each paragraph is given this much space, and aligned inside that space as specified by @alignment@.
- A paragraph break is any line break that is not soft (i.e. caused by word wrap or a @@ break). -| ^^^ @mask@ [[type:image|scriptable image]] ''none'' A mask that indicates where in the box text can be placed.
- Text is never put in black areas of the box:
-
- The same mask image is also used to determine the size and shape of the box. - To include a certain pixel in the size/shape but not allow text to be placed there, it can be made dark gray (a value less than 128). -| ^^^ @content width@ [[type:double]] ''automatic'' When read from a script, gives the width of the current content in this box. -| ^^^ @content height@ [[type:double]] ''automatic'' When read from a script, gives the height of the current content in this box. -| ^^^ @content lines@ [[type:int]] ''automatic'' When read from a script, gives the number of lines of the current content in this box. - -! <<< <<< <<< <<< -| @"choice"@,
@"multiple choice"@,
@"boolean"@ - @popup style@ @"drop down"@ or @"in place"@ @"drop down"@ Where to place the drop down box for editing the value.
- @"drop down"@ places the box below the field, similar to normal combo boxes.
- @"in place"@ places the box at the mouse coordinates. -| ^^^ @render style@ [[type:choice render style]] @"text"@ How should the field be rendered? -| ^^^ @combine@ [[type:combine]] @"normal"@ How to combine the image with the background? Can be overridden using the [[fun:set_combine]] function. -| ^^^ @alignment@ [[type:alignment]] @"stretch"@ Alignment of text and images in the box. -| ^^^ @font@ [[type:font]] Font to use for rendering text (depending on @render style@) -| ^^^ @image@ [[type:image|scriptable image]] Image to show (depending on @render style@).
- The script will be called with @input@ set to the value to determine an image for. -| ^^^ @choice images@ [[type:map]] of [[type:image]]s An alternative way to specify what image to show.
- For each [[type:choice]] a separate image is specified. -| ^^^ @content width@ [[type:double]] ''automatic'' When read from a script, gives the width of the current choice image in this box.
- This is only useful when the alignment is changed, otherwise it is always equal the box size itself. -| ^^^ @content height@ [[type:double]] ''automatic'' When read from a script, gives the height of the current choice image in this box. -| @"multiple choice"@ - @direction@ [[type:scriptable]] [[type:direction]] @"left to right"@ Direction the items are laid out in, only when @render style@ is @list@. -| ^^^ @spacing@ [[type:scriptable]] [[type:double]] @0@ Spacing between the items. - -! <<< <<< <<< <<< -| @"package choice"@ -| ^^^ @font@ [[type:font]] Font to use for rendering text. - -! <<< <<< <<< <<< -| @"color"@ @radius@ [[type:double]] @0@ Radius of rounded corners for the box in pixels. -| ^^^ @left width@ [[type:double]] ∞ Draw only this many pixels from the side, creating a box with a hole in it, or a card border. -| ^^^ @right width@ ^^^ ^^^ ^^^ -| ^^^ @top width@ ^^^ ^^^ ^^^ -| ^^^ @bottom width@ ^^^ ^^^ ^^^ -| ^^^ @combine@ [[type:combine]] @"normal"@ How to combine the color with the background? Only applies when a mask is used. - -! <<< <<< <<< <<< -| @"image"@ @default@ [[type:image|scriptable image]] ''none'' A default image to use when the card has none. - -! <<< <<< <<< <<< -| @"symbol"@ @variations@ [[type:list]] of [[type:symbol variation]]s Available variations of the symbol, a variation describes color and border size. -| ^^^ @min aspect ratio@ [[type:double]] @1@ Bounds for the aspect ratio, @width/height@ symbols can take. This can be used to make non-square symbols. -| ^^^ @max aspect ratio@ [[type:double]] @1@ ^^^ - -! <<< <<< <<< <<< -| @"info"@ @font@ [[type:font]] ''Required'' Font to render the text. -| ^^^ @alignment@ [[type:scriptable]] [[type:alignment]] @top left@ Alignment of the text. -| ^^^ @padding left@ [[type:double]] @0@ Padding between the text and the border of the box, in pixels. -| ^^^ @padding right@ ^^^ ^^^ ^^^ -| ^^^ @padding top@ ^^^ ^^^ ^^^ -| ^^^ @padding bottom@ ^^^ ^^^ ^^^ -| ^^^ @background color@ opaque [[type:color]] @rgb(255,255,255)@ Background color for the box, can be used to make it stand out. - ---Example-- - +Data type: style + +--Overview-- + +A style specifies how a [[type:field]] should look, +things like position, size, fonts, colors, etc. + +Styles are part of the [[file:style triangle]]: +| Description Looks Data +| [[type:Game]] [[type:Stylesheet]] [[type:Set]] +| [[type:Field]] '''Style''' [[type:Value]] + +--Positioning-- + + +A style specifies the position of a box for the content. +To specify the horizontal location ''two'' of @left@, @width@ and @right@ must be specified. + +For example: +> left: 10 +> width: 20 +Implies that @right@ is 30 pixels. + +Similarly: +> left: 10 +> right: 30 +Implies the @width@ is 20. + +The same holds for the vertical location and size; @top@, @height@ and @bottom@. + +--Rotation-- +Rotating a box can be done with the @angle@ property. +The angle gives a counter clockwise rotation in degrees of the box. +The box is rotated such that the corner for which the position is specified is at the correct position after rotating. + +Here are some examples: + +| + >red box: + > width: 30 + > height: 25 + > left: 10 + > top: 20 + > angle: 30 + + >green box: + > width: 25 + > height: 30 + > left: 10 + > top: 80 + > angle: 90 + + >blue box: + > width: 30 + > height: 25 + > right: 90 + > bottom: 30 + > angle: 30 + + >yellow box: + > width: 20 + > height: 35 + > right: 60 + > bottom: 60 + > angle: 180 + + +--Properties-- +! Property Type Default Description +| @z index@ [[type:int]] @0@ Stacking of this box, fields with a higher @z index@ are placed on top of those with a lower index. +| @tab index@ [[type:int]] @0@ Index for moving through the fields with the tab key, fields with a lower tab index come first. Otherwise the order is from top to bottom and then left to right. +| @left@ [[type:scriptable]] [[type:double]] ''Required'' Distance between left edge of the box and the left of the card in pixels. +| @width@ [[type:scriptable]] [[type:double]] ''Required'' Width of the box in pixels. +| @right@ [[type:scriptable]] [[type:double]] ''Required'' Distance between right edge of the box and the ''left'' of the card in pixels. +| @top@ [[type:scriptable]] [[type:double]] ''Required'' Distance between top edge of the box and the top of the card in pixels. +| @height@ [[type:scriptable]] [[type:double]] ''Required'' Height of the box in pixels. +| @bottom@ [[type:scriptable]] [[type:double]] ''Required'' Distance between bottom edge of the box and the ''top'' of the card in pixels. +| @angle@ [[type:scriptable]] [[type:int]] @0@ Rotation of this box, in degrees counter clockwise. +| @visible@ [[type:scriptable]] [[type:boolean]] @true@ Is this field visible at all? +| @mask@ [[type:image|scriptable image]] ''none'' A mask to apply to the box, black areas in the mask become transparent, similar to [[fun:set_mask]]. + +The rest of the properties depend on the type of [[type:field]] this style is for. +! Type Property Type Default Description +| @"text"@ @font@ [[type:font]] ''Required'' Font to render the text. +| ^^^ @symbol font@ [[type:symbol font]] Font to render symbols in the text (optional). +| ^^^ @always symbol@ [[type:boolean]] @false@ Should all text be rendered with symbols?
+ Text that is not supported by the symbol font is still rendered as normal text. +| ^^^ @allow formating@ [[type:boolean]] @true@ Is custom formating (bold, italic) allowed? +| ^^^ @alignment@ [[type:scriptable]] [[type:alignment]] @top left@ Alignment of the text. +| ^^^ @direction@ [[type:direction]] @"left to right"@ Direction in which the text flows. If set to @"vertical"@ it is as if a line break is inserted after each character. +| ^^^ @padding left@ [[type:scriptable]] [[type:double]] @0@ Padding between the text and the border of the box, in pixels. +| ^^^ @padding right@ ^^^ ^^^ ^^^ +| ^^^ @padding top@ ^^^ ^^^ ^^^ +| ^^^ @padding bottom@ ^^^ ^^^ ^^^ +| ^^^ @padding left min@ [[type:scriptable]] [[type:double]] ∞ Minimal padding around the field.
When the text is scaled down the padding is scaled as well, but it becomes no smaller than this. +| ^^^ @padding right min@ ^^^ ^^^ ^^^ +| ^^^ @padding top min@ ^^^ ^^^ ^^^ +| ^^^ @padding bottom min@ ^^^ ^^^ ^^^ +| ^^^ @line height soft@ [[type:scriptable]] [[type:double]] @1@ Multiplier for the line height of 'soft' line breaks. These are breaks caused by wrapping around lines that are too long.
+ A line height of @0@ means all lines are in the same position, @1@ is normal behaviour, @2@ skips a line, etc. +| ^^^ @line height hard@ [[type:scriptable]] [[type:double]] @1@ Multiplier for the line height of 'hard' line breaks. These are breaks caused by the enter key. +| ^^^ @line height line@ [[type:scriptable]] [[type:double]] @1@ Multiplier for the line height of 'soft' line breaks. These are breaks caused by @"\n"@ tags. +| ^^^ @line height soft max@ [[type:scriptable]] [[type:double]] ''disabled'' When there is still vertical room in the text box, increase the line heights to at most these values to spread the text more evenly. +| ^^^ @line height hard max@ ^^^ ^^^ ^^^ +| ^^^ @line height line max@ ^^^ ^^^ ^^^ +| ^^^ @paragraph height@ [[type:double]] ''flexible'' The height of paragraphs. If specified, each paragraph is given this much space, and aligned inside that space as specified by @alignment@.
+ A paragraph break is any line break that is not soft (i.e. caused by word wrap or a @@ break). +| ^^^ @mask@ [[type:image|scriptable image]] ''none'' A mask that indicates where in the box text can be placed.
+ Text is never put in black areas of the box:
+
+ The same mask image is also used to determine the size and shape of the box. + To include a certain pixel in the size/shape but not allow text to be placed there, it can be made dark gray (a value less than 128). +| ^^^ @content width@ [[type:double]] ''automatic'' When read from a script, gives the width of the current content in this box. +| ^^^ @content height@ [[type:double]] ''automatic'' When read from a script, gives the height of the current content in this box. +| ^^^ @content lines@ [[type:int]] ''automatic'' When read from a script, gives the number of lines of the current content in this box. + +! <<< <<< <<< <<< +| @"choice"@,
@"multiple choice"@,
@"boolean"@ + @popup style@ @"drop down"@ or @"in place"@ @"drop down"@ Where to place the drop down box for editing the value.
+ @"drop down"@ places the box below the field, similar to normal combo boxes.
+ @"in place"@ places the box at the mouse coordinates. +| ^^^ @render style@ [[type:choice render style]] @"text"@ How should the field be rendered? +| ^^^ @combine@ [[type:combine]] @"normal"@ How to combine the image with the background? Can be overridden using the [[fun:set_combine]] function. +| ^^^ @alignment@ [[type:alignment]] @"stretch"@ Alignment of text and images in the box. +| ^^^ @font@ [[type:font]] Font to use for rendering text (depending on @render style@) +| ^^^ @image@ [[type:image|scriptable image]] Image to show (depending on @render style@).
+ The script will be called with @input@ set to the value to determine an image for. +| ^^^ @choice images@ [[type:map]] of [[type:image]]s An alternative way to specify what image to show.
+ For each [[type:choice]] a separate image is specified. +| ^^^ @content width@ [[type:double]] ''automatic'' When read from a script, gives the width of the current choice image in this box.
+ This is only useful when the alignment is changed, otherwise it is always equal the box size itself. +| ^^^ @content height@ [[type:double]] ''automatic'' When read from a script, gives the height of the current choice image in this box. +| @"multiple choice"@ + @direction@ [[type:scriptable]] [[type:direction]] @"left to right"@ Direction the items are laid out in, only when @render style@ is @list@. +| ^^^ @spacing@ [[type:scriptable]] [[type:double]] @0@ Spacing between the items. + +! <<< <<< <<< <<< +| @"package choice"@ +| ^^^ @font@ [[type:font]] Font to use for rendering text. + +! <<< <<< <<< <<< +| @"color"@ @radius@ [[type:double]] @0@ Radius of rounded corners for the box in pixels. +| ^^^ @left width@ [[type:double]] ∞ Draw only this many pixels from the side, creating a box with a hole in it, or a card border. +| ^^^ @right width@ ^^^ ^^^ ^^^ +| ^^^ @top width@ ^^^ ^^^ ^^^ +| ^^^ @bottom width@ ^^^ ^^^ ^^^ +| ^^^ @combine@ [[type:combine]] @"normal"@ How to combine the color with the background? Only applies when a mask is used. + +! <<< <<< <<< <<< +| @"image"@ @default@ [[type:image|scriptable image]] ''none'' A default image to use when the card has none. + +! <<< <<< <<< <<< +| @"symbol"@ @variations@ [[type:list]] of [[type:symbol variation]]s Available variations of the symbol, a variation describes color and border size. +| ^^^ @min aspect ratio@ [[type:double]] @1@ Bounds for the aspect ratio, @width/height@ symbols can take. This can be used to make non-square symbols. +| ^^^ @max aspect ratio@ [[type:double]] @1@ ^^^ + +! <<< <<< <<< <<< +| @"info"@ @font@ [[type:font]] ''Required'' Font to render the text. +| ^^^ @alignment@ [[type:scriptable]] [[type:alignment]] @top left@ Alignment of the text. +| ^^^ @padding left@ [[type:double]] @0@ Padding between the text and the border of the box, in pixels. +| ^^^ @padding right@ ^^^ ^^^ ^^^ +| ^^^ @padding top@ ^^^ ^^^ ^^^ +| ^^^ @padding bottom@ ^^^ ^^^ ^^^ +| ^^^ @background color@ opaque [[type:color]] @rgb(255,255,255)@ Background color for the box, can be used to make it stand out. + +--Example-- + diff --git a/doc/type/stylesheet.txt b/doc/type/stylesheet.txt index 07c3f614..ed0a6b96 100644 --- a/doc/type/stylesheet.txt +++ b/doc/type/stylesheet.txt @@ -1,42 +1,42 @@ -File type: Stylesheet - ---Overview-- - -Stylesheets are part of the [[file:style triangle]]: -| Description Looks Data -| [[type:Game]] '''Stylesheet''' [[type:Set]] -| [[type:Field]] [[type:Style]] [[type:Value]] - -Stylesheets provide the ''look and feel'' of cards. - ---Package format-- -A stylesheet is described in a [[file:package]] with the .mse-style file extension, -such a package contains a data file called style. - ---Properties-- -! Property Type Default Description -| '''Common to all packages''' <<< <<< <<< -| @mse version@ [[type:version]] ''required'' Version of MSE this stylesheet is made for. -| @short name@ [[type:string]] file name A short name of this stylesheet, for the 'new set' and style panel lists. -| @full name@ [[type:string]] file name A longer name of this stylesheet. -| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this stylesheet, for the 'new set' and style panel lists. -| @position hint@ [[type:int]] ∞ Where to place this item in the list? Lower numbers come first. -| @version@ [[type:version]] @0.0.0@ Version number of this package. -| @depends on@ [[type:list]] of [[type:dependency]]s - Packages this package depends on. - -| '''Specific to stylesheets''' <<< <<< <<< -| @game@ Name of a [[type:game]] ''required'' Game this stylesheet is made for -| @card width@ [[type:double]] 100 Width of cards in pixels -| @card height@ [[type:double]] 100 Height of cards in pixels -| @card dpi@ [[type:double]] 96 Resolution of cards in dots-per-inch -| @card background@ [[type:color]] white Background color of cards -| @init script@ [[type:script]] @;@ Script to run when this stylesheet is loaded, after the game's init script. -| @styling fields@ [[type:list]] of [[type:field]]s Fields for styling options, shown on the 'style' panel. -| @styling style@ [[type:indexmap]] of [[type:style]]s Styles for the styling fields. -| @set info style@ [[type:indexmap]] of [[type:style]]s game.default_set_style Styling for the 'set info' panel -| @card style@ [[type:indexmap]] of [[type:style]]s Styles for the card fields defined in the game -| @extra card fields@ [[type:list]] of [[type:field]]s Additional fields to add to each card.
- These fields are intended for things like lines and boxes, whose value is determined automatically. -| @extra card style@ [[type:indexmap] of [[type:style]]s Styling for the extra card fields - +File type: Stylesheet + +--Overview-- + +Stylesheets are part of the [[file:style triangle]]: +| Description Looks Data +| [[type:Game]] '''Stylesheet''' [[type:Set]] +| [[type:Field]] [[type:Style]] [[type:Value]] + +Stylesheets provide the ''look and feel'' of cards. + +--Package format-- +A stylesheet is described in a [[file:package]] with the .mse-style file extension, +such a package contains a data file called style. + +--Properties-- +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this stylesheet is made for. +| @short name@ [[type:string]] file name A short name of this stylesheet, for the 'new set' and style panel lists. +| @full name@ [[type:string]] file name A longer name of this stylesheet. +| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this stylesheet, for the 'new set' and style panel lists. +| @position hint@ [[type:int]] ∞ Where to place this item in the list? Lower numbers come first. +| @version@ [[type:version]] @0.0.0@ Version number of this package. +| @depends on@ [[type:list]] of [[type:dependency]]s + Packages this package depends on. + +| '''Specific to stylesheets''' <<< <<< <<< +| @game@ Name of a [[type:game]] ''required'' Game this stylesheet is made for +| @card width@ [[type:double]] 100 Width of cards in pixels +| @card height@ [[type:double]] 100 Height of cards in pixels +| @card dpi@ [[type:double]] 96 Resolution of cards in dots-per-inch +| @card background@ [[type:color]] white Background color of cards +| @init script@ [[type:script]] @;@ Script to run when this stylesheet is loaded, after the game's init script. +| @styling fields@ [[type:list]] of [[type:field]]s Fields for styling options, shown on the 'style' panel. +| @styling style@ [[type:indexmap]] of [[type:style]]s Styles for the styling fields. +| @set info style@ [[type:indexmap]] of [[type:style]]s game.default_set_style Styling for the 'set info' panel +| @card style@ [[type:indexmap]] of [[type:style]]s Styles for the card fields defined in the game +| @extra card fields@ [[type:list]] of [[type:field]]s Additional fields to add to each card.
+ These fields are intended for things like lines and boxes, whose value is determined automatically. +| @extra card style@ [[type:indexmap] of [[type:style]]s Styling for the extra card fields + diff --git a/doc/type/symbol.txt b/doc/type/symbol.txt index 34db1acd..702efd93 100644 --- a/doc/type/symbol.txt +++ b/doc/type/symbol.txt @@ -1,20 +1,20 @@ -File type: Symbol - ---Overview-- - -A symbol file contains a symbol created with the symbol editor. - -Symbols are not stored in packages, the data file is directly written to a @".mse-symbol"@ file. - ---Coordinates-- - -Various parts of a symbol use [[type:vector2d|coordinates]]. -These are pairs of numbers in the range @0@ to @1@. @(0,0)@ is the top-left of the symbol, @(1,1)@ the bottom-right. - ---Properties-- -! Property Type Default Description -| @mse version@ [[type:version]] ''required'' Version of MSE this symbol is made with. -| @parts@ [[type:list]] of [[type:symbol part]]s The parts in this symbol. - ---Example-- -Look at a file made with the program. +File type: Symbol + +--Overview-- + +A symbol file contains a symbol created with the symbol editor. + +Symbols are not stored in packages, the data file is directly written to a @".mse-symbol"@ file. + +--Coordinates-- + +Various parts of a symbol use [[type:vector2d|coordinates]]. +These are pairs of numbers in the range @0@ to @1@. @(0,0)@ is the top-left of the symbol, @(1,1)@ the bottom-right. + +--Properties-- +! Property Type Default Description +| @mse version@ [[type:version]] ''required'' Version of MSE this symbol is made with. +| @parts@ [[type:list]] of [[type:symbol part]]s The parts in this symbol. + +--Example-- +Look at a file made with the program. diff --git a/doc/type/symbol_combine.txt b/doc/type/symbol_combine.txt index 8aa2b972..081957e6 100644 --- a/doc/type/symbol_combine.txt +++ b/doc/type/symbol_combine.txt @@ -1,19 +1,19 @@ -Enumeration: symbol combine - -Specifies how symbol shapes are combined with those below it - ---Script syntax-- -In scripts, symbol combine modes are passed around as a string. - ---Possible values-- -The value is one of the following options: -! Value Description -| @overlap@ Place this shape on top of those below it.
Further combine options only apply to this shape. -| @merge@ Marge this shape with the one below it, they are considered a single shape for further combining. -| @subtract@ Subtract this shape from the one below it. -| @intersection@ Take the intersection of this shape and the one below it, only areas that are in both shapes remain. -| @difference@ Take the difference of this shape and the one below it, only areas that are in exactly one of the shapes remain. -| @border@ Use this shape as additional border for the shape below it. - ---Examples-- -> combine: overlap +Enumeration: symbol combine + +Specifies how symbol shapes are combined with those below it + +--Script syntax-- +In scripts, symbol combine modes are passed around as a string. + +--Possible values-- +The value is one of the following options: +! Value Description +| @overlap@ Place this shape on top of those below it.
Further combine options only apply to this shape. +| @merge@ Marge this shape with the one below it, they are considered a single shape for further combining. +| @subtract@ Subtract this shape from the one below it. +| @intersection@ Take the intersection of this shape and the one below it, only areas that are in both shapes remain. +| @difference@ Take the difference of this shape and the one below it, only areas that are in exactly one of the shapes remain. +| @border@ Use this shape as additional border for the shape below it. + +--Examples-- +> combine: overlap diff --git a/doc/type/symbol_font.txt b/doc/type/symbol_font.txt index c4b44396..9944ab61 100644 --- a/doc/type/symbol_font.txt +++ b/doc/type/symbol_font.txt @@ -1,55 +1,55 @@ -File type: Symbol font - ---Overview-- - -A symbol font is a font for drawing with images. -Each [[type:symbol font symbol|symbol-font-symbol]] in the font is an image. - -A symbol font is referenced in [[type:stylesheet]]s using a [[type:symbol font reference]]. - ---Splitting-- - -A piece of text drawn with the symbol font is split into separate symbols. -The list of symbols in the font is scanned from top to bottom to find matches. - -If the text is for instance "W/GR" and "W/G" should be rendered as a single symbol, then it should appear before the symbol "W". -Otherwise the "W" is seen as a symbol and the program continues with rendering "/GR". - ---Font size-- - -A symbol font is drawn using a specific point size, similar to normal fonts. -Usually the images that make up the font are given in a very high resolution, for example 200x200. -This resolution could correspond to a point size of for instance 150pt. - -When the symbol is drawn at for instance 12pt the image well then be scaled down to @200/150*12 == 16@ pixels. - -Sizes like margin, padding and font size are given in 'pixels per point'. If for instance -> text margin left: 0.1 -is specified, and the symbol is rendered at 12pt, the margin will be @12*0.1 == 1.2@ pixels. - ---Package format-- - -A symbol font is described in a [[file:package]] with the .mse-symbol-font file extension. -Such a package contains a [[file:format|data file]] called symbol-font that has the following properties. - ---Properties-- -! Property Type Default Description -| '''Common to all packages''' <<< <<< <<< -| @mse version@ [[type:version]] ''required'' Version of MSE this symbol font is made for. -| @short name@ [[type:string]] file name A short name of this symbol font, currently not used by the program. -| @full name@ [[type:string]] file name A longer name of this symbol font, currently not used by the program. -| @icon@ [[type:filename]] ''none'' Filename of an icon, currently not used by the program. -| @version@ [[type:version]] @0.0.0@ Version number of this package. -| @depends on@ [[type:list]] of [[type:dependency]]s - Packages this package depends on. - -| '''Specific to symbol fonts''' <<< <<< <<< -| @image font size@ [[type:double]] @12@ To what point size do the images correspond? -| @horizontal space@ [[type:double]] @0@ Horizontal spacing between symbols, in pixels. -| @vertical space@ [[type:double]] @0@ Vertical spacing between symbols, in pixels. -| @symbols@ [[type:list]] of [[type:symbol font symbol]]s Symbols that make up this font. -| @scale text@ [[type:boolean]] @false@ Should text be scaled down to fit in a symbol? -| @insert symbol menu@ [[type:insert symbol menu|"insert symbol" menu]] ''none'' A description of the menu to insert a symbol into the text. - ---Examples-- -See for instance the @"magic-mana-small.mse-symbol-font"@ package in the MSE distribution. +File type: Symbol font + +--Overview-- + +A symbol font is a font for drawing with images. +Each [[type:symbol font symbol|symbol-font-symbol]] in the font is an image. + +A symbol font is referenced in [[type:stylesheet]]s using a [[type:symbol font reference]]. + +--Splitting-- + +A piece of text drawn with the symbol font is split into separate symbols. +The list of symbols in the font is scanned from top to bottom to find matches. + +If the text is for instance "W/GR" and "W/G" should be rendered as a single symbol, then it should appear before the symbol "W". +Otherwise the "W" is seen as a symbol and the program continues with rendering "/GR". + +--Font size-- + +A symbol font is drawn using a specific point size, similar to normal fonts. +Usually the images that make up the font are given in a very high resolution, for example 200x200. +This resolution could correspond to a point size of for instance 150pt. + +When the symbol is drawn at for instance 12pt the image well then be scaled down to @200/150*12 == 16@ pixels. + +Sizes like margin, padding and font size are given in 'pixels per point'. If for instance +> text margin left: 0.1 +is specified, and the symbol is rendered at 12pt, the margin will be @12*0.1 == 1.2@ pixels. + +--Package format-- + +A symbol font is described in a [[file:package]] with the .mse-symbol-font file extension. +Such a package contains a [[file:format|data file]] called symbol-font that has the following properties. + +--Properties-- +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this symbol font is made for. +| @short name@ [[type:string]] file name A short name of this symbol font, currently not used by the program. +| @full name@ [[type:string]] file name A longer name of this symbol font, currently not used by the program. +| @icon@ [[type:filename]] ''none'' Filename of an icon, currently not used by the program. +| @version@ [[type:version]] @0.0.0@ Version number of this package. +| @depends on@ [[type:list]] of [[type:dependency]]s + Packages this package depends on. + +| '''Specific to symbol fonts''' <<< <<< <<< +| @image font size@ [[type:double]] @12@ To what point size do the images correspond? +| @horizontal space@ [[type:double]] @0@ Horizontal spacing between symbols, in pixels. +| @vertical space@ [[type:double]] @0@ Vertical spacing between symbols, in pixels. +| @symbols@ [[type:list]] of [[type:symbol font symbol]]s Symbols that make up this font. +| @scale text@ [[type:boolean]] @false@ Should text be scaled down to fit in a symbol? +| @insert symbol menu@ [[type:insert symbol menu|"insert symbol" menu]] ''none'' A description of the menu to insert a symbol into the text. + +--Examples-- +See for instance the @"magic-mana-small.mse-symbol-font"@ package in the MSE distribution. diff --git a/doc/type/symbol_font_reference.txt b/doc/type/symbol_font_reference.txt index f9f4efd7..a410ce96 100644 --- a/doc/type/symbol_font_reference.txt +++ b/doc/type/symbol_font_reference.txt @@ -1,26 +1,26 @@ -Data type: symbol font reference - ---Overview-- - -A reference to a [[type:symbol font]]. - -In [[type:stylesheet]]s the symbol fonts are not included inline, instead they are referenced by their package name. - ---Properties-- -! Property Type Default Description -| @name@ [[type:scriptable]] Name of a [[type:symbol font]] - ''required'' Name of the symbol font package to use (without the extension). -| @size@ [[type:scriptable]] [[type:double]] 12 Size in points to render the symbols with. -| @scale down to@ [[type:double]] 1 Minimum size in points to scale the size down to. -| @alignment@ [[type:scriptable]] [[type:alignment]] @"middle center"@ Alignment of symbols in a line of text. - ---Example-- ->symbol font: -> name: magic-mana-small -> size: 10 -> alignment: top left -The name can be scripted: ->symbol font: -> name: { if set.use_larga_mana_symbols then "magic-mana-large" else "magic-mana-small" } -> size: 10 -> alignment: top left +Data type: symbol font reference + +--Overview-- + +A reference to a [[type:symbol font]]. + +In [[type:stylesheet]]s the symbol fonts are not included inline, instead they are referenced by their package name. + +--Properties-- +! Property Type Default Description +| @name@ [[type:scriptable]] Name of a [[type:symbol font]] + ''required'' Name of the symbol font package to use (without the extension). +| @size@ [[type:scriptable]] [[type:double]] 12 Size in points to render the symbols with. +| @scale down to@ [[type:double]] 1 Minimum size in points to scale the size down to. +| @alignment@ [[type:scriptable]] [[type:alignment]] @"middle center"@ Alignment of symbols in a line of text. + +--Example-- +>symbol font: +> name: magic-mana-small +> size: 10 +> alignment: top left +The name can be scripted: +>symbol font: +> name: { if set.use_larga_mana_symbols then "magic-mana-large" else "magic-mana-small" } +> size: 10 +> alignment: top left diff --git a/doc/type/symbol_font_symbol.txt b/doc/type/symbol_font_symbol.txt index 275d58f3..8ee24639 100644 --- a/doc/type/symbol_font_symbol.txt +++ b/doc/type/symbol_font_symbol.txt @@ -1,41 +1,41 @@ -Data type: symbol font symbol - ---Overview-- - -A single symbol in a [[type:symbol font]]. - ---Properties-- -! Property Type Default Description -| @image font size@ [[type:double]] value from symbol font To what point size does the images correspond? -| @code@ [[type:string]] or [[type:regex]] ''required'' Text this symbol matches. -| @regex@ [[type:boolean]] @false@ Is the code a regular expression (as opposed to a string)? -| @image@ [[type:scriptable]] [[type:image]] ''required'' Image of this symbol. -| @enabled@ [[type:scriptable]] [[type:boolean]] @true@ Is this symbol actually used?
- This can be scripted to optionally disable certain symbols.
- If multiple symbols with the same code are given disabling the first switches to the second one. -| @draw text@ [[type:int]] @-1@ The index of the captured regex expression to draw as text, or -1 to not draw text.
For example with the code @"x([a-z])"@ and @draw text: 1@ the text of the symbol @"xb"@ will be @"b"@. -| @text font@ [[type:font]] Font to use for drawing text on symbols. The font size is in font points per text box font point. -| @text alignment@ [[type:alignment]] @"middle center"@ How should text be aligned on the symbol? -| @text margin left@ [[type:double]] @0@ Margin on the left of the text in pixels per point. -| @text margin right@ [[type:double]] @0@ Margin on the right of the text in pixels per point. -| @text margin top@ [[type:double]] @0@ Margin on the top of the text in pixels per point. -| @text margin bottom@ [[type:double]] @0@ Margin on the bottom of the text in pixels per point. - - ---Examples-- -A symbol with text: ->symbol: -> image: blank.png -> code: . -> regex: true -> text font: Arial - -Two symbols for the same code, which one is used depends on a function from the [[type:stylesheet]]. -It is recommended to only use functions in @enabled@, so each stylesheet can determine how the font should be used. ->symbol: -> code: T -> image: mana_t_old.png -> enabled: { use_old_tap_symbol() } ->symbol: -> code: T -> image: mana_t.png +Data type: symbol font symbol + +--Overview-- + +A single symbol in a [[type:symbol font]]. + +--Properties-- +! Property Type Default Description +| @image font size@ [[type:double]] value from symbol font To what point size does the images correspond? +| @code@ [[type:string]] or [[type:regex]] ''required'' Text this symbol matches. +| @regex@ [[type:boolean]] @false@ Is the code a regular expression (as opposed to a string)? +| @image@ [[type:scriptable]] [[type:image]] ''required'' Image of this symbol. +| @enabled@ [[type:scriptable]] [[type:boolean]] @true@ Is this symbol actually used?
+ This can be scripted to optionally disable certain symbols.
+ If multiple symbols with the same code are given disabling the first switches to the second one. +| @draw text@ [[type:int]] @-1@ The index of the captured regex expression to draw as text, or -1 to not draw text.
For example with the code @"x([a-z])"@ and @draw text: 1@ the text of the symbol @"xb"@ will be @"b"@. +| @text font@ [[type:font]] Font to use for drawing text on symbols. The font size is in font points per text box font point. +| @text alignment@ [[type:alignment]] @"middle center"@ How should text be aligned on the symbol? +| @text margin left@ [[type:double]] @0@ Margin on the left of the text in pixels per point. +| @text margin right@ [[type:double]] @0@ Margin on the right of the text in pixels per point. +| @text margin top@ [[type:double]] @0@ Margin on the top of the text in pixels per point. +| @text margin bottom@ [[type:double]] @0@ Margin on the bottom of the text in pixels per point. + + +--Examples-- +A symbol with text: +>symbol: +> image: blank.png +> code: . +> regex: true +> text font: Arial + +Two symbols for the same code, which one is used depends on a function from the [[type:stylesheet]]. +It is recommended to only use functions in @enabled@, so each stylesheet can determine how the font should be used. +>symbol: +> code: T +> image: mana_t_old.png +> enabled: { use_old_tap_symbol() } +>symbol: +> code: T +> image: mana_t.png diff --git a/doc/type/symbol_part.txt b/doc/type/symbol_part.txt index 9351b420..cf90d906 100644 --- a/doc/type/symbol_part.txt +++ b/doc/type/symbol_part.txt @@ -1,29 +1,29 @@ -Data type: symbol part - ---Overview-- - -A part of a symbol, corresponds to an item you see in the list on the left of the editor. - ---Properties-- -! Property Type Default Description -| @type@ One of: @"shape"@ What type of symbol part is this? - * @shape@ - * @group@ - * @symmetry@ -| @name@ [[type:string]] @""@ The name of this part, for the part list. - -The rest of the properties depends on the @type@. - -! Type Property Type Default Description -| @"shape"@ @combine@ [[type:symbol combine]] @"overlap"@ How to combine the shape with those below it? -| ^^^ @points@ [[type:list]] of [[type:control point]]s The points that form this shape -| @"symmetry"@ @kind@ @rotation@ or @reflection@ @"rotation"@ What kind of symmetry is this? -| ^^^ @copies@ [[type:int]] 2 How many times is the original copied (including the original itself)? -| ^^^ @center@ [[type:vector2d]] Coordinates of the center of symmetry. -| ^^^ @handle@ [[type:vector2d]] Direction perpendicular to the 'mirror' (this is a direction, so relative to the center). -| @"group"@ and @"symmetry"@ - @parts@ [[type:list]] of [[type:symbol part]]s Parts in this group. - - ---Example-- -Look at a symbol file made with the program. +Data type: symbol part + +--Overview-- + +A part of a symbol, corresponds to an item you see in the list on the left of the editor. + +--Properties-- +! Property Type Default Description +| @type@ One of: @"shape"@ What type of symbol part is this? + * @shape@ + * @group@ + * @symmetry@ +| @name@ [[type:string]] @""@ The name of this part, for the part list. + +The rest of the properties depends on the @type@. + +! Type Property Type Default Description +| @"shape"@ @combine@ [[type:symbol combine]] @"overlap"@ How to combine the shape with those below it? +| ^^^ @points@ [[type:list]] of [[type:control point]]s The points that form this shape +| @"symmetry"@ @kind@ @rotation@ or @reflection@ @"rotation"@ What kind of symmetry is this? +| ^^^ @copies@ [[type:int]] 2 How many times is the original copied (including the original itself)? +| ^^^ @center@ [[type:vector2d]] Coordinates of the center of symmetry. +| ^^^ @handle@ [[type:vector2d]] Direction perpendicular to the 'mirror' (this is a direction, so relative to the center). +| @"group"@ and @"symmetry"@ + @parts@ [[type:list]] of [[type:symbol part]]s Parts in this group. + + +--Example-- +Look at a symbol file made with the program. diff --git a/doc/type/symbol_variation.txt b/doc/type/symbol_variation.txt index cc237af6..d40265c1 100644 --- a/doc/type/symbol_variation.txt +++ b/doc/type/symbol_variation.txt @@ -1,46 +1,46 @@ -Data type: symbol variation - ---Overview-- - -A variation of a symbol, describes color and border. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''Required'' Name of this variation, refered to by the [[fun:symbol_variation]] function. -| @border radius@ [[type:double]] @0.05@ Border radius of the symbol. -| @fill type@ @solid@ or @linear gradient@ or @radial gradient@ - @"solid"@ How to fill the symbol. - -Depending on the @fill type@ there are additional properties: -! Fill type Property Type Description -| @"solid"@ @fill color@ [[type:color]] Color to use for filling the symbol. -| ^^^ @border color@ [[type:color]] Color to use for the border of the symbol. -| @"linear gradient"@ @fill color 1@ [[type:color]] Color to use for filling the symbol at the center of the gradient. -| ^^^ @border color 1@ [[type:color]] Color to use for the border of the symbol at the center of the gradient. -| ^^^ @fill color 2@ [[type:color]] Color to use for filling the symbol at the ends of the gradient. -| ^^^ @border color 2@ [[type:color]] Color to use for the border of the symbol at the ends of the gradient. -| ^^^ @center x@, @center y@ [[type:double]] Position of the center point of the gradient (in the range 0 to 1) -| ^^^ @end x@, @end y@ [[type:double]] Position of the end point of the gradient (in the range 0 to 1) -| @"radial gradient"@ @fill color 1@ [[type:color]] Color to use for filling the symbol at the center of the symbol. -| ^^^ @border color 1@ [[type:color]] Color to use for the border of the symbol at the center of the symbol. -| ^^^ @fill color 2@ [[type:color]] Color to use for filling the symbol at the edges of the symbol. -| ^^^ @border color 2@ [[type:color]] Color to use for the border of the symbol at the edges of the symbol. - ---Examples-- -'Common' and 'uncommon' magic expansion symbol styles: ->variation: -> name: common -> border radius: 0.10 -> # White border, black fill -> fill type: solid -> fill color: rgb(0,0,0) -> border color: rgb(255,255,255) ->variation: -> name: uncommon -> border radius: 0.05 -> fill type: linear gradient -> # Black border, silver gradient fill -> fill color 1: rgb(224,224,224) -> fill color 2: rgb(84, 84, 84) -> border color 1: rgb(0, 0, 0) -> border color 2: rgb(0, 0, 0) +Data type: symbol variation + +--Overview-- + +A variation of a symbol, describes color and border. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''Required'' Name of this variation, refered to by the [[fun:symbol_variation]] function. +| @border radius@ [[type:double]] @0.05@ Border radius of the symbol. +| @fill type@ @solid@ or @linear gradient@ or @radial gradient@ + @"solid"@ How to fill the symbol. + +Depending on the @fill type@ there are additional properties: +! Fill type Property Type Description +| @"solid"@ @fill color@ [[type:color]] Color to use for filling the symbol. +| ^^^ @border color@ [[type:color]] Color to use for the border of the symbol. +| @"linear gradient"@ @fill color 1@ [[type:color]] Color to use for filling the symbol at the center of the gradient. +| ^^^ @border color 1@ [[type:color]] Color to use for the border of the symbol at the center of the gradient. +| ^^^ @fill color 2@ [[type:color]] Color to use for filling the symbol at the ends of the gradient. +| ^^^ @border color 2@ [[type:color]] Color to use for the border of the symbol at the ends of the gradient. +| ^^^ @center x@, @center y@ [[type:double]] Position of the center point of the gradient (in the range 0 to 1) +| ^^^ @end x@, @end y@ [[type:double]] Position of the end point of the gradient (in the range 0 to 1) +| @"radial gradient"@ @fill color 1@ [[type:color]] Color to use for filling the symbol at the center of the symbol. +| ^^^ @border color 1@ [[type:color]] Color to use for the border of the symbol at the center of the symbol. +| ^^^ @fill color 2@ [[type:color]] Color to use for filling the symbol at the edges of the symbol. +| ^^^ @border color 2@ [[type:color]] Color to use for the border of the symbol at the edges of the symbol. + +--Examples-- +'Common' and 'uncommon' magic expansion symbol styles: +>variation: +> name: common +> border radius: 0.10 +> # White border, black fill +> fill type: solid +> fill color: rgb(0,0,0) +> border color: rgb(255,255,255) +>variation: +> name: uncommon +> border radius: 0.05 +> fill type: linear gradient +> # Black border, silver gradient fill +> fill color 1: rgb(224,224,224) +> fill color 2: rgb(84, 84, 84) +> border color 1: rgb(0, 0, 0) +> border color 2: rgb(0, 0, 0) diff --git a/doc/type/tagged_string.txt b/doc/type/tagged_string.txt index 844f65af..aa7f8444 100644 --- a/doc/type/tagged_string.txt +++ b/doc/type/tagged_string.txt @@ -1,58 +1,58 @@ -Data type: string with tags - ---Syntax-- -Strings in [[type:value|text values]] can contain markup tags. -These tags affect the presentation and sometimes the behaviour of the text. - -A tag is something like @"some text"@, similar to HTML. -Tags are closed by the same tag with a @/@ before it. - -To represent the character @"<"@ in a tagged string use @"\<"@ in script code. -This is written as the character with code 1 in files. - ---Basic markup-- -! Tag Description -| @@ The text inside the tag is bold. -| @@ The text inside the tag is italic. -| @@ The text inside the tag is rendered as symbols, if a [[prop:style:symbol font]] is set for the text box. -| @@ The text inside the tag is rendered with the given [[type:color]]. -| @@ The text inside the tag is rendered with the given font size in points, for example @"text"@ makes the text 12 points. The text is scaled down proportionally when it does not fit in a text box and the @scale down to@ attribute allows it. -| @@ Line breaks inside this tag use the [[prop:style:line height line]], and they show a horizontal line. -| @@ Line breaks inside this tag use the [[prop:style:soft line height]]. -| @@ An atomic piece of text. The cursor can never be inside it; it is selected as a whole. - The program automatically inserts @@. -| @@ The text inside the tag is rendered in a monospace font. This is used for syntax highlighting script code. -| @@ The text inside the tag is highlighted as a keyword in source code. -| @@ The text inside the tag is highlighted as a string in source code. - - ---Other tags-- -! Tag Description -| @@ 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: - * @@, Reminder text hidden, by default - * @@, Reminder text shown, by default - * @@, Reminder hidden manually - * @@, Reminder shown manually -| @@ 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. -| @@ At the beginning of a string, indicates a part that can not be selected. This tag is automatically inserted by the [[fun:combined_editor]] function. -| @@ At the end of a string, indicates a part that can not be selected. This tag is automatically inserted by the [[fun:combined_editor]] function. -| @@ Like @@, only hidden. This is inserted by [[fun:combined_editor]] -| @@ Text who's width is ignored for alignment, similar to @@, but not a separator. -| @@ Indicate that the text inside the tag should be selected from a [[type:word list]]. - The ??? must be the name of a word list in the game. -| @@ The text inside the tag is an error, and is shown with a red wavy underline. -| @@ A spelling error, marked by the [[fun::check_spelling]] function. - The ??? part indicates the language used for spelling checking. -| any other tag Other tags are ignored. - - ---Related functions-- -The following script functions deal with tags: -| [[fun:tag_contents]] Change the contents of a specific tag. -| [[fun:remove_tag]] Remove a tag, keep the contents. -| [[fun:remove_tags]] Remove all tags from tagged text. -| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. +Data type: string with tags + +--Syntax-- +Strings in [[type:value|text values]] can contain markup tags. +These tags affect the presentation and sometimes the behaviour of the text. + +A tag is something like @"some text"@, similar to HTML. +Tags are closed by the same tag with a @/@ before it. + +To represent the character @"<"@ in a tagged string use @"\<"@ in script code. +This is written as the character with code 1 in files. + +--Basic markup-- +! Tag Description +| @@ The text inside the tag is bold. +| @@ The text inside the tag is italic. +| @@ The text inside the tag is rendered as symbols, if a [[prop:style:symbol font]] is set for the text box. +| @@ The text inside the tag is rendered with the given [[type:color]]. +| @@ The text inside the tag is rendered with the given font size in points, for example @"text"@ makes the text 12 points. The text is scaled down proportionally when it does not fit in a text box and the @scale down to@ attribute allows it. +| @@ Line breaks inside this tag use the [[prop:style:line height line]], and they show a horizontal line. +| @@ Line breaks inside this tag use the [[prop:style:soft line height]]. +| @@ An atomic piece of text. The cursor can never be inside it; it is selected as a whole. + The program automatically inserts @@. +| @@ The text inside the tag is rendered in a monospace font. This is used for syntax highlighting script code. +| @@ The text inside the tag is highlighted as a keyword in source code. +| @@ The text inside the tag is highlighted as a string in source code. + + +--Other tags-- +! Tag Description +| @@ 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: + * @@, Reminder text hidden, by default + * @@, Reminder text shown, by default + * @@, Reminder hidden manually + * @@, Reminder shown manually +| @@ 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. +| @@ At the beginning of a string, indicates a part that can not be selected. This tag is automatically inserted by the [[fun:combined_editor]] function. +| @@ At the end of a string, indicates a part that can not be selected. This tag is automatically inserted by the [[fun:combined_editor]] function. +| @@ Like @@, only hidden. This is inserted by [[fun:combined_editor]] +| @@ Text who's width is ignored for alignment, similar to @@, but not a separator. +| @@ Indicate that the text inside the tag should be selected from a [[type:word list]]. + The ??? must be the name of a word list in the game. +| @@ The text inside the tag is an error, and is shown with a red wavy underline. +| @@ A spelling error, marked by the [[fun::check_spelling]] function. + The ??? part indicates the language used for spelling checking. +| any other tag Other tags are ignored. + + +--Related functions-- +The following script functions deal with tags: +| [[fun:tag_contents]] Change the contents of a specific tag. +| [[fun:remove_tag]] Remove a tag, keep the contents. +| [[fun:remove_tags]] Remove all tags from tagged text. +| [[fun:to_text]] Remove all tags from tagged text, and convert it to a [[type:string]]. diff --git a/doc/type/value.txt b/doc/type/value.txt index 10410a6d..e38fbe41 100644 --- a/doc/type/value.txt +++ b/doc/type/value.txt @@ -1,51 +1,51 @@ -Data type: Field value - ---Overview-- - -A value is something that is 'stored in' a [[type:field]]. - -Values are part of the [[file:style triangle]]: -| Description Looks Data -| [[type:Game]] [[type:Stylesheet]] [[type:Set]] -| [[type:Field]] [[type:Style]] '''Value''' - ---Possible types-- - -The type of a value depends on the corresponding field: -! Field type Value data type Description -| @"text"@ [[type:tagged string]] A piece of text, possibly with markup. -| @"choice"@ [[type:string]] One of the choices of the field. -| @"multiple choice"@ [[type:string]] A list of choices from the field, separated by commas.
- For example: @"red, green, blue"@. -| @"package choice"@ Name of a package The (file)name of a package, including the extension. -| @"boolean"@ @"yes"@ or @"no"@ This can be directly used as a [[type:boolean]] value in scripts. -| @"image"@ [[type:filename]] Filename of an image file in the [[type:set]] package. -| @"symbol"@ [[type:filename]] Filename of a [[type:symbol]] file in the [[type:set]] package.
- When accessed from a script, image fields can be directly used as [[type:image]]s. -| @"color"@ opaque [[type:color]] A color. -| @"info"@ [[type:string]] A label for the information box. - ---File syntax-- - -DOC_MSE_VERSION: since 2.0.1 - -Values are stored using script syntax. This makes means that a value can be parsed without knowing the field type. -Here are some examples ->some_text_value: "This is a string\nNext line." ->some_choice_value: "uncommon" ->some_image_value: local_image_file("image1.png") ->some_symbol_value: local_symbol_file("symbol1.mse-symbol") - ---Example (old syntax)-- - -DOC_MSE_VERSION: before 2.0.1 - -For the field: ->field: -> type: choice -> name: card color -> choice: red -> choice: green -> choice: blue -A value could be: ->card color: red +Data type: Field value + +--Overview-- + +A value is something that is 'stored in' a [[type:field]]. + +Values are part of the [[file:style triangle]]: +| Description Looks Data +| [[type:Game]] [[type:Stylesheet]] [[type:Set]] +| [[type:Field]] [[type:Style]] '''Value''' + +--Possible types-- + +The type of a value depends on the corresponding field: +! Field type Value data type Description +| @"text"@ [[type:tagged string]] A piece of text, possibly with markup. +| @"choice"@ [[type:string]] One of the choices of the field. +| @"multiple choice"@ [[type:string]] A list of choices from the field, separated by commas.
+ For example: @"red, green, blue"@. +| @"package choice"@ Name of a package The (file)name of a package, including the extension. +| @"boolean"@ @"yes"@ or @"no"@ This can be directly used as a [[type:boolean]] value in scripts. +| @"image"@ [[type:filename]] Filename of an image file in the [[type:set]] package. +| @"symbol"@ [[type:filename]] Filename of a [[type:symbol]] file in the [[type:set]] package.
+ When accessed from a script, image fields can be directly used as [[type:image]]s. +| @"color"@ opaque [[type:color]] A color. +| @"info"@ [[type:string]] A label for the information box. + +--File syntax-- + +DOC_MSE_VERSION: since 2.0.1 + +Values are stored using script syntax. This makes means that a value can be parsed without knowing the field type. +Here are some examples +>some_text_value: "This is a string\nNext line." +>some_choice_value: "uncommon" +>some_image_value: local_image_file("image1.png") +>some_symbol_value: local_symbol_file("symbol1.mse-symbol") + +--Example (old syntax)-- + +DOC_MSE_VERSION: before 2.0.1 + +For the field: +>field: +> type: choice +> name: card color +> choice: red +> choice: green +> choice: blue +A value could be: +>card color: red diff --git a/doc/type/vector2d.txt b/doc/type/vector2d.txt index a4f38183..2f38d1f1 100644 --- a/doc/type/vector2d.txt +++ b/doc/type/vector2d.txt @@ -1,15 +1,15 @@ -Data type: two dimensional vector - -A coordinate or direction in a symbol. -This is a pair of [[type:double]]s. - -The coordinates are usually in the range @0@ to @1@. -@(0,0)@ is the top-left of the symbol, @(1,1)@ the bottom-right. - ---File syntax-- -> (x-coordinate,y-coordinate) -For example -> (0.5,0.5) - ---Script syntax-- -Vectors can not be represented in script syntax. +Data type: two dimensional vector + +A coordinate or direction in a symbol. +This is a pair of [[type:double]]s. + +The coordinates are usually in the range @0@ to @1@. +@(0,0)@ is the top-left of the symbol, @(1,1)@ the bottom-right. + +--File syntax-- +> (x-coordinate,y-coordinate) +For example +> (0.5,0.5) + +--Script syntax-- +Vectors can not be represented in script syntax. diff --git a/doc/type/version.txt b/doc/type/version.txt index 2cbc8199..52c96277 100644 --- a/doc/type/version.txt +++ b/doc/type/version.txt @@ -1,11 +1,11 @@ -Primitive type: version number - ---File syntax-- -A version number consists of three components, in the form "a.b.c". -Higher numbers mean newer versions. - -The version number can also be a date, of the form "YYYY-MM-DD" - ---Examples-- -> version: 1.2.3 -> version: 2007-07-12 +Primitive type: version number + +--File syntax-- +A version number consists of three components, in the form "a.b.c". +Higher numbers mean newer versions. + +The version number can also be a date, of the form "YYYY-MM-DD" + +--Examples-- +> version: 1.2.3 +> version: 2007-07-12 diff --git a/doc/type/word_list.txt b/doc/type/word_list.txt index 861b78b2..445f73f1 100644 --- a/doc/type/word_list.txt +++ b/doc/type/word_list.txt @@ -1,18 +1,18 @@ -Data type: word list - -A list of words. Used for drop down lists in the text editor, for example for card types. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''Required'' Name of this word list, refered to using a @""@ tag. -| @words@ [[type:list]] of [[type:word list word]]s ''Required'' The words in the list - ---Example-- ->word list: -> name: type -> word: Creature -> word: Spell -> word: Artifact -This can be used with for example: -> @"Creature"@ -Which gives the creature choice, and that can be changed with a drop down list. +Data type: word list + +A list of words. Used for drop down lists in the text editor, for example for card types. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''Required'' Name of this word list, refered to using a @""@ tag. +| @words@ [[type:list]] of [[type:word list word]]s ''Required'' The words in the list + +--Example-- +>word list: +> name: type +> word: Creature +> word: Spell +> word: Artifact +This can be used with for example: +> @"Creature"@ +Which gives the creature choice, and that can be changed with a drop down list. diff --git a/doc/type/word_list_word.txt b/doc/type/word_list_word.txt index ef5166da..d9ab5429 100644 --- a/doc/type/word_list_word.txt +++ b/doc/type/word_list_word.txt @@ -1,34 +1,34 @@ -Data type: word list word - -A word in a [[type:word list]]. - ---Properties-- -! Property Type Default Description -| @name@ [[type:string]] ''Required'' The word. -| @line below@ [[type:boolean]] @false@ Display a line below this item in the list? -| @is prefix@ [[type:boolean]] @false@ Should this word be used as a prefix before another word from the list?
- Think "Legendary ". Note the space after it, words are directly concatenated. -| @words@ [[type:list]] of [[type:word list word]]s A submenu. If given, the @name@ of this word is only used as a label for the menu. -| @script@ [[type:script]] ''Optional'' A script that determines zero or more words.
- The result should be a list of comma separated words, for example @"x,y,z"@ specifies three words. - The words are included in the parent menu, not a sub menu. - -A word can also be given in a short form, in that case only the name is specified. - ---Example-- -In short form: ->word: xyz -Is the same as: ->word: -> name: xyz - -Using a script, ->word: -> script: "red,green,blue" -> line below: true -Is the same as ->word: blue ->word: green ->word: -> name: red -> line below: true +Data type: word list word + +A word in a [[type:word list]]. + +--Properties-- +! Property Type Default Description +| @name@ [[type:string]] ''Required'' The word. +| @line below@ [[type:boolean]] @false@ Display a line below this item in the list? +| @is prefix@ [[type:boolean]] @false@ Should this word be used as a prefix before another word from the list?
+ Think "Legendary ". Note the space after it, words are directly concatenated. +| @words@ [[type:list]] of [[type:word list word]]s A submenu. If given, the @name@ of this word is only used as a label for the menu. +| @script@ [[type:script]] ''Optional'' A script that determines zero or more words.
+ The result should be a list of comma separated words, for example @"x,y,z"@ specifies three words. + The words are included in the parent menu, not a sub menu. + +A word can also be given in a short form, in that case only the name is specified. + +--Example-- +In short form: +>word: xyz +Is the same as: +>word: +> name: xyz + +Using a script, +>word: +> script: "red,green,blue" +> line below: true +Is the same as +>word: blue +>word: green +>word: +> name: red +> line below: true diff --git a/src/cli/cli_main.cpp b/src/cli/cli_main.cpp index 1ffd0807..fc76bbce 100644 --- a/src/cli/cli_main.cpp +++ b/src/cli/cli_main.cpp @@ -1,275 +1,300 @@ -//+----------------------------------------------------------------------------+ -//| Description: Magic Set Editor - Program to make Magic (tm) cards | -//| Copyright: (C) 2001 - 2012 Twan van Laarhoven and Sean Hunt | -//| License: GNU General Public License 2 or later (see file COPYING) | -//+----------------------------------------------------------------------------+ - -// ----------------------------------------------------------------------------- : Includes - -#include "util/prec.hpp" -#include "util/error.hpp" -#include "cli/cli_main.hpp" -#include "cli/text_io_handler.hpp" -#include "script/functions/functions.hpp" -#include "script/profiler.hpp" -#include "data/format/formats.hpp" -#include -#include -#include - -using std::min; - -String read_utf8_line(wxInputStream& input, bool eat_bom = true, bool until_eof = false); - - -// ----------------------------------------------------------------------------- : Command line interface - -CLISetInterface::CLISetInterface(const SetP& set, bool quiet) - : quiet(quiet) - , our_context(nullptr) -{ - if (!cli.haveConsole()) { - throw Error(_("Can not run command line interface without a console;\nstart MSE with \"mse.com --cli\"")); - } - ei.allow_writes_outside = true; - setExportInfoCwd(); - setSet(set); - // show welcome logo - if (!quiet) showWelcome(); - cli.print_pending_errors(); -} - -CLISetInterface::~CLISetInterface() { - delete our_context; -} - -Context& CLISetInterface::getContext() { - if (set) { - return set->getContext(); - } else { - if (!our_context) { - our_context = new Context(); - init_script_functions(*our_context); - } - return *our_context; - } -} - -void CLISetInterface::onBeforeChangeSet() { - if (set || our_context) { - Context& ctx = getContext(); - ctx.closeScope(scope); - } -} - -void CLISetInterface::onChangeSet() { - Context& ctx = getContext(); - scope = ctx.openScope(); - ei.set = set; -} - -void CLISetInterface::setExportInfoCwd() { - // write to the current directory - ei.directory_relative = ei.directory_absolute = wxGetCwd(); - // read from the current directory - ei.export_template = intrusive(new Package()); - ei.export_template->open(ei.directory_absolute, true); -} - - -// ----------------------------------------------------------------------------- : Running - -void CLISetInterface::run_interactive() { - // loop - running = true; - while (running) { - // show prompt - if (!quiet) { - cli << GRAY << _("> ") << NORMAL; - cli.flush(); - } - // read line from stdin - String command = cli.getLine(); - if (command.empty() && !cli.canGetLine()) break; - handleCommand(command); - cli.print_pending_errors(); - cli.flush(); - cli.flushRaw(); - } -} - -bool CLISetInterface::run_script(ScriptP const& script) { - try { - WITH_DYNAMIC_ARG(export_info, &ei); - Context& ctx = getContext(); - ScriptValueP result = ctx.eval(*script,false); - // show result (?) - cli << result->toCode() << ENDL; - return true; - } CATCH_ALL_ERRORS(true); - return false; -} - -bool CLISetInterface::run_script_string(String const& command, bool multiline) { - vector errors; - ScriptP script = parse(command,nullptr,false,errors); - if (errors.empty()) { - return run_script(script); - } else { - for(auto& error :errors) { - if (multiline) { - cli.show_message(MESSAGE_ERROR, String::Format(_("On line %d:\t"), error.line) + error.what()); - } else { - cli.show_message(MESSAGE_ERROR, error.what()); - } - } - return false; - } -} - -bool CLISetInterface::run_script_file(String const& filename) { - // read file - if (!wxFileExists(filename)) { - cli.show_message(MESSAGE_ERROR, _("File not found: ")+filename); - return false; - } - wxFileInputStream is(filename); - if (!is.Ok()) { - cli.show_message(MESSAGE_ERROR, _("Unable to open file: ")+filename); - return false; - } - wxBufferedInputStream bis(is); - String code = read_utf8_line(bis, true, true); - run_script_string(code); - return true; -} - -void CLISetInterface::showWelcome() { - cli << _(" ___ \n") - _(" __ __ _ ___ _ ___ _ _ _ |__ \\ \n") - _(" | \\/ |__ _ __ _(_)__ / __|___| |_ | __|__| (_) |_ ___ _ _ ) |\n") - _(" | |\\/| / _` / _` | / _| \\__ | -_) _| | _|/ _` | | _/ _ \\ '_| / / \n") - _(" |_| |_\\__,_\\__, |_\\__| |___|___|\\__| |___\\__,_|_|\\__\\___/_| / /_ \n") - _(" |___/ |____|\n\n"); - cli.flush(); -} - -void CLISetInterface::showUsage() { - cli << _(" Commands available from the prompt:\n\n"); - cli << _(" Execute a script expression, display the result\n"); - cli << _(" :help Show this help page.\n"); - cli << _(" :load Load a different set file.\n"); - cli << _(" :quit Exit the MSE command line interface.\n"); - cli << _(" :reset Clear all local variable definitions.\n"); - cli << _(" :pwd Print the current working directory.\n"); - cli << _(" :cd Change the working directory.\n"); - cli << _(" :! Perform a shell command.\n"); - cli << _("\n Commands can be abreviated to their first letter if there is no ambiguity.\n\n"); -} - -void CLISetInterface::handleCommand(const String& command) { - try { - if (command.empty()) { - // empty, ignore - } else if (command.GetChar(0) == _(':')) { - // :something - size_t space = min(command.find_first_of(_(' ')), command.size()); - String before = command.substr(0,space); - String arg = space + 1 < command.size() ? command.substr(space+1) : wxEmptyString; - if (before == _(":q") || before == _(":quit")) { - if (!quiet) { - cli << _("Goodbye\n"); - } - running = false; - } else if (before == _(":?") || before == _(":h") || before == _(":help")) { - showUsage(); - } else if (before == _(":l") || before == _(":load")) { - if (arg.empty()) { - cli.show_message(MESSAGE_ERROR,_("Give a filename to open.")); - } else { - setSet(import_set(arg)); - } - } else if (before == _(":r") || before == _(":reset")) { - Context& ctx = getContext(); - ei.exported_images.clear(); - ctx.closeScope(scope); - scope = ctx.openScope(); - } else if (before == _(":i") || before == _(":info")) { - if (set) { - cli << _("set: ") << set->identification() << ENDL; - cli << _("filename: ") << set->absoluteFilename() << ENDL; - cli << _("relative: ") << set->relativeFilename() << ENDL; - cli << String::Format(_("#cards: %d"), set->cards.size()) << ENDL; - } else { - cli << _("No set loaded") << ENDL; - } - } else if (before == _(":c") || before == _(":cd")) { - if (arg.empty()) { - cli.show_message(MESSAGE_ERROR,_("Give a new working directory.")); - } else { - if (!wxSetWorkingDirectory(arg)) { - cli.show_message(MESSAGE_ERROR,_("Can't change working directory to ")+arg); - } else { - setExportInfoCwd(); - } - } - } else if (before == _(":pwd") || before == _(":p")) { - cli << ei.directory_absolute << ENDL; - } else if (before == _(":!")) { - if (arg.empty()) { - cli.show_message(MESSAGE_ERROR,_("Give a shell command to execute.")); - } else { - #ifdef UNICODE - #ifdef __WXMSW__ - _wsystem(arg.c_str()); // TODO: is this function available on other platforms? - #else - wxCharBuffer buf = arg.fn_str(); - system(buf); - #endif - #else - system(arg.c_str()); - #endif - } - #if USE_SCRIPT_PROFILING - } else if (before == _(":profile")) { - if (arg == _("full")) { - showProfilingStats(profile_root); - } else { - long level = 1; - arg.ToLong(&level); - showProfilingStats(profile_aggregated(level)); - } - #endif - } else { - cli.show_message(MESSAGE_ERROR,_("Unknown command, type :help for help.")); - } - } else if (command == _("exit") || command == _("quit")) { - cli << _("Use :quit to quit\n"); - } else if (command == _("help")) { - cli << _("Use :help for help\n"); - } else { - run_script_string(command); - } - } catch (const Error& e) { - cli.show_message(MESSAGE_ERROR,e.what()); - } -} - -#if USE_SCRIPT_PROFILING - void CLISetInterface::showProfilingStats(const FunctionProfile& item, int level) { - // show parent - if (level == 0) { - cli << GRAY << _("Time(s) Avg (ms) Calls Function") << ENDL; - cli << _("======== ======== ====== ===============================") << NORMAL << ENDL; - } else { - for (int i = 1 ; i < level ; ++i) cli << _(" "); - cli << String::Format(_("%8.5f %8.5f %6d %s"), item.total_time(), 1000 * item.avg_time(), item.calls, item.name.c_str()) << ENDL; - } - // show children - vector children; - item.get_children(children); - for(auto& c : boost::adaptors::reverse(children)) { - showProfilingStats(*c, level + 1); - } - } -#endif +//+----------------------------------------------------------------------------+ +//| Description: Magic Set Editor - Program to make Magic (tm) cards | +//| Copyright: (C) 2001 - 2012 Twan van Laarhoven and Sean Hunt | +//| License: GNU General Public License 2 or later (see file COPYING) | +//+----------------------------------------------------------------------------+ + +// ----------------------------------------------------------------------------- +// : Includes + +#include "util/prec.hpp" +#include "util/error.hpp" +#include "cli/cli_main.hpp" +#include "cli/text_io_handler.hpp" +#include "script/functions/functions.hpp" +#include "script/profiler.hpp" +#include "data/format/formats.hpp" +#include +#include +#include + +using std::min; + +String read_utf8_line(wxInputStream &input, bool eat_bom = true, + bool until_eof = false); + +// ----------------------------------------------------------------------------- +// : Command line interface + +CLISetInterface::CLISetInterface(const SetP &set, bool quiet) + : quiet(quiet), our_context(nullptr) { + if (!cli.haveConsole()) { + throw Error(L"Can not run command line interface without a console;\n" + L"Start MSE with \"mse.com --cli\""); + } + ei.allow_writes_outside = true; + setExportInfoCwd(); + setSet(set); + // show welcome logo + if (!quiet) + showWelcome(); + cli.print_pending_errors(); +} + +CLISetInterface::~CLISetInterface() { delete our_context; } + +Context &CLISetInterface::getContext() { + if (set) { + return set->getContext(); + } else { + if (!our_context) { + our_context = new Context(); + init_script_functions(*our_context); + } + return *our_context; + } +} + +void CLISetInterface::onBeforeChangeSet() { + if (set || our_context) { + Context &ctx = getContext(); + ctx.closeScope(scope); + } +} + +void CLISetInterface::onChangeSet() { + Context &ctx = getContext(); + scope = ctx.openScope(); + ei.set = set; +} + +void CLISetInterface::setExportInfoCwd() { + // write to the current directory + ei.directory_relative = ei.directory_absolute = wxGetCwd(); + // read from the current directory + ei.export_template = intrusive(new Package()); + ei.export_template->open(ei.directory_absolute, true); +} + +// ----------------------------------------------------------------------------- +// : Running + +void CLISetInterface::run_interactive() { + // loop + running = true; + while (running) { + // show prompt + if (!quiet) { + cli << GRAY << L"> " << NORMAL; + cli.flush(); + } + // read line from stdin + String command = cli.getLine(); + if (command.empty() && !cli.canGetLine()) + break; + handleCommand(command); + cli.print_pending_errors(); + cli.flush(); + cli.flushRaw(); + } +} + +bool CLISetInterface::run_script(ScriptP const &script) { + try { + WITH_DYNAMIC_ARG(export_info, &ei); + Context &ctx = getContext(); + ScriptValueP result = ctx.eval(*script, false); + // show result (?) + cli << result->toCode() << ENDL; + return true; + } + CATCH_ALL_ERRORS(true); + return false; +} + +bool CLISetInterface::run_script_string(String const &command, bool multiline) { + vector errors; + ScriptP script = parse(command, nullptr, false, errors); + if (errors.empty()) { + return run_script(script); + } else { + for (auto &error : errors) { + if (multiline) { + cli.show_message(MESSAGE_ERROR, + String::Format(L"On line %d:\t", error.line) + + error.what()); + } else { + cli.show_message(MESSAGE_ERROR, error.what()); + } + } + return false; + } +} + +bool CLISetInterface::run_script_file(String const &filename) { + // read file + if (!wxFileExists(filename)) { + cli.show_message(MESSAGE_ERROR, L"File not found: " + filename); + return false; + } + wxFileInputStream is(filename); + if (!is.Ok()) { + cli.show_message(MESSAGE_ERROR, L"Unable to open file: " + filename); + return false; + } + wxBufferedInputStream bis(is); + String code = read_utf8_line(bis, true, true); + run_script_string(code); + return true; +} + +void CLISetInterface::showWelcome() { + // clang-format off + cli << LR"++(\ ++---------------------------------------------------------------------------+ +| ___ | +| __ __ _ ___ _ ___ _ _ _ |__ \ | +| | \/ |__ _ __ _(_)__ / __|___| |_ | __|__| (_) |_ ___ _ _ ) | | +| | |\/| / _` / _` | / _| \__ | -_) _| | _|/ _` | | _/ _ \ '_| / / | +| |_| |_\__,_\__, |_\__| |___|___|\__| |___\__,_|_|\__\___/_| / /_ | +| |___/ |____| | +| | ++---------------------------------------------------------------------------+ +)++"; + // clang-format on + cli.flush(); +} + +void CLISetInterface::showUsage() { + // clang-format off + cli << L" Commands available from the prompt:\n\n"; + cli << L" Execute a script expression, display the result\n"; + cli << L" :help Show this help page.\n"; + cli << L" :load Load a different set file.\n"; + cli << L" :quit Exit the MSE command line interface.\n"; + cli << L" :reset Clear all local variable definitions.\n"; + cli << L" :pwd Print the current working directory.\n"; + cli << L" :cd Change the working directory.\n"; + cli << L" :! Perform a shell command.\n"; + cli << L"\n Commands can be abreviated to their first letter if there is no ambiguity.\n\n"; + // clang-format on +} + +void CLISetInterface::handleCommand(const String &command) { + try { + if (command.empty()) { + // empty, ignore + } else if (command.GetChar(0) == L':') { + // :something + size_t space = min(command.find_first_of(L' '), command.size()); + String before = command.substr(0, space); + String arg = space + 1 < command.size() ? command.substr(space + 1) + : wxEmptyString; + if (before == L":q" || before == L":quit") { + if (!quiet) { + cli << L"Goodbye\n"; + } + running = false; + } else if (before == L":?" || before == L":h" || + before == L":help") { + showUsage(); + } else if (before == L":l" || before == L":load") { + if (arg.empty()) { + cli.show_message(MESSAGE_ERROR, + L"Give a filename to open."); + } else { + setSet(import_set(arg)); + } + } else if (before == L":r" || before == L":reset") { + Context &ctx = getContext(); + ei.exported_images.clear(); + ctx.closeScope(scope); + scope = ctx.openScope(); + } else if (before == L":i" || before == L":info") { + if (set) { + cli << L"set: " << set->identification() << ENDL; + cli << L"filename: " << set->absoluteFilename() << ENDL; + cli << L"relative: " << set->relativeFilename() << ENDL; + cli << String::Format(L"#cards: %d", set->cards.size()) + << ENDL; + } else { + cli << L"No set loaded" << ENDL; + } + } else if (before == L":c" || before == L":cd") { + if (arg.empty()) { + cli.show_message(MESSAGE_ERROR, + L"Give a new working directory."); + } else { + if (!wxSetWorkingDirectory(arg)) { + cli.show_message(MESSAGE_ERROR, + L"Can't change working directory to " + + arg); + } else { + setExportInfoCwd(); + } + } + } else if (before == L":pwd" || before == L":p") { + cli << ei.directory_absolute << ENDL; + } else if (before == L":!") { + if (arg.empty()) { + cli.show_message(MESSAGE_ERROR, + L"Give a shell command to execute."); + } else { +#ifdef __WXMSW__ + _wsystem(arg.c_str()); // TODO: is this function available + // on other platforms? +#else + wxCharBuffer buf = arg.fn_str(); + system(buf); +#endif + } +#if USE_SCRIPT_PROFILING + } else if (before == L":profile") { + if (arg == L"full") { + showProfilingStats(profile_root); + } else { + long level = 1; + arg.ToLong(&level); + showProfilingStats(profile_aggregated(level)); + } +#endif + } else { + cli.show_message(MESSAGE_ERROR, + L"Unknown command, type :help for help."); + } + } else if (command == L"exit" || command == L"quit") { + cli << L"Use :quit to quit\n"; + } else if (command == L"help") { + cli << L"Use :help for help\n"; + } else { + run_script_string(command); + } + } catch (const Error &e) { + cli.show_message(MESSAGE_ERROR, e.what()); + } +} + +#if USE_SCRIPT_PROFILING +void CLISetInterface::showProfilingStats(const FunctionProfile &item, + int level) { + // show parent + if (level == 0) { + cli << GRAY << L"Time(s) Avg (ms) Calls Function" << ENDL; + cli << L"======== ======== ====== ===============================" + << NORMAL << ENDL; + } else { + for (int i = 1; i < level; ++i) + cli << L" "; + cli << String::Format(L"%8.5f %8.5f %6d %s", item.total_time(), + 1000 * item.avg_time(), item.calls, + item.name.c_str()) + << ENDL; + } + // show children + vector children; + item.get_children(children); + for (auto &c : boost::adaptors::reverse(children)) { + showProfilingStats(*c, level + 1); + } +} +#endif diff --git a/src/cli/cli_main.hpp b/src/cli/cli_main.hpp index c70d6b44..a9c2e976 100644 --- a/src/cli/cli_main.hpp +++ b/src/cli/cli_main.hpp @@ -1,55 +1,60 @@ -//+----------------------------------------------------------------------------+ -//| Description: Magic Set Editor - Program to make Magic (tm) cards | -//| Copyright: (C) 2001 - 2012 Twan van Laarhoven and Sean Hunt | -//| License: GNU General Public License 2 or later (see file COPYING) | -//+----------------------------------------------------------------------------+ - -#ifndef HEADER_CLI_MAIN -#define HEADER_CLI_MAIN - -// ----------------------------------------------------------------------------- : Includes - -#include -#include -#include -#include