_

Useful stdlib functions.

Summary

_	Useful stdlib functions.
_	StdLib loader and script initializer.
m	Debug function.
S	Struct function.
v	Storage function, designed to use as stdlib or copy and enhance.
t	Timer
d	Delay/Thread function.
Fatal	Exits the script with the message.
About

_

_( opt = "" )

StdLib loader and script initializer.

Parameters

opt	Space separated list of script options.

Options

m	Affects how m function works: mm makes it use MsgBox (default), mo OutputDebug, m alone disables it. Anything else will set it to FileAppend mode.
d	Detect hidden windows.
e	Escape exits the script. Use ea to exit the script only if its window is active.
wd	SetWorkingDir %A_ScriptDir%
wN	SetWinDelay. If N is omitted, it defaults to -1.
cN	SetControlDelay. If N is omitted, it defaults to -1.
sN	Speed, will always be set in first call to this function (defaults to -1). Subsequent calls will set scripts speed only if s is explicitly set up.
t?	Title match mode: t1 (or ts), t2 (or tc), t3 (or te), tr (regular expression).

Example

_("s100 d e")   ;set speed to 100ms, detect hiden windows, exit on ESC.
_("mo wd tc")   ;set m to use OutputDebug, set working directory to A_ScriptDir, set title match mode to c (c=2="contain").
_("mout.txt!")  ;set m to use File out.txt and to clear it each time script is started.


_("m")          ;disable m for the script.
....
m( x, y )       ;will not trigger
...
if x = 1
    _("mm")     ;enable m after this point and use msgbox.
    ....
    m(x, y)     ;will trigger
    ...
    _("m")      ;disable it again

Remarks

Includes #NoEnv and #SingleInstance force always. Keep in mind that calling this function will set scripts speed to maximum.

m

m( o1 = "~`a",
o2 = "~`a",
o3 = "~`a",
o4 = "~`a",
o5 = "~`a",
o6 = "~`a",
o7 = "~`a",
o8 = "~`a" )

Debug function.

Parameters

o1..o8

Arguments to display.

Modes

Function can work in 4 modes:

m	MsgBox mode.
o[!]	OutputDebug mode. All arguments will be joined in single line. The function will use DbgView.exe for monitoring. Program must be copied into the location that is in system PATH (for instance Windows dir).
word[!]	FileAppend mode. Word is the name of the text file (no spaces) that will be used to save messages.
””	Disabled mode. Function will simply return without taking any action.

You can set mode by using _ function and its “m” option.

Returns

o1.

Remarks

! at the end means that medium used will be erased when script starts.

Example

if m( (x - m(y) = z) ) ; Use m inside expressions for debugging.

S

S( ByRef S,
pQ,
ByRef o1 = "~`a ",
ByRef o2 = "",
ByRef o3 = "",
ByRef o4 = "",
ByRef o5 = "",
ByRef o6 = "",
ByRef o7 = "",
ByRef o8 = "" )

Struct function. With S, you define structure, then you can put or get values from it. It also allows you to create your own library of structures that can be included at the start of the program.

Define

Must be omitted or empty variable.

Struct definition. First word is struct name followed by : and a space, followed by space separated list of field definitions. Field definition consists of field name, optionally followed by = sign and decimal number representation of offset and type. For instance, “left=4.1” means that field name is “left”, field offset is 4 bytes and field type is 1 (UChar). You can omit field decimal in which case “Uint” is used as default type and offset is calculated from previous one (or it defaults to 0 if it is first field in the list). Precede type number with 0 to make it signed type or with 00 to make it Float or Double. For instance, .01 is “Char” and .004 is Float. S will calculate the size of the struct for you based on the input fields. If you don’t define entire struct (its perfectly valid to declare only parts of the struct you are interested in) you can still define struct size by including = and size after structs name. This allows you to use ! mode later.

Define Syntax

