{{
#vardefine:name|split_string}}{{
#vardefine:return_type|string [int]}}{{
#vardefine:aggregate|yes}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|source}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|source}}|
parameter2={{Param|string|delimiter}}|
p1desc={{Pspan|source}} is the string to split|
p2desc={{Pspan|delimiter}} is the (optional) [[Regular Expressions|regular expression]] to split with|
}}|

function_description=Returns an array of your {{pspan|source}}, split by either {{pspan|delimiter}} or by line-breaks if not supplied.|

needscode=yes|

special=This function technically returns an array, not a map. The information in both is accessed in the same way. However, you cannot add new key-value pairs to an array (its length is static once set).|
}}

[[Category:String Handling Routines]]

Talk:Data Types

2011-02-18T03:36:30Z

StDoodle: /* Re: rollback */

=Note=

This page copied from the deletion-in-progress Datatype Constants discussion page.

=Old Discussion=

Yes, this page should be renamed & such. It's another artifact of the way things were when I started working on the wiki, that unfortunately became a "hub" of sorts without being properly changed. However, since HUNDREDS of pages link here, we really need to be a bit more careful before moving this page. It should probably be done by a mod (to avoid automatic redirect creation) AFTER various prerequisites are taken care of. --[[User:StDoodle|StDoodle (#1059825)]] 04:29, 21 June 2010 (UTC)

*Thanks for clarification, and sorry about not discussing it first. --[[User:PhilmASTErpLus|PhilmASTErpLus]]

Ugh. It's worse than I thought; when templates are nested, it takes a while for the "what links here" pages to get updated. I've started the process of transitioning from "Datatype Constantes" to "Data Types," but it may be a while before it's complete. Warning: please leave this project alone, I've got a handle on it & don't want confilcts. Thanks. --[[User:StDoodle|StDoodle (#1059825)]] 04:52, 14 July 2010 (UTC)

