Hamster-Scripts: Functions (built-in)

Miscellaneous

sleep( <millisecs> )

Waits the given amount of milliseconds (1/1000 seconds).

Returns: Given sleep time.

sleep( 60000 ) # 1 minute

iif( <condition>, <true-result>, <false-result> )

Returns <true-result>, if <condition> is other than zero, <false-result> otherwise.

Returns: As given.

print( iif( $answer="42", "Correct!", "Wrong!" ) )

icase( <value>, <compare1>, <result1> [ , <c2>, <r2> ... ] )

Compares <value> with <compare1>, and if both values are equal, <result1> is returned. Otherwise, all remaining <compare#>/<result#>-pairs are tested the same way, until one matches. The special <compare#>-value "else" matches always, so if used, it should be the last one.

Returns: The selected result or 0 if no pair matched and there was no else-part.

$word = icase( $digit, _
           0, "Zero", 1, "One", 2, "Two", 3, "Three", 4, "Four", _
           5, "Five", 6, "Six", 7, "Seven", 8, "Eight", 9, "Nine", _
           else, "User, we have a problem!" _
        )

gosub( <identifier> )

Looks for a "label" with the given identifier and continues execution right after it. Such a "subroutine" has to be terminated with "return".

Returns: Return-value.

print( gosub( Test ) )
quit
label( Test )
   # ...
return( 42 )

RunScript( <script>, <params>, <wait> )

RunScript( <script>, <params> )
RunScript( <script> )

Starts the given <script> file with given <params>.

If <wait> is given and True (default), the command does not return until the started script has finished.

Returns: 0=Ok, -1=Error, -2=Script not found.

varset( $CRLF, chr(13)+chr(10) )
runscript( "doit.hsc", "par1" + $CRLF + "par2" + $CRLF + "par3" )

ParamCount

Returns the number of parameters, with which the script was started.

Returns: Number.

# see ParamStr below

ParamStr( <index> )

Returns one of the parameters, with which the script was started. Each parameter is numbered with an <index> ranging from 1 to ParamCount.
Calling with <index> = 0 returns the name of the current scriptfile.

Returns: String.

var( $i )
print( "Script: ", ParamStr( 0 ) )
for( $i, 1, ParamCount )
   print( "Par. ", $i, ": ", ParamStr( $i ) )
endfor

random( <limit> )

Returns a random number in the range ( 0 <= result < <limit> ).

Returns: Number.

print( Random(6)+1 )

digest( <type>, <string>, <ashex> )

digest( <type>, <string> )

Returns checksum/digest for the given <string>.
Supported <types> are 0 (CRC32, integer), 1 (MD5, 16 chars), 2 (SHA1, 20 chars).
If third parameter is given and true (<>0), the digest is returned as a hex string.

Returns: Digest value.

print( Digest( 1, "MD5-Test!", True ) )

decode( <type>, <string>, <keyword>, <errvar> )

decode( <type>, <string>, <keyword> )
decode( <type>, <string> )

Returns decoded value for the given <string>.
Supported <types> are 0 (base64), 1 (quoted printable), 2 (QP/B64 in headers), 3 (like 2, but return value UTF-8 encoded).
Third parameter is not used so far.
Fourth parameter can be a variable receiving success of decoding (<>0: ok, =0: failed).

Note: Decoding of <types> 1 and 2 can only be used for very simple purposes like making something "readable" for human beings.

Returns: Decoded value.

print( Decode( 0, $Base64Str ) )

encode( <type>, <string>, <keyword>, <errvar> )

encode( <type>, <string>, <keyword> )
encode( <type>, <string> )

Similar to Decode, but encodes the given string.
<type> 2 is not supported here.
Note: Encoding of <type> 1 can only be used for very simple purposes like making something "readable" for human beings.

Returns: Encoded value.

print( Encode( 0, "Text to be base64 encoded" ) )

CharsetList( <list> )

Fills the given <list> with the names of all supported character sets.

Returns: Number of charsets, -1 on errors.

varset( $list, ListAlloc )
CharsetList( $list )
print( ListGetText($list) )
ListFree( $list )

CharsetExists( <name> )

Checks, if a charset with the given <name> exists.

Returns: 1 (true=exists), 0 (false)

if( CharsetExists("UTF-8") )
   print( "UTF-8 is supported!" )
endif

CharsetDefault

Returns the name of Window's default character set ("active codepage"), i. e. the character set, that the script code is assumed to be encoded in.
Note: This function always returns one of the supported character sets. It returns "windows-1252" if the real one is not supported.

Returns: Name of a supported 'windows-' charset.

print( "Default character set: ", CharsetDefault )

CharsetConvert( <data>, <cs-in>, <cs-out>, <err-var> )

CharsetConvert( <data>, <cs-in>, <cs-out> )

Converts the given <data> from character set <cs-in> to <cs-out>.

If <err-var> is given and a valid variable, it is set to 1 (true), if all characters could be converted and to 0 (false), if some characters could not be converted and were replaced by "?".

Returns: String with converted <data>

varset( $test, "The price for ,  and  is 42 " )
print( CharsetDefault, ": ", $test )
print( "ISO-8859-1: ", CharsetConvert( $test, "", "ISO-8859-1" ) )
print( "ISO-8859-15: ", CharsetConvert( $test, "", "ISO-8859-15" ) )
print( "UTF-7: ", CharsetConvert( $test, "", "UTF-7" ) )
print( "UTF-8: ", CharsetConvert( $test, "", "UTF-8" ) )
print( CharsetDefault, ": ", CharsetConvert( CharsetConvert($test,"","UTF-8"), "UTF-8", "" ) )

trace( <onoff> )

If tracing is turned on, all script-lines are displayed while they are executed. If <onoff> is 0 (false), tracing is turned off, otherwise it is turned on.

Returns: Previous trace setting.

trace( 1 )
# ...
trace( 0 )

[www.elbiah.de Hamster Playground Documentation]