pQ       :: StructName[=[Size]]: FieldDef1 FieldDef2 ... FieldDefN
FieldDef :: FieldName[=[Def]
Def      :: offset.[0][0]Type
Type     :: [0]1 | [0]2 | [0]4 | [0]8 | 004 | 008

Put & Get

S	Pointer to struct data.
pQ	Query parameter. First word is struct name followed by the mode char and a space, followed by the space separated list of field names. If the first char after struct name is “<” or “)” function will work in Put mode, if char is “>” or “)” it works in “Get” mode. If char is “!” function works in IPut mode (Initialize & Put). For ! to work, you must define entire struct, not just part of it. The difference between < and ( is that < works on binary data contained in S, while ( works on binary data pointed to by S. The same difference applies to > and ) modes.
o1..o8	Reference to output variables (Get) or input variables (Put)

Put & Get Syntax

pQ :: StructName[>)<(!]: FieldName1 FieldName2 ... FieldNameN

Returns

In Define mode function returns struct size.
In Get/Put mode function returns o1.

Otherwise the result contains description of the error.

Examples

Define Examples:
        S(_,"RECT=16: left=0.4 top=4.4 right=8.4 bottom=12.4")      ;Define RECT explicitly.
        S(_,"RECT: left top right bottom")  ; Define RECT struct with auto struct size and auto offset increment. Returns 16. The same as above.
        S(_,"RECT: right=8 bottom")         ; Define only 2 fields of RECT struct. Since the fields are last one, ! can be used afterwards. Returns 16.
        S(_,"RECT: top=4)                   ; Defines only 1 field of the RECT. Returns 8, so ! can't be used.
        S(_,"RECT=16: top=4)                ; Defines only 1 field of the RECT and overrides size. Returns 16, so ! can be used.
        S(-,"R: x=.1 y=.02 k z=28.004")     ; Define R, size don't care. R.x is UChar at 0, R.y is Short at 1, R.k is Uint at 3 and  R.z is Float at 28.
        S(_,"R=48: x=.1 y=.02 k z=28.004")  ; Override struct size. Returns user size (48 in this case)
                                            ;  This is not the same as above as it states that z is not the last field of the R struct and that actual size is 48.

Get & Put Examples:
        S(b, "RECT< left right", x,y)       ; b.left := x, b.right := y (b must be initialized)
        S(b, "RECT> left right", x,y)       ; x := b.left, y := b.right
        S(b, "RECT! left right", x,y)       ; VarSetCapacity(b, SizeOf(RECT)), b.left = x, b.right=y
        S(b:=&buf,"RECT) left right", x,y)  ; *b.left = x, *b.right=y
        S(b:=&buf,"RECT( left right", x,y)  ; x := *b.left , y := *b.right

v

v( var = "",
value = "~`a ",
ByRef o1 = "",
ByRef o2 = "",
ByRef o3 = "",
ByRef o4 = "",
ByRef o5 = "",
ByRef o6 = "" )

Storage function, designed to use as stdlib or copy and enhance.

Parameters

var	Variable name to retrieve. To get up several variables at once (up to 6), omit this parameter.
value	Optional variable value to set. If var is empty value contains list of vars to retrieve with optional prefix
o1 .. o6	If present, reference to variables to receive values.

Returns

if value is omitted, function returns the current value of var
if value is set, function sets the var to value and returns previous value of the var
if var is empty, function accepts list of variables in value and returns values of those variables in o1 .. o6

Remarks

To use multiple storages, copy v function and change its name.

You can choose to initialize storage from additional ahk script containing only list of assignments to storage variables, to do it internally by adding the values to the end of the your own copy of the function, or to do both, by accepting user values on startup, and checking them afterwards. If you use stdlib module without including it directly, just make v.ahk script and put variable definitions there.

Don’t use storage variables that consist only of _ character as those are used to regulate inner working of function.

Examples

v(x)        ; returns value of x or value of x from v.ahk inside scripts dir.
v(x, v)     ; set value of x to v and return previous value
v("", "x y z", x, y, z)             ; get values of x, y and z into x, y and z
v("", "prefix_)x y z", x, y, z) ; get values of prefix_x, prefix_y and prefix_z into x, y and z

t

t( ByRef v = "~`a " )

Timer

Parameters

v	Reference to output variable. Omit to reset timer.

Returns

Example

t()
loop, 10000
    f1()
p := t()

loop, 10000
    f2()
t(k)
m(p, k)

d

d( fun,
delay = "",
a1 = "",
a2 = "" )

Delay/Thread function. Thread is not OS thread, but AHK thread.

Parameters

fun	Function to be executed.
delay	Delay in ms.
a1, a2	Parameters.

Example

d("fun1", "",  1)   ;execute asap in new thread with param 1
d("fun2", 500, "abc")   ;execute after 500ms in new thread with param "abc"

Fatal

Fatal( Message,
E = 1,
ExitCode = "" )

Exits the script with the message.

Parameters

Message	Message to show.
E	Expression. By default 1. The function will exit the script only when E is True.
ExitCode	Exit code to return to the caller.

About

0.44 by majkinetor
Licensed under GNU GPL http://creativecommons.org/licenses/GPL/2.0/