diff --git a/doc/function/chosen.txt b/doc/function/chosen.txt index e69de29b..5adb5de2 100644 --- a/doc/function/chosen.txt +++ b/doc/function/chosen.txt @@ -0,0 +1,17 @@ +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 diff --git a/doc/function/combined_editor.txt b/doc/function/combined_editor.txt index e69de29b..8a9f775c 100644 --- a/doc/function/combined_editor.txt +++ b/doc/function/combined_editor.txt @@ -0,0 +1,44 @@ +Function: combined_editor + +--Usage-- +> forward_editor(field: some_text_value) +> combined_editor(field1: some_text_value, field2: some_text_value, ..., separtor1: 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 separtors in <sep> 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 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.'' +| @hide when empty@ [[type:boolean]] Don't include separators if the entire value is empty. +| @soft before empty@ [[type:boolean]] Make separators 'soft' when the value folowing 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/drop_shadow.txt b/doc/function/drop_shadow.txt index e69de29b..3e2b0ddc 100644 --- a/doc/function/drop_shadow.txt +++ b/doc/function/drop_shadow.txt @@ -0,0 +1,24 @@ +Function: drop_shadow + +--Usage-- +> drop_shadow(image, offset_x: offset, offset_y: offset) + +Add a drop shadow to an image. + +--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 +| @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/enlarge.txt b/doc/function/enlarge.txt index 45693c1e..65f94ef5 100644 --- a/doc/function/enlarge.txt +++ b/doc/function/enlarge.txt @@ -13,4 +13,4 @@ The border size is given in percentages of the image size, so @border_size: 1@ m --Examples-- > enlarge(input: "image1.png", border_size: 0.1) == [[Image]] ->>> enlarge(light: "image1.png", border_size: 0.1) == "image_enlarge.png" +>>> enlarge(input: "image1.png", border_size: 0.1) == "image_enlarge.png" diff --git a/doc/function/exclusive_choice.txt b/doc/function/exclusive_choice.txt new file mode 100644 index 00000000..cb347821 --- /dev/null +++ b/doc/function/exclusive_choice.txt @@ -0,0 +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. diff --git a/doc/function/filter_text.txt b/doc/function/filter_text.txt index db210b18..eb81c63c 100644 --- a/doc/function/filter_text.txt +++ b/doc/function/filter_text.txt @@ -8,6 +8,9 @@ Filter text by only keeping the parts of the input that match the regular expres If @in_context@ is given, the context must also match the string where the match is represented as <match>. +This function is available in [[script:rule form]]. +When the filter is used many times the rule form is more efficient, because the regular expression is only compiled once. + --Parameters-- ! Parameter Type Description | @input@ [[type:string]] String to replace in. diff --git a/doc/function/image4.png b/doc/function/image4.png new file mode 100644 index 00000000..eaa29de7 Binary files /dev/null and b/doc/function/image4.png differ diff --git a/doc/function/image_drop_shadow_1.png b/doc/function/image_drop_shadow_1.png new file mode 100644 index 00000000..c2ea860e Binary files /dev/null and b/doc/function/image_drop_shadow_1.png differ diff --git a/doc/function/image_drop_shadow_2.png b/doc/function/image_drop_shadow_2.png new file mode 100644 index 00000000..7783f4b2 Binary files /dev/null and b/doc/function/image_drop_shadow_2.png differ diff --git a/doc/function/process_english_hints.txt b/doc/function/process_english_hints.txt index e69de29b..86875efa 100644 --- a/doc/function/process_english_hints.txt +++ b/doc/function/process_english_hints.txt @@ -0,0 +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" diff --git a/doc/function/remove_choice.txt b/doc/function/remove_choice.txt index e69de29b..853ab1eb 100644 --- a/doc/function/remove_choice.txt +++ b/doc/function/remove_choice.txt @@ -0,0 +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. +| [[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/require_choice.txt b/doc/function/require_choice.txt index e69de29b..563c3a8c 100644 --- a/doc/function/require_choice.txt +++ b/doc/function/require_choice.txt @@ -0,0 +1,29 @@ +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. +| @choice@ [[type:string]] Choice to require. +| @choice1@ [[type:string]] Require multiple choices. +| @choice2@ [[type:string]] ''etc.'' + +--Examples-- +> require_choice(choice: "red", "red") == "red" +> require_choice(choice: "red", "blue") == "blue, red" +> require_choice(choice: "red", "red, blue") == "red, blue" +> require_choice(choice1: "red", choice2: "green", "red, blue") == "red, blue" +> require_choice(choice1: "red", choice2: "green", "red, green") == "red, blue" +> require_choice(choice1: "red", choice2: "green", "green, blue") == "green, blue" +> require_choice(choice1: "red", choice2: "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 new file mode 100644 index 00000000..151f040b --- /dev/null +++ b/doc/function/require_exclusive_choice.txt @@ -0,0 +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. diff --git a/doc/function/symbol_variation.txt b/doc/function/symbol_variation.txt index e69de29b..0d60d65c 100644 --- a/doc/function/symbol_variation.txt +++ b/doc/function/symbol_variation.txt @@ -0,0 +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 varations 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 filter]] 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]]