Yeah, uh, finger slipped. Oops. (Undone now, don't worry about it.) --[[User:Heeheehee|Heeheehee]] 12:09, 22 June 2010 (UTC)

It's all yours. Good luck with it. --[[User:Bale|Bale]] 05:17, 14 July 2010 (UTC)

Gee that was fun (not). But I think it's done; KoLmafia wiki, now 50% less untechnically accurate! --[[User:StDoodle|StDoodle (#1059825)]] 05:38, 14 July 2010 (UTC)

== Call by value or call by reference? ==

I actually wrote a simple script to see how it works. Apparently all the primitive data types are called by value when passed to a function, whereas maps and records are called by reference (with smart garbage collection!). I presume this is the same for substitution(<code>=</code>), and that buffers are called by reference, though I haven't tried either. Could someone high up there please verify this information before I add it? --[[User:PhilmASTErpLus|PhilmASTErpLus]] 07:14, 23 June 2010 (UTC)

= Re: rollback =

I'm not using the very latest daily, I know, but on r9045 it DOESN'T change the result if you JUST change the 2 to 2.0. I get 0.0 as my result. Can you double-check that this has changed? --[[User:StDoodle|StDoodle (#1059825)]] 03:34, 18 February 2011 (UTC)

Er, edit to clarify; could someone verify that this is INTENDED, and thus safe advice, vs. just being a side-effect of some other change, and subject to revert to the behavior I'm seeing. --[[User:StDoodle|StDoodle (#1059825)]] 03:36, 18 February 2011 (UTC)

Talk:Data Types

2011-02-18T03:34:10Z

StDoodle: /* Call by value or call by reference? */

Data Types

2011-02-18T03:32:56Z

StDoodle: Reverted edits by Bale (Talk) to last revision by StDoodle

{{TOCright}}
==Primitive Datatypes==

===void===
Can be thought of better as the absence of a datatype. No value can be assigned to '''void''' nor can a value be returned from a function of datatype '''void'''.

===boolean===
A boolean value is either '''true''' or '''false'''. By default, a boolean variable is set to false.

===int===

A whole number (short for "integer"), either positive or negative (or 0). The int used by KoLmafia is a 32-bit signed int, meaning it has a maximum value of 2,147,483,647 and a minimum value of -2,147,483,648. The default value of a integer variable is 0.

Be careful when doing math with integers! As with some other strongly-typed languages, numbers are converted to integers at every step of the operation when only integer types are used. For example:
{{
CodeSample|
code=
<syntaxhighlight>
int a = 1;
int b = 2;
print( a / b * 2 );
</syntaxhighlight>}}
Will give the output "0," not "1" as you may expect. Changing either variable to a float type will "correct" this.

===float===

The float data type is a single-precision 32-bit IEEE 754 floating point. Its range of values is beyond the scope of this discussion, but is specified in section 4.2.3 of the Java Language Specification. [http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3]

When assigning to a variable of type float, one should be careful to always enter numbers in decimal form, as unwanted behavior can result from supplying a value that KoLmafia may interpret as an int type without the decimal point.

Note that float is not infinitely precise; it intrinsically rounds off after a certain point. This loss of accuracy is for the sake of storage, but beware of the possibility of small errors compounding from multiple float types.
{{
CodeSample|
description=For instance, try the following code as an example of how rather long post-decimal portions are handled:|
code=
<syntaxhighlight>
float f;
f = 4.9999999;
print( f );
</syntaxhighlight>}}
The default value of a <code>float</code> variable is 0.0.

===string===

A group of characters including, but not limited to: lowercase letters, uppercase characters, numbers, and various control characters. When assigning a value to a string, always enclose the desired value in either single or double quotes (note you must use the same quote type on both ends of the string assignment). If you need to include the same character inside of the string itself, you will need to escape it first with a backslash.{{CodeSample|
description=For example:|
code=
<syntaxhighlight>
string s = "This is my \"friend\" Pete.";
</syntaxhighlight>|
moreinfo=
Will result in the following being stored to s:
<pre>This is my "friend" Pete</pre>}}
The default value of a string is an empty string, or literally <code>""</code>.

===buffer===

Similar to a string, but more efficient in certain operations, including concatenation and passing as function arguments. For the most part, you can interchange references to strings and buffers. However, you should test all such actions first, as a few functions require a specific datatype to be supplied as a parameter. (Most notably, those listed under [[String Handling Routines#Regular Expressions|Regular Expressions]].)

==Special Datatypes==

Several datatypes are included in KoLmafia to represent common categories within the KoL universe.

Note that while variables of these types are declared in the same way as for Primitive Datatypes; assigning and referencing them is done differently.
{{CodeSample|
description=For example, to declare an item datatype and assign it a value, you would use the following line of code:|
code=
<syntaxhighlight>
item it = $item[ broken skull ];
</syntaxhighlight>}}
The default values of any variable of one of the following types is <code>$''type''[ none ]</code>. For example, the default value of a <code>item</code> variable is <code>$item[ none ]</code>.

===class===

Besides $class[ none ], there are six possible values for this datatype:

* Seal Clubber
* Turtle Tamer
* Pastamancer
* Sauceror
* Disco Bandit
* Accordion Thief

===effect===

Any effect you can be under in KoL, whether from items, skills, or what-have-you, is valid for this datatype.

The full range, besides $effect[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Effects}} page for more information.

===element===

Besides $element[ none ], there are six possible values for this datatype. (Note that "Bad Spelling" is not considered a true element.)
Also note that these names are case-sensitive (referencing $element[ Spooky ] will generate an error).

* cold
* hot
* sleaze
* spooky
* stench
* slime

===familiar===

Any familiar available in KoL is valid for this datatype.

The full range, besides $familiar[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Familiars}} page for more information.

===item===

Any item in all of KoL is valid for this datatype. Note that unlike most special datatypes, item references can make use of the item ID number.
{{CodeSample|
description=For example, you could assign the item plexiglass pants as follows:|
code=
<syntaxhighlight>
item it = $item[ 1234 ];
</syntaxhighlight>}}
The full range, besides $item[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Items}} page for more information.

===location===

Any location one can adventure at in KoL is valid for this datatype.

The full range, besides $location[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Locations}} page for more information.

===monster===

Any monster you can encounter in KoL is valid for this datatype.

The full range, besides $monster[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Monster Compendium}} page for more information.

===skill===
Any skill you can have in KoL (whether permable or not, granted by items, etc.) is valid for this datatype.

The full range, besides $skill[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Skills}} page for more information.

===slot===

Besides $slot[ none ], there are 13 possible values for this datatype.

* hat
* weapon
* off-hand
* shirt
* pants
* acc1
* acc2
* acc3
* familiar
* sticker1
* sticker2
* sticker3
* fakehand

===stat===

Besides $stat[ none ], there are six possible values for this datatype (the last three are for referencing sub-stats).

* muscle
* mysticality
* moxie
* submuscle
* submysticality
* submoxie

==aggregate==

An aggregate is a complex datatype composed of two or more primitive or special datatypes. For more information, see [[Data Structures]].

==record==

Records are user-defined datatypes that hold as many sub-datatypes as desired. For more information, see the page for [[Data Structures]].

==Plural Typed Constants==

(see http://kolmafia.us/showthread.php?p=15592, from which this section is reproduced)

Plural typed constants allow you to easily do something with a list of specified objects, without having to replicate code or laboriously build up an array of the objects so that you can iterate over it. Here's a quick example:
{{CodeSample|code=<syntaxhighlight>
foreach weapon in $items[star sword, star staff, star crossbow] {
if (available_amount(weapon) > 0) {
equip(weapon);
break;
}
}</syntaxhighlight>}}
The syntax is basically the same as the existing typed constant feature, but with an "s" or "es" after the type name. (The "es" case is there so that you can properly pluralize "class".) The text between the square brackets is interpreted as a comma-separated list of elements, each of which is converted to the specified type as if it were an individual constant. More details:
* The list can span multiple lines.
* Whitespace before or after elements is ignored.
* Completely empty elements are ignored (so that you can leave a comma at the end of the list).
* You can include a comma or closing square bracket in an element by writing it as "\," or "\]".
* All the other escape sequences allowed in strings are possible, such as "\n" (newline), "\t" (tab), and "\uXXXX" (Unicode character value). To put an actual backslash in an element, you have to write it as "\\".

The value generated by a plural constant is of type boolean[type], with the keys being the specified elements, and the boolean value always being true - although you won't normally do anything with the boolean, you'd use a foreach loop to iterate over the keys. You can assign a plural constant to a variable declared as that type, but note that the value differs from a normal map in three important respects:
* Since the expression that generates it is syntactically a constant, the value has to be immutable. If you were allowed to change it in any way, those changes would appear in every future use of the same constant.
* There can be multiple instances of the same key - $ints[1,1,2,3,5,8] is perfectly valid, and will result in the value 1 appearing twice in a foreach loop.
* The keys will appear in the order you wrote them, rather than being sorted alphanumerically as maps usually do.

In addition to being used in a foreach loop, plural constants also efficiently support membership testing via the 'contains' operator. Here's another example:
{{CodeSample|code=<syntaxhighlight>
for hour from 1 to 12 {
print("It's " + hour + " o'clock.");
if ($ints[10, 2, 4] contains hour) {
print("Time to drink a Dr Pepper!");
}
}</syntaxhighlight>}}
(Yes, that example could just as easily have been done with a switch statement.)

Iterating over an empty list is rather pointless, so plural constants with no elements are given a different meaning: they represent every value of the specified type, where this is practical. (The 'none' value, if defined for a given type, is omitted.) The biggest benefit here is $items[], which lets you loop over every defined item, more efficiently than you could otherwise write in a script (since the list is generated once per session and then cached), and without having to hard-code a maximum item ID number in your script. Example:
{{CodeSample|code=<syntaxhighlight>
foreach it in $items[] {
if (autosell_price(it) == 42) print(it);
}</syntaxhighlight>}}
Enumeration of all possible values works with the following types:
* $booleans[] - false and true.
* $items[]
* $locations[]
* $classes[]
* $stats[] - Muscle, Mysticality, Moxie: the substat values are omitted.
* $skills[]
* $effects[]
* $familiars[]
* $slots[] - includes sticker slots and fake hands, which you might not want to consider as normal slots.
* $monsters[]
* $elements[] - includes slime now, and possibly other not-quite-elements like cute in the future.

The remaining types that can be used in plural constants require an explicit list of elements, since there are too many possible values:
* $ints[] - you don't have enough RAM to store a list with 4 billion elements.
* $floats[] - ditto.
* $strings[] - nobody has that much RAM.

==Custom==

===matcher===

A matcher isn't really a datatype so much as it's a class, but it is included here for reference, as it is used much as datatypes are in ASH. It can only be declared through the function {{f|create_matcher}}, using two strings. One is the string to find matches in, the other a regular expression to test against. For more information on using a matcher, see [[Regular Expressions]].

[[Category:Scripting]]

2011-01-26T16:04:40Z

StDoodle: /* Boolean Operators */

{{TOCright}}
==Mathematical Operators==

The following mathematical operators are used in KoLmafia:
{{
eztable|
{{eztr|{{eztd| + |Addition|Performs addition and string concatenation}}}}
{{eztr|{{eztd| - |Subtraction|Performs subtraction}}}}
{{eztr|{{eztd| * |Multiplication|Performs multiplication}}}}
{{eztr|{{eztd| / |Division|Performs division}}}}
{{eztr|{{eztd| % |Modulo|Returns the remainder after division}}}}
{{eztr|{{eztd| ** |Exponent|Performs exponentiation}}}}
}}
Note that, with the exception of using <nowiki>"+"</nowiki> for string concatenation, these operators can only be used on int or float datatypes.

==Bitwise Operators==

The following mathematical operators are used for operating on the bits of integers. The operands must be integers; no coercion is allowed:
{{
eztable|
{{eztr|{{eztd| <nowiki>&</nowiki> |and|a & b}}}}
{{eztr|{{eztd| <nowiki>|</nowiki> |or|a <nowiki>|</nowiki> b}}}}
{{eztr|{{eztd| ~ |not|~a}}}}
{{eztr|{{eztd| << |left shift|a << b}}}}
{{eztr|{{eztd| >> |right shift|a >> b}}}}
{{eztr|{{eztd| <nowiki>&=</nowiki> |and|<nowiki>a &= b --> a = a & b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>|=</nowiki> |or|<nowiki>a |= b --> a = a | b</nowiki>}}}}
{{eztr|{{eztd| >>> |unsigned right shift|a >>> b}}}}
}}

==Assignment Operators==
The following assignment operators are used in KoLmafia (let a = left operand, b = right operand):
{{
eztable|
{{eztr|{{eztd| <nowiki>=</nowiki> |<nowiki>a = b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>+=</nowiki> |<nowiki>a = a + b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>-=</nowiki> |<nowiki>a = a - b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>*=</nowiki> |<nowiki>a = a * b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>/=</nowiki> |<nowiki>a = a / b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>%=</nowiki> |<nowiki>a = a % b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>**=</nowiki> |<nowiki>a = a ** b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>>>=</nowiki> |<nowiki>a = a >> b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>>>>=</nowiki> |<nowiki>a = a >>> b</nowiki>}}}}
}}
Of these, only += and = are usable for strings. See [[Operators#Mathematical Operators|Mathematical Operators]] for information regarding the basic Mathematical Operators.

==Relational Operators==

To follow these examples, a basic understanding of the concepts found on [[Control Structures]] would be helpful.

In order to create more complex if statements, we need to understand the basic relational operators:
{{
eztable|
{{eztr|{{eztd| <nowiki>==</nowiki> |equal to}}}}
{{eztr|{{eztd| <nowiki>!=</nowiki> |not equal to}}}}
{{eztr|{{eztd| <nowiki><</nowiki> |less than}}}}
{{eztr|{{eztd| <nowiki>></nowiki> |greater than}}}}
{{eztr|{{eztd| <nowiki><=</nowiki> |less than or equal to}}}}
{{eztr|{{eztd| <nowiki>>=</nowiki> |greater than or equal to}}}}
}}
Note that you cannot mix datatypes within a comparison or KoLmafia will abort with an error, with the exception of mixing types int and float, where KoLmafia will do a transparent type conversion behind-the-scenes. If you need to compare different datatypes, use one or more of the [[Datatype Conversions|Datatype Conversion]] functions. Also, == is case-insensitive with respect to strings.

{{
CodeSample|
code=
<syntaxhighlight>
if ( true == true )
{
print( "This line DOES get printed." );
}
if ( true == false )
{
print( "This line does NOT get printed." );
}
if ( 1 == 1.0 )
{
print( "This line DOES get printed." );
}
if ( 1 == 2 )
{
print( "This line does NOT get printed." );
}
if ( "Hello" == "hello" )
{
print( "This line DOES get printed." );
}
</syntaxhighlight>}}
==Boolean Operators==
{{
eztable|
{{eztr|{{eztd| <nowiki>&&</nowiki> |and}}}}
{{eztr|{{eztd| <nowiki>||</nowiki> |or}}}}
{{eztr|{{eztd| <nowiki>!</nowiki> |not}}}}
}}
Note that the above operators only work with boolean values & datatypes. To make use of them with other datatypes, you will either need to first perform a [[Datatype Conversions|Datatype Conversion]], or you will need to nest your operations such that a boolean value is used with the boolean operators.
{{
CodeSample|
code=
<syntaxhighlight>
if ( true && true )
{
print( "This line DOES get printed (both possibilities proved true)." );
}
if ( true && false )
{
print( "This line does NOT get printed (only one possibility proved true)." );
}
if ( true || false )
{
print( "This line DOES get printed (since at least one of the possibilities proved true)." );
}
if ( ! false )
{
print( "This line DOES get printed (since the not operator converted false to true)." );
}
</syntaxhighlight>}}
We also need to understand operator precedence. Statements inside a () pair are always evaluated first, then from right to left.
{{
CodeSample|
code=
<syntaxhighlight>
if ( true || true && false )
{
print( "This line DOES get printed." );
// evaluated right-to-left
// true or (true && false) returns true
}
if ( ( true && false ) && true )
{
print( "This line does NOT get printed." );
// ( true && false ) is evaluated first since it is inside of parentheses
// so we end up evaluating ( false && true ) which returns false
}
if ( true && ! ( true && false ) )
{
print( "This line DOES get printed." );
// ( true && false ) is evaluated first since it is inside of parentheses
// the ! operator converts the false from ( true && false ) to true
// ( true && true ) returns true
}
</syntaxhighlight>}}

==Operator Precedence==

KoLmafia follows [http://download.oracle.com/javase/tutorial/java/nutsandbolts/operators.html Java's Operator Precedence rules] with a few exceptions.

[[Category:Scripting]]

Category talk:Tech Support

2011-01-21T22:17:14Z

StDoodle: Created page with 'We should brainstorm on how we want this category organized and what should be added. I'm looking into getting into editing / reviewing the source myself, and I'd love clearer he…'

2010-12-03T15:41:19Z

StDoodle:

<includeonly>{{Lnkstart}}#{{{1}}}{{!}}{{{1}}}(){{Lnkend}}</includeonly>
<noinclude>
A simple way of linking to a function '''on the same page''', but displaying it with the parentheses.
[[Category:Basic Templates]]
</noinclude>

Template:Fa

2010-12-03T15:40:01Z

StDoodle:

Template:Fa

2010-12-03T15:37:48Z

StDoodle:

<includeonly>{{
Lnkstart}}£{{{
1}}}{{
!}}{{{
1}}}(){{
Lnkend}}</includeonly><noinclude>
A simple way of linking to a function '''on the same page''', but displaying it with the parentheses.
[[Category:Basic Templates]]
</noinclude>

Template:Fa

2010-12-03T15:37:27Z

StDoodle: Created page with '<includeonly>{{ Lnkstart}}£{{{ 1}}}{{ !}}{{{ 1}}}(){{ Lnkend}}</includeonly><noinclude> A simple way of linking to a function page, but displaying it with the paren…'

<includeonly>{{
Lnkstart}}£{{{
1}}}{{
!}}{{{
1}}}(){{
Lnkend}}</includeonly><noinclude>
A simple way of linking to a function page, but displaying it with the parentheses.
[[Category:Basic Templates]]
</noinclude>

Htmlform

2010-12-03T15:30:00Z

StDoodle:

{{TOCright}}{{DISPLAYTITLE:HTMLform (htmlform.ash)}}
{{Attention|
This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
}}
== About jasonharper's Form Library ==
[http://kolmafia.us/showthread.php?3842 HTMLform] is a code library for building relay browser scripts that accept user input.

== Scope ==

The purpose of HTMLform is to allow you to write relay scripts without necessarily having a deep knowledge of HTML forms (although you will need to know at least a bit about HTML formatting if you want your scripts to look nice). It is designed to make the process of gathering input from the user look like a simple sequence of prompts, when in fact the script is being reloaded multiple times in order to present and validate the user's choices.

== Globals ==

There are two global variables defined by the library that you'll need to know about:
'''string [string]''' ''fields'' is a map holding the result of a call to {{f|form_fields}}. The current value of any input element can be retrieved as '''''fields[name]''''', although you probably won't have to do that very often as the functions that actually write the elements to the page will return the current value of that element. You can also modify values in the map, prior to writing the corresponding element, to change their value - for example, to change the default values of certain fields based on the user's input in other fields.
The global '''boolean''' ''success'' is true when a valid page submission has occurred - the fields map will be non-empty (unlike the initial run of the script in which the choices are initially shown in the browser), and none of the fields have a validation failure. Button actions should generally be conditional on this variable being true (and will automatically be so, if you use the [[#test_button|test_button()]] function).

All other internal global variables, and functions for internal use, have names starting with an underscore, to minimize the chance of a name collision with your script.

== Names ==

Every HTML form element requires a distinguishing name, which for maximum compatibility should be chosen with the same basic rules as ASH variables - start with a letter, use only numbers and letters. Take care if you're generating names automatically; for example, if you were generating a field for each item in a list, it would be a bad idea to use the actual item names as (part of) the fields' names, since items may have arbitrarily weird characters in their names. The items' ID numbers (retrievable with {{f|to_int}}) would be a much safer basis for making field names.

For the most part, element names must be distinct (and strange things will happen if you violate that). There are two exceptions:
* Radio buttons normally come in mutually-exclusive groups, all of which must share the same name - in fact, that's the only thing that relates them as a group (there's no requirement for them to be physically grouped, although of course that would usually be good style).
* Submit buttons can share a name if they do the same thing - for example, you might want to have a "Save changes" button at both the top and bottom of a tall form. If a button has no action at all (it just updates the form), its name can be left blank.

== Attributes ==

There is a large and ever-growing set of optional attributes that can be specified to customize the appearance and behavior of HTML form elements. It would be utterly impractical for htmlform to have optional parameters for every possible attribute, or even for every particularly useful attribute. Instead, you can supply arbitrary attributes by preceding the call that writes an element with one or more calls to:
void attr( string attribute )
The string will be inserted at the appropriate place in the HTML tag being written. If called multiple times, the strings will be separated by spaces.

{{att_box|{{att|title='TEXT'}} will add a tooltip to any element. Advanced users may want to use style & class attributes for fine control over element appearance. A complete list of attributes is entirely beyond the scope of this documentation (see any HTML reference, instead), but the most useful ones will be pointed out in blocks like this.}}

== Validators ==

The functions that produce a field for the user to type in (write_field() and write_textarea()) can be passed the name of a validator function that can check (and possibly modify) the field value. Any validation failure is shown in red to the right of the field, and blocks submission of the form until the user corrects the problem. Validator functions are provide for all the datatypes for which typed-in values make sense:
intvalidator, floatvalidator, itemvalidator, locationvalidator, skillvalidator, effectvalidator, familiarvalidator, monstervalidator
(They AREN'T provided for types like 'class' and 'slot' that have only a few possible values; other input elements are more appropriate in those cases).
None of these accept the 'none' value; there is a separate itemnonevalidator that will accept items or 'none' (similar validators for other types didn't seem likely to be as useful). There is also a nonemptyvalidator that simply requires the entered string to not be blank.

intvalidator and floatvalidator additionally support bounds checking via the function:
void range( float min, float max ) - place this just before the call to write_field().

The provided validators only check that the entered text is something understandable to KoLmafia - not that you (for example) actually have the named familiar, or that the item goes in some specific slot. If you want to perform such checks, you'll need to write your own validator, which is just a function with one string parameter (the element name), that returns a string. Any non-empty string is treated as a validation error. Returning an empty string indicates success, in which case the function is allowed to modify the value in the fields[] map, which will update the value shown in the browser. (That's why the function is passed the field name, rather than the field value. All of the built-in validators that allow fuzzy matching use this feature, in order to replace an abbreviated user entry with the full, proper name of the object.) Here's a simple example that verifies that the entered text is a valid item (duplicating the function of itemvalidator), which furthermore is a hat that you own:

== Generating the Page Structure ==
{{HideLink|write_header}}{{Function|
name=write_header|
return_type=void|
}}
{{Function|
name=finish_header|
return_type=void|
}}
{{Function|
name=write_page|
return_type=void|
}}
write_page() is equivalent to write_header() followed by finish_header(), but the separate functions may be preferred so that you can add information into the page header such as a script or stylesheet.

{{HideLink|finish_page}}{{Function|
name=finish_page|
return_type=void|
}}
This must be used at the end of the form.

{{HideLink|write_box}}{{Function|
name=write_box|
parameter1={{Param|string|label}}|
return_type=void|
}}
{{Function|
name=finish_box|
return_type=void|
}}
These can be used in matched pairs around a group of elements to enclose them in a box. The label will be at the top of the box. 
'''attr("align=center")''' or '''attr("align=right")''' will change the position of the label.

== Making use of HTMLform ==

To include this library in your script, first you must download it from the location provided below and make sure it is in your /scripts directory (or a sub-directory thereof). Then, simply add the following towards the top any script in which you wish to have access to these functions:
{{CodeSample|
code=
<syntaxhighlight>
import "htmlform.ash";
</syntaxhighlight>}}
Then all these functions will be available in your script. Have fun! Note that most of these functions are intended for use in relay info scripts, which must be placed in the /relay directory (top-level only, no sub-directories) and must begin with "relay_" to show in the user's relay browser.

== More Information ==
See the thread for HTMLform on the KoLmafia forum [http://kolmafia.us/showthread.php?3842 here].

[[Category:Scripting]][[Category:ASH Function Libraries]]

Template:Att

2010-12-03T15:25:04Z

StDoodle:

<includeonly>attr("{{{1}}}" )</includeonly>
<noinclude>
For use on [[htmlform]]
[[Category:HTMLform Templates]]
</noinclude>

Template:Att box

2010-12-03T15:23:27Z

StDoodle:

<includeonly><div style="border: dashed 1px #aa2000;">USEFUL ATTRIBUTES
<div style="padding: 0 1em;">{{{1}}}</div></div>
</includeonly>
<noinclude>
For use on [[htmlform]]
[[Category:HTMLform Templates]]
</noinclude>