AutoIt Wiki - User contributions [en]

User Defined Functions

2012-12-13T16:30:17Z

FlutterShy: /* Internet protocol suite */

[[Category:UDF]]
This page is a listing of libraries of user defined functions. These libraries have been written to allow easy integration into your own script and are a very valuable resource for any programmer.

== Automation ==
* [http://www.autoitscript.com/forum/index.php?showtopic=87956 Java UDF] - Creates an access bridge between your application and a Java application. Allowing you to automate some Java applications.
* [http://www.autoitscript.com/forum/index.php?showtopic=86574 SAP] - SAP business management automation.
* [http://www.autoitscript.com/forum/index.php?showtopic=42776 PDFCreator] - Automation of PDFCreator allows you to create and manipulate PDF files.
* [http://www.autoitscript.com/forum/index.php?showtopic=91018 WiFi] - Low level control over your wireless LAN
* [http://www.autoitscript.com/forum/index.php?showtopic=106163 Active Directory] - Extensive library to control and manipulate the Windows active directory. Link to the [[Active_Directory_UDF_-_General|documentation]] pages.
* [http://www.autoitscript.com/forum/index.php?showtopic=28436 Windows Events] - Create your own Windows events.

===Browsers===
* Internet Explorer - Everything about Internet explorer can be automated with the IE library supplied with a standard AutoIt install.
* [http://www.autoitscript.com/forum/index.php?showtopic=95595 FireFox] - A little less support for automation than IE, but still very good.
* [http://www.autoitscript.com/forum/index.php?showtopic=61090 Opera] - The same as above for Opera. Automate the most common tasks in Opera with the Opera UDF.

===Microsoft Office Automation===
* [http://www.autoitscript.com/forum/index.php?showtopic=32144 Microsoft Office Access] - Automation of Access.
* [http://www.autoitscript.com/forum/index.php?showtopic=34302 Microsoft Office Excel] - Large automation library for Excel.
* [http://www.autoitscript.com/forum/topic/135312-excelchart-udf Microsoft Office Excel] - Creating charts using Excel.
* [http://www.autoitscript.com/forum/topic/126305-outlookex-udf/ Microsoft Office Outlook] - Extended Outlook UDF. Link to the [[OutlookEX_UDF_-_General|documentation]] pages.
* Microsoft Office Word UDF - A way to automate Office Word is included with AutoIt.

== Hardware ==
* [http://www.autoitscript.com/forum/index.php?showtopic=45842 Serial port (COM port)] - Requires my comMG.dll (included)

== Information gathering ==
* [http://www.autoitscript.com/forum/index.php?showtopic=29404 Computer information] - A general purpose library to get various details about a Windows machine.

== Databases and web connections ==
* FTP - A FTP library is now included with the AutoIt libraries.
* [http://www.autoitscript.com/forum/index.php?showtopic=17099 SQLite] - "SQLite is a library that implements a self-contained, embeddable, zero-configuration SQL database engine"
* [http://www.autoitscript.com/forum/index.php?showtopic=19848 XML DOM Wrapper] - Supports CRUD operations on XML. Including XSL and XPath.
* [http://www.autoitscript.com/forum/index.php?showtopic=20814 MySQL] - MySQL relational database management system UDF.

== Internet protocol suite ==
* [http://www.autoitscript.com/forum/topic/84133-winhttp-functions/ WinHTTP] - Enables scripts to access the HTTP protocol for creating GET and POST requests and submitting them with conforming standards, cookies not supported.
* [http://www.autoitscript.com/forum/topic/77503-wininetau3-ftphttphttpsgopher/ WinInet] - Enables scripts to access standard Internet protocols, such as FTP, Gopher and HTTP. Also supports creating GET and POST requests and submitting them with conforming standards, cookies supported.
* [http://www.autoitscript.com/forum/index.php?showtopic=22838 POP3] - POP3 library for retrieving email messages. Not compatible with Gmail because it uses SSL.
* [http://www.autoitscript.com/forum/index.php?showtopic=64051 POP3 SSL] - A POP3 library that's compatible with Gmail. It uses an external executable that must be supplied with your script.
* [http://www.autoitscript.com/forum/index.php?showtopic=43515 IRC] - A lightweight library for communicating with IRC servers.

== Data compression ==
* [http://www.autoitscript.com/forum/index.php?showtopic=116565 zip] - Create ZIP files and unpack ZIP files.
* [http://www.autoitscript.com/forum/index.php?showtopic=85094 7z, zip, gzip, bzip2, tar] - More extensive library than the one above. Uses a external DLL that must be provided with the script.

== Encryption and hash ==
* [http://www.autoitscript.com/forum/index.php?showtopic=76976 MD5,SHA1,CRC32,RC4,BASE64,XXTEA] - Several encryption and hash functions.
* [http://www.autoitscript.com/forum/index.php?showtopic=78745 AES Rijndael] - Very fast AES UDF. Support ECB/CBC/CFB/OFB block cipher mode.

== Media ==
* [http://www.autoitscript.com/forum/index.php?showtopic=94834 Simple DirectMedia Layer UDF] - Adds support for joysticks, CDs, 2D graphics, timers. See [http://www.libsdl.org/ SDL website] for more information.
* [http://www.autoitscript.com/forum/index.php?showtopic=95357 FreeImage library] - Various operations on images, such as rotate, resize, flip.
* [http://www.autoitscript.com/forum/index.php?showtopic=51054 Printer controller] - Print text in any font, size and colour at any position on the page, draw lines, curves, elipses, pies in any colour, and print images.

===Sound===
* [http://www.autoitscript.com/forum/index.php?showtopic=83481 BASS Function Library] - Sound and Music via wrappers for Bass, BassEnc, Bass FX, BassSFX, BassAsio and BassCd DLLs

===3D graphics===
* [http://www.autoitscript.com/forum/index.php?showtopic=70506 IrrLicht] - A 3D graphics engine suitable for creating games.
* [http://www.autoitscript.com/forum/index.php?showtopic=113881 au3Irrlicht2] - Another UDF bringing Irrlicht and au3 together. Historically some kind of a follower of the UDF above, technically with a complete different approach.

== GUI Additions ==
* [http://www.autoitscript.com/forum/index.php?showtopic=32494 XSkin] - A large library that allows skinning of your GUI and to apply custom skins.
* [http://www.autoitscript.com/forum/topic/132864-uskinlibraryau3-udf-skin-with-dll-free-no-ads-and-fully-functional/ Uskin] - A library that allows a user to skin their application GUI using the Windows ''.MSstyles'' files.
* [http://www.autoitscript.com/forum/index.php?showtopic=20967 Modern tray menu] - Allows the creation of modern, fancy GUI and tray menus with icons.
* [http://www.autoitscript.com/forum/index.php?showtopic=71811 SetOnEvent] - Provides an easy way for an event to call functions with parameters.
* [http://www.autoitscript.com/forum/topic/119505-guiframe-udf-melba23-version/ GUIFrame] - Divide a GUI into adjustable frames.
* [http://www.autoitscript.com/forum/topic/113723-scrollbars-made-easy/ Easy Scrollbars] - Easily create scrollable sections in your GUI
* [http://www.autoitscript.com/forum/index.php?showtopic=105582 GUICtrlOnChangeRegister] - Call a function when an edits content is changed.
* [http://www.autoitscript.com/forum/topic/96258-contexthelp-au3/ ContextHelp.au3] - Management of context help ([http://www.autoitscript.com/forum/topic/72152-contexthelp/ original])
* [http://www.autoitscript.com/forum/topic/117909-guiextender-new-version-171110/ GUIExtender] - Expand and contract sections of your GUI
* [http://www.autoitscript.com/forum/topic/109096-extended-message-box-new-version-3-dec-10/ ExtMsgBox] - A very customisable replacement for MsgBox
* [http://www.autoitscript.com/forum/topic/108445-how-to-make-toast/ Toast] - Small message GUIs which pop out of the Systray

=== Controls ===
* [http://www.autoitscript.com/forum/index.php?showtopic=79412 Graph control UDF] - Easily create and show bar chart and line charts.
* [http://www.autoitscript.com/forum/index.php?showtopic=105682 GUICtrlCreateFinder] - Allows you to create a window finder control like the one seen in AutoIt Window Info.
* [http://www.autoitscript.com/forum/index.php?showtopic=111438 GUIPager] - Create and control native pager controls.
* [http://www.autoitscript.com/forum/index.php?showtopic=90598 Hotkey input control] - Hotkeys Input Control UDF Library (Non-native)
* [http://www.autoitscript.com/forum/index.php?showtopic=107965 GUIHotkey] - UDF for using native hotkey controls.
* [http://www.autoitscript.com/forum/topic/103904-info-bar-like-tickertape/page__view__findpost__p__735769 Marquees] - Make tickertape info bars
* [http://www.autoitscript.com/forum/topic/96464-colorpicker-udf/ Colorpicker] - Create a button for the user to select a color.
* [http://www.autoitscript.com/forum/topic/126958-guisyslink-udf/ Syslink] - Provides a convenient way to embed hypertext links in a window
* [http://www.autoitscript.com/forum/topic/74649-progressbar-with-gdiplus/ Progressbar with GDIplus] - You even can use full textured images

== Maths ==
* [http://www.autoitscript.com/forum/index.php?showtopic=83091 Primes UDF] - Many functions dealing with prime number generation and calculations.
* [http://www.autoitscript.com/forum/index.php?showtopic=83529 Big number UDF] - Make calculations with extremely large numbers that AutoIt normally is not able to support.
* [http://www.autoitscript.com/forum/index.php?showtopic=81189 Number base conversion] - From, to and between positive bases less than 63 (decimals supported)
* [http://www.autoitscript.com/forum/index.php?showtopic=106551 Decimal To fraction] - Converts any decimal number to a fraction. Example: 1.2 to 6/5
* [http://www.autoitscript.com/forum/index.php?showtopic=82722 Trigonometry math functions] - _ATan2(), _Cosh(), _Frexp(), _Hypot(), _Ldexp(), _Logb(), _Sinh(), _Tanh()
* [http://www.autoitscript.com/forum/index.php?showtopic=108803 Polynomials] - Functions for using polynomials.
* [http://www.autoitscript.com/forum/index.php?showtopic=117156 NumToWord] - Convert numerals to a human readable string.
* [http://www.autoitscript.com/forum/index.php?showtopic=98160 Root function] - Working out real roots of numbers.
* [http://www.autoitscript.com/forum/topic/102686-advanced-rounding/ Advanced rounding] - Support for different measures of accuracy and 8 ways to resolve tie breaks.

== Misc ==
* [http://www.autoitscript.com/forum/topic/90492-hotkey-au3/ Hotkey.au3] - Management of Hotkeys UDF, with several advantages over HotkeySet().
* [http://www.autoitscript.com/forum/topic/97826-animateau3-updated/ Animated tray icons] - Make animated tray icons easily.
* [http://www.autoitscript.com/forum/topic/101733-prevent-dotted-focus-lines-on-controls/ NoFocusLines] - Remove the dotted focus lines from buttons, sliders, radios and checkboxes which spoil the look of your GUI
* [http://www.autoitscript.com/forum/topic/114034-stringsize-m23/ StringSize] - Automatically size controls to fit the text you want to put in them
* [http://www.autoitscript.com/forum/topic/104150-json-udf-library-fully-rfc4627-compliant/ JSON] - RFC4627 compliant JSON encode/decode

User Defined Functions

2012-11-13T16:24:43Z

FlutterShy: /* GUI Additions */

This page is a listing of libraries of user defined functions. These libraries have been written to allow easy integration into your own script and are a very valuable resource for any programmer.

== Automation ==
* [http://www.autoitscript.com/forum/index.php?showtopic=87956 Java UDF] - Creates an access bridge between your application and a Java application. Allowing you to automate some Java applications.
* [http://www.autoitscript.com/forum/index.php?showtopic=86574 SAP] - SAP business management automation.
* [http://www.autoitscript.com/forum/index.php?showtopic=42776 PDFCreator] - Automation of PDFCreator allows you to create and manipulate PDF files.
* [http://www.autoitscript.com/forum/index.php?showtopic=91018 WiFi] - Low level control over your wireless LAN
* [http://www.autoitscript.com/forum/index.php?showtopic=106163 Active Directory] - Extensive library to control and manipulate the Windows active directory. Link to the [[Active_Directory_UDF_-_General|documentation]] pages.
* [http://www.autoitscript.com/forum/index.php?showtopic=28436 Windows Events] - Create your own Windows events.

===Browsers===
* Internet Explorer - Everything about Internet explorer can be automated with the IE library supplied with a standard AutoIt install.
* [http://www.autoitscript.com/forum/index.php?showtopic=95595 FireFox] - A little less support for automation than IE, but still very good.
* [http://www.autoitscript.com/forum/index.php?showtopic=61090 Opera] - The same as above for Opera. Automate the most common tasks in Opera with the Opera UDF.

===Microsoft Office Automation===
* [http://www.autoitscript.com/forum/index.php?showtopic=32144 Microsoft Office Access] - Automation of Access.
* [http://www.autoitscript.com/forum/index.php?showtopic=34302 Microsoft Office Excel] - Large automation library for Excel.
* [http://www.autoitscript.com/forum/topic/135312-excelchart-udf Microsoft Office Excel] - Creating charts using Excel.
* [http://www.autoitscript.com/forum/topic/126305-outlookex-udf/ Microsoft Office Outlook] - Extended Outlook UDF. Link to the [[OutlookEX_UDF_-_General|documentation]] pages.
* Microsoft Office Word UDF - A way to automate Office Word is included with AutoIt.

== Hardware ==
* [http://www.autoitscript.com/forum/index.php?showtopic=45842 Serial port (COM port)] - Requires my comMG.dll (included)

== Information gathering ==
* [http://www.autoitscript.com/forum/index.php?showtopic=29404 Computer information] - A general purpose library to get various details about a Windows machine.

== Databases and web connections ==
* FTP - A FTP library is now included with the AutoIt libraries.
* [http://www.autoitscript.com/forum/index.php?showtopic=17099 SQLite] - "SQLite is a library that implements a self-contained, embeddable, zero-configuration SQL database engine"
* [http://www.autoitscript.com/forum/index.php?showtopic=19848 XML DOM Wrapper] - Supports CRUD operations on XML. Including XSL and XPath.
* [http://www.autoitscript.com/forum/index.php?showtopic=20814 MySQL] - MySQL relational database management system UDF.

== Internet protocol suite ==
* [http://www.autoitscript.com/forum/topic/84133-winhttp-functions/ HTTP] - For creating GET and POST requests and submitting them with conforming standards.
* [http://www.autoitscript.com/forum/index.php?showtopic=22838 POP3] - POP3 library for retrieving email messages. Not compatible with Gmail because it uses SSL.
* [http://www.autoitscript.com/forum/index.php?showtopic=64051 POP3 SSL] - A POP3 library that's compatible with Gmail. It uses an external executable that must be supplied with your script.
* [http://www.autoitscript.com/forum/index.php?showtopic=43515 IRC] - A lightweight library for communicating with IRC servers.

== Data compression ==
* [http://www.autoitscript.com/forum/index.php?showtopic=116565 zip] - Create ZIP files and unpack ZIP files.
* [http://www.autoitscript.com/forum/index.php?showtopic=85094 7z, zip, gzip, bzip2, tar] - More extensive library than the one above. Uses a external DLL that must be provided with the script.

== Encryption and hash ==
* [http://www.autoitscript.com/forum/index.php?showtopic=76976 MD5,SHA1,CRC32,RC4,BASE64,XXTEA] - Several encryption and hash functions.
* [http://www.autoitscript.com/forum/index.php?showtopic=78745 AES Rijndael] - Very fast AES UDF. Support ECB/CBC/CFB/OFB block cipher mode.

== Media ==
* [http://www.autoitscript.com/forum/index.php?showtopic=94834 Simple DirectMedia Layer UDF] - Adds support for joysticks, CDs, 2D graphics, timers. See [http://www.libsdl.org/ SDL website] for more information.
* [http://www.autoitscript.com/forum/index.php?showtopic=95357 FreeImage library] - Various operations on images, such as rotate, resize, flip.
* [http://www.autoitscript.com/forum/index.php?showtopic=51054 Printer controller] - Print text in any font, size and colour at any position on the page, draw lines, curves, elipses, pies in any colour, and print images.

===Sound===
* [http://www.autoitscript.com/forum/index.php?showtopic=83481 BASS Function Library] - Sound and Music via wrappers for Bass, BassEnc, Bass FX, BassSFX, BassAsio and BassCd DLLs

===3D graphics===
* [http://www.autoitscript.com/forum/index.php?showtopic=70506 IrrLicht] - A 3D graphics engine suitable for creating games.
* [http://www.autoitscript.com/forum/index.php?showtopic=113881 au3Irrlicht2] - Another UDF bringing Irrlicht and au3 together. Historically some kind of a follower of the UDF above, technically with a complete different approach.

== GUI Additions ==
* [http://www.autoitscript.com/forum/index.php?showtopic=32494 XSkin] - A large library that allows skinning of your GUI and to apply custom skins.
* [http://www.autoitscript.com/forum/topic/132864-uskinlibraryau3-udf-skin-with-dll-free-no-ads-and-fully-functional/ Uskin] - A library that allows a user to skin their application GUI using the Windows ''.MSstyles'' files.
* [http://www.autoitscript.com/forum/index.php?showtopic=20967 Modern tray menu] - Allows the creation of modern, fancy GUI and tray menus with icons.
* [http://www.autoitscript.com/forum/index.php?showtopic=71811 SetOnEvent] - Provides an easy way for an event to call functions with parameters.
* [http://www.autoitscript.com/forum/topic/119505-guiframe-udf-melba23-version/ GUIFrame] - Divide a GUI into adjustable frames.
* [http://www.autoitscript.com/forum/topic/113723-scrollbars-made-easy/ Easy Scrollbars] - Easily create scrollable sections in your GUI
* [http://www.autoitscript.com/forum/index.php?showtopic=105582 GUICtrlOnChangeRegister] - Call a function when an edits content is changed.
* [http://www.autoitscript.com/forum/topic/96258-contexthelp-au3/ ContextHelp.au3] - Management of context help ([http://www.autoitscript.com/forum/topic/72152-contexthelp/ original])
* [http://www.autoitscript.com/forum/topic/117909-guiextender-new-version-171110/ GUIExtender] - Expand and contract sections of your GUI
* [http://www.autoitscript.com/forum/topic/109096-extended-message-box-new-version-3-dec-10/ ExtMsgBox] - A very customisable replacement for MsgBox
* [http://www.autoitscript.com/forum/topic/108445-how-to-make-toast/ Toast] - Small message GUIs which pop out of the Systray

=== Controls ===
* [http://www.autoitscript.com/forum/index.php?showtopic=79412 Graph control UDF] - Easily create and show bar chart and line charts.
* [http://www.autoitscript.com/forum/index.php?showtopic=105682 GUICtrlCreateFinder] - Allows you to create a window finder control like the one seen in AutoIt Window Info.
* [http://www.autoitscript.com/forum/index.php?showtopic=111438 GUIPager] - Create and control native pager controls.
* [http://www.autoitscript.com/forum/index.php?showtopic=90598 Hotkey input control] - Hotkeys Input Control UDF Library (Non-native)
* [http://www.autoitscript.com/forum/index.php?showtopic=107965 GUIHotkey] - UDF for using native hotkey controls.
* [http://www.autoitscript.com/forum/topic/103904-info-bar-like-tickertape/page__view__findpost__p__735769 Marquees] - Make tickertape info bars
* [http://www.autoitscript.com/forum/topic/96464-colorpicker-udf/ Colorpicker] - Create a button for the user to select a color.
* [http://www.autoitscript.com/forum/topic/126958-guisyslink-udf/ Syslink] - Provides a convenient way to embed hypertext links in a window
* [http://www.autoitscript.com/forum/topic/74649-progressbar-with-gdiplus/ Progressbar with GDIplus] - You even can use full textured images

== Maths ==
* [http://www.autoitscript.com/forum/index.php?showtopic=83091 Primes UDF] - Many functions dealing with prime number generation and calculations.
* [http://www.autoitscript.com/forum/index.php?showtopic=83529 Big number UDF] - Make calculations with extremely large numbers that AutoIt normally is not able to support.
* [http://www.autoitscript.com/forum/index.php?showtopic=81189 Number base conversion] - From, to and between positive bases less than 63 (decimals supported)
* [http://www.autoitscript.com/forum/index.php?showtopic=106551 Decimal To fraction] - Converts any decimal number to a fraction. Example: 1.2 to 6/5
* [http://www.autoitscript.com/forum/index.php?showtopic=82722 Trigonometry math functions] - _ATan2(), _Cosh(), _Frexp(), _Hypot(), _Ldexp(), _Logb(), _Sinh(), _Tanh()
* [http://www.autoitscript.com/forum/index.php?showtopic=108803 Polynomials] - Functions for using polynomials.
* [http://www.autoitscript.com/forum/index.php?showtopic=117156 NumToWord] - Convert numerals to a human readable string.
* [http://www.autoitscript.com/forum/index.php?showtopic=98160 Root function] - Working out real roots of numbers.
* [http://www.autoitscript.com/forum/topic/102686-advanced-rounding/ Advanced rounding] - Support for different measures of accuracy and 8 ways to resolve tie breaks.

== Misc ==
* [http://www.autoitscript.com/forum/topic/90492-hotkey-au3/ Hotkey.au3] - Management of Hotkeys UDF, with several advantages over HotkeySet().
* [http://www.autoitscript.com/forum/topic/97826-animateau3-updated/ Animated tray icons] - Make animated tray icons easily.
* [http://www.autoitscript.com/forum/topic/101733-prevent-dotted-focus-lines-on-controls/ NoFocusLines] - Remove the dotted focus lines from buttons, sliders, radios and checkboxes which spoil the look of your GUI
* [http://www.autoitscript.com/forum/topic/114034-stringsize-m23/ StringSize] - Automatically size controls to fit the text you want to put in them

Talk:User Defined Functions

2012-11-13T16:19:44Z

FlutterShy:

This page should really be a spin-off from: http://www.autoitscript.com/forum/index.php?showtopic=19370
[[User:Manadar|Manadar]] 13:12, 27 May 2009 (UTC)

== Migrated UDF List here ==

The old page can still be seen here: http://www.autoitscript.com/w/index.php?title=UDF_List&action=edit

== Changes to AutoIt wrappers ==

Currently the old wrappers forum thread by valuator is locked and is being migrated to the wiki (link?). I have just removed the outdated link for now.
--[[User:Mat|Mat]] 19:28, 24 September 2012 (BST)

== Internet protocol suite ==
* [http://www.autoitscript.com/forum/index.php?showtopic=64051 POP3 SSL] - A POP3 library that's compatible with Gmail. It uses an external executable that must be supplied with your script.

Are we sure we should link this topic in here?
I've looked through it and the ''user who made the topic never posted anything that works'', they just explained how their script worked and ''never actually provided code...''

SciTE4AutoIt3

2012-11-13T11:53:58Z

FlutterShy: /* SciTE4AutoIt3 */

=SciTE4AutoIt3=
SciTE4AutoIt3 is a specialist editor package based on the excellent [http://www.scintilla.org/SciTE.html SciTE] editor. SciTE has been set up to compile AutoIt scripts and has been extended with a multitude of Lua scripts. SciTE4AutoIt3 may be downloaded here: [http://www.autoitscript.com/site/autoit-script-editor/ SciTE4AutoIt3]

SciTE4AutoIt3 provides:
* Syntax highlighting
* Calltips (also known as IntelliSense)
* Code AutoComplete
* Auto Indentation
* AutoIt Script help integration
* SciTE help integration
* Abbreviations
* Editing macros
* Debugging support
* Tools for AutoIt scripting
* A toolbar that enables easy access to an array of community created tools
* Various other features

Keep in mind that SciTE4AutoIt3 is not an official package. Direct any bug reports or feature requests to the AutoIt3 forum and not the bug tracker.

=Syntax Highlighting=
[[File:Syntax_Highlight.png|457px|thumb|right|A demonstration of syntax highlighting using the default theme.]]
SciTE4AutoIt3 comes with a customized AutoIt3 lexer which enables syntax highlighting. Syntax highlighting enables the colorization of various code elements such as variables, strings, operators, comments, etc. This allows one to differentiate the various code elements at a glance without having to specifically read everything. To load a custom theme a user may press [Ctrl] + [1] to bring up ''SciTEConfig''. The options are located under the ''Color Settings'' tab.

Some options that are available for customization include:
* White Space
* Comment Line
* Comment Block
* Number
* Function
* Keyword
* Macro
* String

=Quick Tips=
To access the helpfile the user may press [Alt] + [F1].
To quickly access help information on a specific function/statement, simply click/highlight the function/statement in question and press the [F1] key to bring up the help file on the relevant page.

For SciTE related help, use the key combination [Ctrl] + [F1] to bring up a help file detailing SciTE related help documentation. ''It's recommended that you read it.''

For anyone not familiar with SciTE, here are a few tips and tricks to help you easily modify the installation to suit your needs. For any "truly" advanced info, you should visit the [[http://www.scintilla.org/SciTEDoc.html SciTE home page]].

With the information below, you will be doing some minor editing to SciTE's configuration files.
It is imperative that you know the hierarchy of SciTE's configuration files. The main files we will be dealing with here are listed below.

Remember there are four properties files used:

# ''SciTE.properties''
# ''SciTEDirectory.properties''
# ''SciTEUser.properties''
# ''SciTEGlobal.properties''

<table border="1">
<tr><td>SciTE.properties</td><td>Local properties file which may be present in the same directory as the file being edited. This file overrides any other properties files settings below. This file is user created.</td></tr>
<tr><td>SciTEDirectory.properties</td><td>Directory properties file which may be present in the same or in a parent directory as the file being edited. This file overrides all properties setting of the files below, but not the local properties settings aka ''SciTE.properties''. This file is user created.</td></tr>
<tr><td>SciTEUser.properties</td><td>User properties file, this files settings override only the Global properties settings aka ''SciTEGlobal.properties''. This file is found under the current logged on users profile directory.</td></tr>
<tr><td>SciTEGlobal.properties</td><td>All settings in this file can be overridden by any of the above files. Typically you shouldn't mess with this file and use any of the above methods to implement a setting change. This file can be found in SciTE's installation directory.</td></tr>
</table>

''If you have any trouble finding any of the previously mentioned files then I recommend that you do ''not'' continue further.''

==Inline Errors==
[[File:InlineError.JPG‎‎|234px|thumb|right|Intentional error prone code used to display the "Inline Error" feature.]]
In the latest version of SciTE, there exists a new feature called "Inline Errors", some users find them annoying. Inline Error marks are error messages that will appear in the source code within the Scintilla window. While helpful, some users prefer to disable this feature often for unknown reasons.
You can quickly disable/enable them using the '''SciTEUser.properties'''.

Open the SciTE user properties file in a text editor and add the following code to the file.

To disable Inline Errors, add the following.
<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=0
</syntaxhighlight>
To enable Inline Errors, add the following.
<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=1
</syntaxhighlight>

==Selection Highlighting==
In the latest SciTE4AutoIt3, there is a new feature which highlights other instances of the currently highlighted word or string. Due to the colors, sometimes it's hard to tell the selection apart.

If you'd like, you can do either of two things using the ''SciTEUser.properties''.
# Disable it
# Change the color scheme

To disable it
<syntaxhighlight lang="properties">
highlight.current.word=0
</syntaxhighlight>
To re-enable it, just delete it and save.

To change the color scheme, add the following to your SciTEUser.properties file.
<syntaxhighlight lang="properties">
highlight.current.word.colour=#000040
selection.alpha=50
selection.back=#F025A8
</syntaxhighlight>

The user should try adjusting the ''#COLOR'' values to come to a preferred color.

==More Language Highlighting Options==
In the SciTEUser.properties file, add the following code.

<syntaxhighlight lang="properties">
# Language Highlighting Options
menu.language=\
#FreeBasic|bas||\
Text|txt|Shift+F11|\
#Ada|ads||\
AutoIt3|au3|Shift+F12|\
#Apache Confi&g|conf||\
#Assembler|asm||\
#ASN.1|asn1||\
#Avenue|ave||\
#Baan|bc||\
#&Batch|bat||\
#Bullant|ant||\
#&C / C++|cpp||\
#CMake|cmake||\
#C&#|cs||\
#COBOL|cob||\
#Csound|orc||\
#CSS|css||\
#D|d||\
#&Difference|diff||\
#&Eiffel|e||\
#Erlang|erl||\
#&Errorlist|err||\
#FlagShip|prg||\
#&Fortran|f90||\
#&Fortran|f90||\
#Gap|g||\
#Haskell|hs||\
#H&ypertext|html|$(keyHTML)|\
#&InnoSetup|iss||\
#&Java|java||\
#Java&Script|js||\
#&Kix|kix||\
#Lisp|lisp||\
#Lot|lot||\
#Lout|lt||\
#Lu&a|lua||\
#Matlab|m.matlab||\
#&Makefile|mak||\
#MetaPost|mp||\
#MMIXAL|mms||\
#Modula-3|m3||\
#&nnCron crontab|tab||\
#NSIS|nsis||\
#Objective Caml|ml||\
#Octave|m.octave||\
#Opal|impl||\
#Pascal|pas||\
#Pe&rl|pl||\
#P&HP|php||\
#P&LSQL|spec||\
#P&ostScript|ps||\
#P&OV-Ray SDL|pov||\
#PowerShell|ps1||\
#PowerPro|powerpro||\
#&Properties|properties||\
#Pytho&n|py||\
#R|R||\
#Reso&urce|rc||\
#Ruby|rb||\
#Shell|sh||\
#S&QL|sql||\
#Specman|e||\
#&TCL|tcl||\
#TeX|tex||\
#&txt2tags|t2t||\
#&VB|vb||\
#VBScr&ipt|vbs||\
#Verilog|v||\
#VHDL|vhd||\
#&XML|xml||\
#&YAML|yaml||
</syntaxhighlight>

For whatever language you wish to have an option appear under the ''Language'' menu option, uncomment the language. Say you want to SciTE to give you the option to highlight batch script code, change the following string in the above list from

<syntaxhighlight lang="properties">
#&Batch|bat||\
</syntaxhighlight>
to
<syntaxhighlight lang="properties">
&Batch|bat||\
</syntaxhighlight>
Restart SciTE and if done correctly, the option should be present! Do this for any language listed in the above example list.

In the case that you uncommented a language and you notice that it's not being highlighted correctly, then we will have to edit some things in the '''SciTEGlobal.properties''' file.

Open the '''SciTEGlobal.properties''' file in a text editor and find the section
<syntaxhighlight lang="properties">
# import properties\all the language specific properties files
</syntaxhighlight>
Below that section there will be a few strings that look like
<syntaxhighlight lang="properties">
#import properties\[syntax]
</syntaxhighlight>
Uncomment the syntax related property you wish to have support for.

Say you wanted support for ruby, just locate the one that says ''ruby'' where ''[syntax]'' is written.

==Colors in the Output Pane==
When you use SciTE as your AutoIt script editor it is a simple matter to get color in the output pane while you test run your code. Try this:
<syntaxhighlight lang="AutoIt">
ConsoleWrite("This is plain text" & @LF)
ConsoleWrite(">Make it have some color" & @LF)
ConsoleWrite("+Make it have some other color" & @LF)
ConsoleWrite("-Make it have some other color" & @LF)
ConsoleWrite("!Make it have some other color" & @LF)
</syntaxhighlight>

==Debugging Code Easily==
This is one of my (@uten's) favorites.
<syntaxhighlight lang="autoit">
dbg("This is a test")
dbg("Jump to this line")
dbg("just by clicking my output line")

Func dbg($msg, $error = @error, $extended = @extended, $erl = @ScriptLineNumber)
ConsoleWrite("(" & $erl & ") : = (" & $error & ")(" & $extended & ") " & $msg & @LF)
If $error <> 0 Then SetError($error, $extended, $error)
Return $error
EndFunc ;==>dbg
</syntaxhighlight>

=AutoIt3Wrapper=
AutoIt3Wrapper directives allow much greater and in depth control of your resulting programs. Some of these can be very useful under different circumstances.

==Stripping Excess Code==
For instance, if you have several includes, then you can often strip thousands of lines from your program using obfuscator:

#AutoIt3Wrapper_Run_Obfuscator=y
#Obfuscator_Parameters=/sf /sv /om /cs=0 /cn=0

On a medium sized script, results are often like this:

>Running Obfuscator (1.0.27.0) from:C:\Program Files\AutoIt3\SciTE cmdline:
- Iteration 1 Strip Functions result: Output 2580 lines and stripped 6741 lines
- Iteration 2 Strip Variables result: Output 1585 lines and stripped 950 lines
- Iteration 3 Strip Variables result: Output 1566 lines and stripped 19 lines
- Iteration 4 Start the actual Obfuscation.
+> Source 26190 lines 1447980 Characters.
+> Stripped 7710 Func/Var lines and 16862 comment lines, Total 1373871 Characters.
+> Saved 93% lines 94% Characters.
+> Obfuscator v1.0.27.0 finished obfuscating 1566 lines, created:C:\MyScript_Obfuscated.au3

==Using ResHacker==
ResHacker is a very important programming tool for extracting and adding resources into executables. It has a very simple command line interface that allows it to be used easily using the "Run_After" directive. Adding a picture to an executable could be done like this:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, MyPicture.bmp, BITMAP, RESOURCENAME, 0

*NB:* Reshacker.exe ''must'' be copied into the script directory for this to work!

If you then want to use the resources in your code, there is an excellent [http://www.autoitscript.com/forum/index.php?showtopic=51103 Resources UDF] which will allow you to access the resources from within the exe.

==Adding Original Source Code==
When using the above tip on stripping excess code, the new source is not readable. As a result, using the standard directive for saving the source:

#AutoIt3Wrapper_Res_SaveSource=y

Would add the obfuscated code to the exe, which is not the desired result. The solution is to add it in manually. This code does not require any editing, so you can just copy and paste it in:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, %scriptfile%.au3, RCDATA, SOURCE, 0

==Creating a Version Directory==
When compiling, it is very possible that you want to go back to a previous version. If so, then it is neat to have a directory which will store all previous builds, without the need for you to manually copy and paste every time! Make sure you add these directives in last (after adding resources) as they might not be included in the copied result.

#AutoIt3Wrapper_Run_After=md "%scriptdir%\Versions\%fileversion%"
#AutoIt3Wrapper_Run_After=copy "%in%" "%scriptdir%\Versions\%fileversion%\%scriptfile%%fileversion%.au3"
#AutoIt3Wrapper_Run_After=copy "%out%" "%scriptdir%\Versions\%fileversion%\%scriptfile%%fileversion%.exe"

==Running the exe on Build==
Often you are building as a test, so to have to open up Windows Explorer to get the exe is a pain, furthermore, unless you have a program to do it (or it's a console program) you will not be able to read console info such as the debug messages you put in the exe. The solution is simple:

#AutoIt3Wrapper_Run_After="%out%"

This will run the program and read the console output to the SciTE debug frame.

==Extended Reshacker Info==
ResHacker doesn't always return with a return code (rc) of not 0 if it fails, to get that info you need to read the ResHacker.log file that is created. This is also pretty simple to do:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, MyPicture.bmp, BITMAP, RESOURCENAME, 0
#AutoIt3Wrapper_Run_After=TYPE ResHacker.log

The new output now looks like this:

>Running:ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
>ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0 Ended rc:0
>Running:TYPE ResHacker.log
[19 Jan 2010, 21:26:22]
ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
Added: BITMAP,RESOURCENAME,0

Commands completed
>TYPE ResHacker.log Ended rc:0

And an example of it showing an error:

>ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0 Ended rc:0
>Running:TYPE ResHacker.log
[19 Jan 2010, 21:32:10]
ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
Error: "MyPicture.bmp" does not exist
>TYPE ResHacker.log Ended rc:0

As you can see, Reshacker on its own returns rc: 0, usually indicating no error. This would have gone completely unnoticed except for the log file, which shows the error and an explanation.

==Other Run_After and Run_Before Commands==
You can use any commands you like in the Run_After and Run_Before directives. Examples such as "TYPE" have been shown above.

For a more complete list the following website is very useful: [http://ss64.com/nt An A-Z Index of the Windows CMD Line]

=Other Wiki Pages=
[[Adding_utilities_to_the_SciTE_Tools_menu|Adding Utilities to the SciTE Tools Menu]]

[[Adding_UDFs_to_AutoIt_and_SciTE|Adding UDFs to AutoIt and SciTE]]

SciTE4AutoIt3

2012-11-12T17:59:58Z

FlutterShy: /* Debugging Code Easily */

=SciTE4AutoIt3=
SciTE4AutoIt3 is a specialist editor package based around the excellent [http://www.scintilla.org/SciTE.html SciTE] editor. SciTE has been set up to compile AutoIt scripts. SciTE has been extended with a multitude of lua scripts. SciTE4AutoIt3 may be downloaded here: [http://www.autoitscript.com/site/autoit-script-editor/ SciTE4AutoIt3]

SciTE4AutoIt3 comes with an array of tools and advanced options including a configuration program named ''SciTEConfig'' under the ''Tools'' menu. With ''SciTEConfig'' a user may change the color scheme of SciTE's syntax highlighting, change the default au3 script file double-click action, create a script backup policy and determine what tools are shown in SciTE's ''Tools'' menu. Also available are calltips, abbreviations, autocompletion, code folding and quick access to the help file.

Keep in mind that SciTE4AutoIt3 is not an official package. Direct any bug reports or feature requests to the AutoIt3 forum and not the bug tracker.

=Syntax Highlighting=
[[File:Syntax_Highlight.png|457px|thumb|right|A demonstration of syntax highlighting using the default theme.]]
SciTE4AutoIt3 comes with a customized AutoIt3 lexer which enables syntax highlighting. Syntax highlighting enables the colorization of various code elements such as variables, strings, operators, comments, etc. This allows one to differentiate the various code elements at a glance without having to specifically read everything. To load a custom theme a user may press [Ctrl] + [1] to bring up ''SciTEConfig''. The options are located under the ''Color Settings'' tab.

Some options that are available for customization include:
* White Space
* Comment Line
* Comment Block
* Number
* Function
* Keyword
* Macro
* String

=Quick Tips=
To access the helpfile the user may press [Alt] + [F1].
To quickly access help information on a specific function/statement, simply click/highlight the function/statement in question and press the [F1] key to bring up the help file on the relevant page.

For SciTE related help, use the key combination [Ctrl] + [F1] to bring up a help file detailing SciTE related help documentation. ''It's recommended that you read it.''

For anyone not familiar with SciTE, here are a few tips and tricks to help you easily modify the installation to suit your needs. For any "truly" advanced info, you should visit the [[http://www.scintilla.org/SciTEDoc.html SciTE home page]].

With the information below, you will be doing some minor editing to SciTE's configuration files.
It is imperative that you know the hierarchy of SciTE's configuration files. The main files we will be dealing with here are listed below.

Remember there are four properties files used:

# ''SciTE.properties''
# ''SciTEDirectory.properties''
# ''SciTEUser.properties''
# ''SciTEGlobal.properties''

<table border="1">
<tr><td>SciTE.properties</td><td>Local properties file which may be present in the same directory as the file being edited. This file overrides any other properties files settings below. This file is user created.</td></tr>
<tr><td>SciTEDirectory.properties</td><td>Directory properties file which may be present in the same or in a parent directory as the file being edited. This file overrides all properties setting of the files below, but not the local properties settings aka ''SciTE.properties''. This file is user created.</td></tr>
<tr><td>SciTEUser.properties</td><td>User properties file, this files settings override only the Global properties settings aka ''SciTEGlobal.properties''. This file is found under the current logged on users profile directory.</td></tr>
<tr><td>SciTEGlobal.properties</td><td>All settings in this file can be overridden by any of the above files. Typically you shouldn't mess with this file and use any of the above methods to implement a setting change. This file can be found in SciTE's installation directory.</td></tr>
</table>

''If you have any trouble finding any of the previously mentioned files then I recommend that you do ''not'' continue further.''

==Inline Errors==
[[File:InlineError.JPG‎‎|234px|thumb|right|Intentional error prone code used to display the "Inline Error" feature.]]
In the latest version of SciTE, there exists a new feature called "Inline Errors", some users find them annoying. Inline Error marks are error messages that will appear in the source code within the Scintilla window. While helpful, some users prefer to disable this feature often for unknown reasons.
You can quickly disable/enable them using the '''SciTEUser.properties'''.

Open the SciTE user properties file in a text editor and add the following code to the file.

To disable Inline Errors, add the following.
<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=0
</syntaxhighlight>
To enable Inline Errors, add the following.
<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=1
</syntaxhighlight>

==Selection Highlighting==
In the latest SciTE4AutoIt3, there is a new feature which highlights other instances of the currently highlighted word or string. Due to the colors, sometimes it's hard to tell the selection apart.

If you'd like, you can do either of two things using the ''SciTEUser.properties''.
# Disable it
# Change the color scheme

To disable it
<syntaxhighlight lang="properties">
highlight.current.word=0
</syntaxhighlight>
To re-enable it, just delete it and save.

To change the color scheme, add the following to your SciTEUser.properties file.
<syntaxhighlight lang="properties">
highlight.current.word.colour=#000040
selection.alpha=50
selection.back=#F025A8
</syntaxhighlight>

The user should try adjusting the ''#COLOR'' values to come to a preferred color.

==More Language Highlighting Options==
In the SciTEUser.properties file, add the following code.

<syntaxhighlight lang="properties">
# Language Highlighting Options
menu.language=\
#FreeBasic|bas||\
Text|txt|Shift+F11|\
#Ada|ads||\
AutoIt3|au3|Shift+F12|\
#Apache Confi&g|conf||\
#Assembler|asm||\
#ASN.1|asn1||\
#Avenue|ave||\
#Baan|bc||\
#&Batch|bat||\
#Bullant|ant||\
#&C / C++|cpp||\
#CMake|cmake||\
#C&#|cs||\
#COBOL|cob||\
#Csound|orc||\
#CSS|css||\
#D|d||\
#&Difference|diff||\
#&Eiffel|e||\
#Erlang|erl||\
#&Errorlist|err||\
#FlagShip|prg||\
#&Fortran|f90||\
#&Fortran|f90||\
#Gap|g||\
#Haskell|hs||\
#H&ypertext|html|$(keyHTML)|\
#&InnoSetup|iss||\
#&Java|java||\
#Java&Script|js||\
#&Kix|kix||\
#Lisp|lisp||\
#Lot|lot||\
#Lout|lt||\
#Lu&a|lua||\
#Matlab|m.matlab||\
#&Makefile|mak||\
#MetaPost|mp||\
#MMIXAL|mms||\
#Modula-3|m3||\
#&nnCron crontab|tab||\
#NSIS|nsis||\
#Objective Caml|ml||\
#Octave|m.octave||\
#Opal|impl||\
#Pascal|pas||\
#Pe&rl|pl||\
#P&HP|php||\
#P&LSQL|spec||\
#P&ostScript|ps||\
#P&OV-Ray SDL|pov||\
#PowerShell|ps1||\
#PowerPro|powerpro||\
#&Properties|properties||\
#Pytho&n|py||\
#R|R||\
#Reso&urce|rc||\
#Ruby|rb||\
#Shell|sh||\
#S&QL|sql||\
#Specman|e||\
#&TCL|tcl||\
#TeX|tex||\
#&txt2tags|t2t||\
#&VB|vb||\
#VBScr&ipt|vbs||\
#Verilog|v||\
#VHDL|vhd||\
#&XML|xml||\
#&YAML|yaml||
</syntaxhighlight>

For whatever language you wish to have an option appear under the ''Language'' menu option, uncomment the language. Say you want to SciTE to give you the option to highlight batch script code, change the following string in the above list from

<syntaxhighlight lang="properties">
#&Batch|bat||\
</syntaxhighlight>
to
<syntaxhighlight lang="properties">
&Batch|bat||\
</syntaxhighlight>
Restart SciTE and if done correctly, the option should be present! Do this for any language listed in the above example list.

In the case that you uncommented a language and you notice that it's not being highlighted correctly, then we will have to edit some things in the '''SciTEGlobal.properties''' file.

Open the '''SciTEGlobal.properties''' file in a text editor and find the section
<syntaxhighlight lang="properties">
# import properties\all the language specific properties files
</syntaxhighlight>
Below that section there will be a few strings that look like
<syntaxhighlight lang="properties">
#import properties\[syntax]
</syntaxhighlight>
Uncomment the syntax related property you wish to have support for.

Say you wanted support for ruby, just locate the one that says ''ruby'' where ''[syntax]'' is written.

==Colors in the Output Pane==
When you use SciTE as your AutoIt script editor it is a simple matter to get color in the output pane while you test run your code. Try this:
<syntaxhighlight lang="AutoIt">
ConsoleWrite("This is plain text" & @LF)
ConsoleWrite(">Make it have some color" & @LF)
ConsoleWrite("+Make it have some other color" & @LF)
ConsoleWrite("-Make it have some other color" & @LF)
ConsoleWrite("!Make it have some other color" & @LF)
</syntaxhighlight>

==Debugging Code Easily==
This is one of my (@uten's) favorites.
<syntaxhighlight lang="autoit">
dbg("This is a test")
dbg("Jump to this line")
dbg("just by clicking my output line")

Func dbg($msg, $error = @error, $extended = @extended, $erl = @ScriptLineNumber)
ConsoleWrite("(" & $erl & ") : = (" & $error & ")(" & $extended & ") " & $msg & @LF)
If $error <> 0 Then SetError($error, $extended, $error)
Return $error
EndFunc ;==>dbg
</syntaxhighlight>

=AutoIt3Wrapper=
AutoIt3Wrapper directives allow much greater and in depth control of your resulting programs. Some of these can be very useful under different circumstances.

==Stripping Excess Code==
For instance, if you have several includes, then you can often strip thousands of lines from your program using obfuscator:

#AutoIt3Wrapper_Run_Obfuscator=y
#Obfuscator_Parameters=/sf /sv /om /cs=0 /cn=0

On a medium sized script, results are often like this:

>Running Obfuscator (1.0.27.0) from:C:\Program Files\AutoIt3\SciTE cmdline:
- Iteration 1 Strip Functions result: Output 2580 lines and stripped 6741 lines
- Iteration 2 Strip Variables result: Output 1585 lines and stripped 950 lines
- Iteration 3 Strip Variables result: Output 1566 lines and stripped 19 lines
- Iteration 4 Start the actual Obfuscation.
+> Source 26190 lines 1447980 Characters.
+> Stripped 7710 Func/Var lines and 16862 comment lines, Total 1373871 Characters.
+> Saved 93% lines 94% Characters.
+> Obfuscator v1.0.27.0 finished obfuscating 1566 lines, created:C:\MyScript_Obfuscated.au3

==Using ResHacker==
ResHacker is a very important programming tool for extracting and adding resources into executables. It has a very simple command line interface that allows it to be used easily using the "Run_After" directive. Adding a picture to an executable could be done like this:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, MyPicture.bmp, BITMAP, RESOURCENAME, 0

*NB:* Reshacker.exe ''must'' be copied into the script directory for this to work!

If you then want to use the resources in your code, there is an excellent [http://www.autoitscript.com/forum/index.php?showtopic=51103 Resources UDF] which will allow you to access the resources from within the exe.

==Adding Original Source Code==
When using the above tip on stripping excess code, the new source is not readable. As a result, using the standard directive for saving the source:

#AutoIt3Wrapper_Res_SaveSource=y

Would add the obfuscated code to the exe, which is not the desired result. The solution is to add it in manually. This code does not require any editing, so you can just copy and paste it in:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, %scriptfile%.au3, RCDATA, SOURCE, 0

==Creating a Version Directory==
When compiling, it is very possible that you want to go back to a previous version. If so, then it is neat to have a directory which will store all previous builds, without the need for you to manually copy and paste every time! Make sure you add these directives in last (after adding resources) as they might not be included in the copied result.

#AutoIt3Wrapper_Run_After=md "%scriptdir%\Versions\%fileversion%"
#AutoIt3Wrapper_Run_After=copy "%in%" "%scriptdir%\Versions\%fileversion%\%scriptfile%%fileversion%.au3"
#AutoIt3Wrapper_Run_After=copy "%out%" "%scriptdir%\Versions\%fileversion%\%scriptfile%%fileversion%.exe"

==Running the exe on Build==
Often you are building as a test, so to have to open up Windows Explorer to get the exe is a pain, furthermore, unless you have a program to do it (or it's a console program) you will not be able to read console info such as the debug messages you put in the exe. The solution is simple:

#AutoIt3Wrapper_Run_After="%out%"

This will run the program and read the console output to the SciTE debug frame.

==Extended Reshacker Info==
ResHacker doesn't always return with a return code (rc) of not 0 if it fails, to get that info you need to read the ResHacker.log file that is created. This is also pretty simple to do:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, MyPicture.bmp, BITMAP, RESOURCENAME, 0
#AutoIt3Wrapper_Run_After=TYPE ResHacker.log

The new output now looks like this:

>Running:ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
>ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0 Ended rc:0
>Running:TYPE ResHacker.log
[19 Jan 2010, 21:26:22]
ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
Added: BITMAP,RESOURCENAME,0

Commands completed
>TYPE ResHacker.log Ended rc:0

And an example of it showing an error:

>ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0 Ended rc:0
>Running:TYPE ResHacker.log
[19 Jan 2010, 21:32:10]
ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
Error: "MyPicture.bmp" does not exist
>TYPE ResHacker.log Ended rc:0

As you can see, Reshacker on its own returns rc: 0, usually indicating no error. This would have gone completely unnoticed except for the log file, which shows the error and an explanation.

==Other Run_After and Run_Before Commands==
You can use any commands you like in the Run_After and Run_Before directives. Examples such as "TYPE" have been shown above.

For a more complete list the following website is very useful: [http://ss64.com/nt An A-Z Index of the Windows CMD Line]

=Other Wiki Pages=
[[Adding_utilities_to_the_SciTE_Tools_menu|Adding Utilities to the SciTE Tools Menu]]

[[Adding_UDFs_to_AutoIt_and_SciTE|Adding UDFs to AutoIt and SciTE]]

SciTE4AutoIt3

2012-11-12T17:59:40Z

FlutterShy: /* Colors in the Output Pane */

=SciTE4AutoIt3=
SciTE4AutoIt3 is a specialist editor package based around the excellent [http://www.scintilla.org/SciTE.html SciTE] editor. SciTE has been set up to compile AutoIt scripts. SciTE has been extended with a multitude of lua scripts. SciTE4AutoIt3 may be downloaded here: [http://www.autoitscript.com/site/autoit-script-editor/ SciTE4AutoIt3]

SciTE4AutoIt3 comes with an array of tools and advanced options including a configuration program named ''SciTEConfig'' under the ''Tools'' menu. With ''SciTEConfig'' a user may change the color scheme of SciTE's syntax highlighting, change the default au3 script file double-click action, create a script backup policy and determine what tools are shown in SciTE's ''Tools'' menu. Also available are calltips, abbreviations, autocompletion, code folding and quick access to the help file.

Keep in mind that SciTE4AutoIt3 is not an official package. Direct any bug reports or feature requests to the AutoIt3 forum and not the bug tracker.

=Syntax Highlighting=
[[File:Syntax_Highlight.png|457px|thumb|right|A demonstration of syntax highlighting using the default theme.]]
SciTE4AutoIt3 comes with a customized AutoIt3 lexer which enables syntax highlighting. Syntax highlighting enables the colorization of various code elements such as variables, strings, operators, comments, etc. This allows one to differentiate the various code elements at a glance without having to specifically read everything. To load a custom theme a user may press [Ctrl] + [1] to bring up ''SciTEConfig''. The options are located under the ''Color Settings'' tab.

Some options that are available for customization include:
* White Space
* Comment Line
* Comment Block
* Number
* Function
* Keyword
* Macro
* String

=Quick Tips=
To access the helpfile the user may press [Alt] + [F1].
To quickly access help information on a specific function/statement, simply click/highlight the function/statement in question and press the [F1] key to bring up the help file on the relevant page.

For SciTE related help, use the key combination [Ctrl] + [F1] to bring up a help file detailing SciTE related help documentation. ''It's recommended that you read it.''

For anyone not familiar with SciTE, here are a few tips and tricks to help you easily modify the installation to suit your needs. For any "truly" advanced info, you should visit the [[http://www.scintilla.org/SciTEDoc.html SciTE home page]].

With the information below, you will be doing some minor editing to SciTE's configuration files.
It is imperative that you know the hierarchy of SciTE's configuration files. The main files we will be dealing with here are listed below.

Remember there are four properties files used:

# ''SciTE.properties''
# ''SciTEDirectory.properties''
# ''SciTEUser.properties''
# ''SciTEGlobal.properties''

<table border="1">
<tr><td>SciTE.properties</td><td>Local properties file which may be present in the same directory as the file being edited. This file overrides any other properties files settings below. This file is user created.</td></tr>
<tr><td>SciTEDirectory.properties</td><td>Directory properties file which may be present in the same or in a parent directory as the file being edited. This file overrides all properties setting of the files below, but not the local properties settings aka ''SciTE.properties''. This file is user created.</td></tr>
<tr><td>SciTEUser.properties</td><td>User properties file, this files settings override only the Global properties settings aka ''SciTEGlobal.properties''. This file is found under the current logged on users profile directory.</td></tr>
<tr><td>SciTEGlobal.properties</td><td>All settings in this file can be overridden by any of the above files. Typically you shouldn't mess with this file and use any of the above methods to implement a setting change. This file can be found in SciTE's installation directory.</td></tr>
</table>

''If you have any trouble finding any of the previously mentioned files then I recommend that you do ''not'' continue further.''

==Inline Errors==
[[File:InlineError.JPG‎‎|234px|thumb|right|Intentional error prone code used to display the "Inline Error" feature.]]
In the latest version of SciTE, there exists a new feature called "Inline Errors", some users find them annoying. Inline Error marks are error messages that will appear in the source code within the Scintilla window. While helpful, some users prefer to disable this feature often for unknown reasons.
You can quickly disable/enable them using the '''SciTEUser.properties'''.

Open the SciTE user properties file in a text editor and add the following code to the file.

To disable Inline Errors, add the following.
<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=0
</syntaxhighlight>
To enable Inline Errors, add the following.
<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=1
</syntaxhighlight>

==Selection Highlighting==
In the latest SciTE4AutoIt3, there is a new feature which highlights other instances of the currently highlighted word or string. Due to the colors, sometimes it's hard to tell the selection apart.

If you'd like, you can do either of two things using the ''SciTEUser.properties''.
# Disable it
# Change the color scheme

To disable it
<syntaxhighlight lang="properties">
highlight.current.word=0
</syntaxhighlight>
To re-enable it, just delete it and save.

To change the color scheme, add the following to your SciTEUser.properties file.
<syntaxhighlight lang="properties">
highlight.current.word.colour=#000040
selection.alpha=50
selection.back=#F025A8
</syntaxhighlight>

The user should try adjusting the ''#COLOR'' values to come to a preferred color.

==More Language Highlighting Options==
In the SciTEUser.properties file, add the following code.

<syntaxhighlight lang="properties">
# Language Highlighting Options
menu.language=\
#FreeBasic|bas||\
Text|txt|Shift+F11|\
#Ada|ads||\
AutoIt3|au3|Shift+F12|\
#Apache Confi&g|conf||\
#Assembler|asm||\
#ASN.1|asn1||\
#Avenue|ave||\
#Baan|bc||\
#&Batch|bat||\
#Bullant|ant||\
#&C / C++|cpp||\
#CMake|cmake||\
#C&#|cs||\
#COBOL|cob||\
#Csound|orc||\
#CSS|css||\
#D|d||\
#&Difference|diff||\
#&Eiffel|e||\
#Erlang|erl||\
#&Errorlist|err||\
#FlagShip|prg||\
#&Fortran|f90||\
#&Fortran|f90||\
#Gap|g||\
#Haskell|hs||\
#H&ypertext|html|$(keyHTML)|\
#&InnoSetup|iss||\
#&Java|java||\
#Java&Script|js||\
#&Kix|kix||\
#Lisp|lisp||\
#Lot|lot||\
#Lout|lt||\
#Lu&a|lua||\
#Matlab|m.matlab||\
#&Makefile|mak||\
#MetaPost|mp||\
#MMIXAL|mms||\
#Modula-3|m3||\
#&nnCron crontab|tab||\
#NSIS|nsis||\
#Objective Caml|ml||\
#Octave|m.octave||\
#Opal|impl||\
#Pascal|pas||\
#Pe&rl|pl||\
#P&HP|php||\
#P&LSQL|spec||\
#P&ostScript|ps||\
#P&OV-Ray SDL|pov||\
#PowerShell|ps1||\
#PowerPro|powerpro||\
#&Properties|properties||\
#Pytho&n|py||\
#R|R||\
#Reso&urce|rc||\
#Ruby|rb||\
#Shell|sh||\
#S&QL|sql||\
#Specman|e||\
#&TCL|tcl||\
#TeX|tex||\
#&txt2tags|t2t||\
#&VB|vb||\
#VBScr&ipt|vbs||\
#Verilog|v||\
#VHDL|vhd||\
#&XML|xml||\
#&YAML|yaml||
</syntaxhighlight>

For whatever language you wish to have an option appear under the ''Language'' menu option, uncomment the language. Say you want to SciTE to give you the option to highlight batch script code, change the following string in the above list from

<syntaxhighlight lang="properties">
#&Batch|bat||\
</syntaxhighlight>
to
<syntaxhighlight lang="properties">
&Batch|bat||\
</syntaxhighlight>
Restart SciTE and if done correctly, the option should be present! Do this for any language listed in the above example list.

In the case that you uncommented a language and you notice that it's not being highlighted correctly, then we will have to edit some things in the '''SciTEGlobal.properties''' file.

Open the '''SciTEGlobal.properties''' file in a text editor and find the section
<syntaxhighlight lang="properties">
# import properties\all the language specific properties files
</syntaxhighlight>
Below that section there will be a few strings that look like
<syntaxhighlight lang="properties">
#import properties\[syntax]
</syntaxhighlight>
Uncomment the syntax related property you wish to have support for.

Say you wanted support for ruby, just locate the one that says ''ruby'' where ''[syntax]'' is written.

==Colors in the Output Pane==
When you use SciTE as your AutoIt script editor it is a simple matter to get color in the output pane while you test run your code. Try this:
<syntaxhighlight lang="AutoIt">
ConsoleWrite("This is plain text" & @LF)
ConsoleWrite(">Make it have some color" & @LF)
ConsoleWrite("+Make it have some other color" & @LF)
ConsoleWrite("-Make it have some other color" & @LF)
ConsoleWrite("!Make it have some other color" & @LF)
</syntaxhighlight>

==Debugging Code Easily==
This is one of my (@uten's) favorites.
<syntaxhighlight lang="properties">
dbg("This is a test")
dbg("Jump to this line")
dbg("just by clicking my output line")

Func dbg($msg, $error = @error, $extended = @extended, $erl = @ScriptLineNumber)
ConsoleWrite("(" & $erl & ") : = (" & $error & ")(" & $extended & ") " & $msg & @LF)
If $error <> 0 Then SetError($error, $extended, $error)
Return $error
EndFunc ;==>dbg
</syntaxhighlight>

=AutoIt3Wrapper=
AutoIt3Wrapper directives allow much greater and in depth control of your resulting programs. Some of these can be very useful under different circumstances.

==Stripping Excess Code==
For instance, if you have several includes, then you can often strip thousands of lines from your program using obfuscator:

#AutoIt3Wrapper_Run_Obfuscator=y
#Obfuscator_Parameters=/sf /sv /om /cs=0 /cn=0

On a medium sized script, results are often like this:

>Running Obfuscator (1.0.27.0) from:C:\Program Files\AutoIt3\SciTE cmdline:
- Iteration 1 Strip Functions result: Output 2580 lines and stripped 6741 lines
- Iteration 2 Strip Variables result: Output 1585 lines and stripped 950 lines
- Iteration 3 Strip Variables result: Output 1566 lines and stripped 19 lines
- Iteration 4 Start the actual Obfuscation.
+> Source 26190 lines 1447980 Characters.
+> Stripped 7710 Func/Var lines and 16862 comment lines, Total 1373871 Characters.
+> Saved 93% lines 94% Characters.
+> Obfuscator v1.0.27.0 finished obfuscating 1566 lines, created:C:\MyScript_Obfuscated.au3

==Using ResHacker==
ResHacker is a very important programming tool for extracting and adding resources into executables. It has a very simple command line interface that allows it to be used easily using the "Run_After" directive. Adding a picture to an executable could be done like this:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, MyPicture.bmp, BITMAP, RESOURCENAME, 0

*NB:* Reshacker.exe ''must'' be copied into the script directory for this to work!

If you then want to use the resources in your code, there is an excellent [http://www.autoitscript.com/forum/index.php?showtopic=51103 Resources UDF] which will allow you to access the resources from within the exe.

==Adding Original Source Code==
When using the above tip on stripping excess code, the new source is not readable. As a result, using the standard directive for saving the source:

#AutoIt3Wrapper_Res_SaveSource=y

Would add the obfuscated code to the exe, which is not the desired result. The solution is to add it in manually. This code does not require any editing, so you can just copy and paste it in:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, %scriptfile%.au3, RCDATA, SOURCE, 0

==Creating a Version Directory==
When compiling, it is very possible that you want to go back to a previous version. If so, then it is neat to have a directory which will store all previous builds, without the need for you to manually copy and paste every time! Make sure you add these directives in last (after adding resources) as they might not be included in the copied result.

#AutoIt3Wrapper_Run_After=md "%scriptdir%\Versions\%fileversion%"
#AutoIt3Wrapper_Run_After=copy "%in%" "%scriptdir%\Versions\%fileversion%\%scriptfile%%fileversion%.au3"
#AutoIt3Wrapper_Run_After=copy "%out%" "%scriptdir%\Versions\%fileversion%\%scriptfile%%fileversion%.exe"

==Running the exe on Build==
Often you are building as a test, so to have to open up Windows Explorer to get the exe is a pain, furthermore, unless you have a program to do it (or it's a console program) you will not be able to read console info such as the debug messages you put in the exe. The solution is simple:

#AutoIt3Wrapper_Run_After="%out%"

This will run the program and read the console output to the SciTE debug frame.

==Extended Reshacker Info==
ResHacker doesn't always return with a return code (rc) of not 0 if it fails, to get that info you need to read the ResHacker.log file that is created. This is also pretty simple to do:

#AutoIt3Wrapper_Run_After=ResHacker.exe -add %out%, %out%, MyPicture.bmp, BITMAP, RESOURCENAME, 0
#AutoIt3Wrapper_Run_After=TYPE ResHacker.log

The new output now looks like this:

>Running:ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
>ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0 Ended rc:0
>Running:TYPE ResHacker.log
[19 Jan 2010, 21:26:22]
ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
Added: BITMAP,RESOURCENAME,0

Commands completed
>TYPE ResHacker.log Ended rc:0

And an example of it showing an error:

>ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0 Ended rc:0
>Running:TYPE ResHacker.log
[19 Jan 2010, 21:32:10]
ResHacker.exe -add C:\MyScript.exe, C:\MyScript.exe, MyPicture.bmp, BITMAP, RESOURCENAME, 0
Error: "MyPicture.bmp" does not exist
>TYPE ResHacker.log Ended rc:0

As you can see, Reshacker on its own returns rc: 0, usually indicating no error. This would have gone completely unnoticed except for the log file, which shows the error and an explanation.

==Other Run_After and Run_Before Commands==
You can use any commands you like in the Run_After and Run_Before directives. Examples such as "TYPE" have been shown above.

For a more complete list the following website is very useful: [http://ss64.com/nt An A-Z Index of the Windows CMD Line]

=Other Wiki Pages=
[[Adding_utilities_to_the_SciTE_Tools_menu|Adding Utilities to the SciTE Tools Menu]]

[[Adding_UDFs_to_AutoIt_and_SciTE|Adding UDFs to AutoIt and SciTE]]

Tutorial Core Language

2012-11-10T03:28:49Z

FlutterShy: /* Defining */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
;A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Local $var
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF(); define a simple user defined function
; Your customized code will go in here
; then you can call this function and have your code executed or "run"
EndFunc
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
MyUDFAcceptingArguments("Some string")

Func MyUDFAcceptingArguments($arg1, $arg2 = "Default Data")
MsgBox(64, $arg1, $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
Global $sReturn = _MyUDF_ReturnResults()
ConsoleWrite($sReturn & @CR); Display what was returned, we add @CR or @LF to drop down a line break, remove to see what happens

Func _MyUDF_ReturnResults()
Local $sTest = "Some information"; this will be returned
; The Return statement will tell the function to return the information in the $Is variable
Return $sTest
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-10T03:26:46Z

FlutterShy: /* Returning data */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
;A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Local $var
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF(); define a simple user defined function
;Generate a random capital alphabetical letter
Return Chr(Random(65, 90, 1))
EndFunc
ConsoleWrite(MySimplestUDF() & @LF); call the function
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
MyUDFAcceptingArguments("Some string")

Func MyUDFAcceptingArguments($arg1, $arg2 = "Default Data")
MsgBox(64, $arg1, $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
Global $sReturn = _MyUDF_ReturnResults()
ConsoleWrite($sReturn & @CR); Display what was returned, we add @CR or @LF to drop down a line break, remove to see what happens

Func _MyUDF_ReturnResults()
Local $sTest = "Some information"; this will be returned
; The Return statement will tell the function to return the information in the $Is variable
Return $sTest
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-10T03:19:45Z

FlutterShy: /* Passing data */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
;A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Local $var
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF(); define a simple user defined function
;Generate a random capital alphabetical letter
Return Chr(Random(65, 90, 1))
EndFunc
ConsoleWrite(MySimplestUDF() & @LF); call the function
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
MyUDFAcceptingArguments("Some string")

Func MyUDFAcceptingArguments($arg1, $arg2 = "Default Data")
MsgBox(64, $arg1, $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
ConsoleWrite("1) " & _MyUDF_ReturnResults(10) & @LF)
ConsoleWrite("2) " & _MyUDF_ReturnResults(10.5) & @LF)
ConsoleWrite("3) " & _MyUDF_ReturnResults("10") & @LF)
ConsoleWrite("4) " & _MyUDF_ReturnResults(True) & @LF)
ConsoleWrite("5) " & _MyUDF_ReturnResults(Default) & @LF)
ConsoleWrite("6) " & _MyUDF_ReturnResults(Binary("AutoIt")) & @LF)
ConsoleWrite("7) " & _MyUDF_ReturnResults(GUICreate("")) & @LF)
ConsoleWrite("8) " & _MyUDF_ReturnResults(ObjCreate("shell.application")) & @LF)
ConsoleWrite("9) " & _MyUDF_ReturnResults(DllStructCreate("int")) & @LF)
ConsoleWrite("10) " & _MyUDF_ReturnResults(DllStructGetPtr(DllStructCreate("char"))) & @LF)
ConsoleWrite("11) " & _MyUDF_ReturnResults(StringSplit("1.2.3", ".")) & @LF)

Func _MyUDF_ReturnResults($arg1)
Local $Is
If IsNumber($arg1) Then $Is &= "NUMBER "
If IsFloat($arg1) Then $Is &= "FLOAT "
If IsString($arg1) Then $Is &= "STRING "
If IsInt($arg1) Then $Is &= "INTEGER "
If IsBinary($arg1) Then $Is &= "BINARY "
If IsArray($arg1) Then $Is &= "ARRAY "
If IsPtr($arg1) Then $Is &= "POINTER "
If IsDllStruct($arg1) Then $Is &= "DLL_STRUCTURE "
If IsHWnd($arg1) Then $Is &= "WINDOW_HANDLE "
If IsBool($arg1) Then $Is &= "BOOL "
If IsKeyword($arg1) Then $Is &= "KEYWORD "
If IsObj($arg1) Then $Is &= "OBJECT "
Return $Is
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-10T03:14:18Z

FlutterShy:

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
;A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Local $var
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF(); define a simple user defined function
;Generate a random capital alphabetical letter
Return Chr(Random(65, 90, 1))
EndFunc
ConsoleWrite(MySimplestUDF() & @LF); call the function
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
ConsoleWrite("1) " & _MyUDF_ReturnResults(10) & @LF)
ConsoleWrite("2) " & _MyUDF_ReturnResults(10.5) & @LF)
ConsoleWrite("3) " & _MyUDF_ReturnResults("10") & @LF)
ConsoleWrite("4) " & _MyUDF_ReturnResults(True) & @LF)
ConsoleWrite("5) " & _MyUDF_ReturnResults(Default) & @LF)
ConsoleWrite("6) " & _MyUDF_ReturnResults(Binary("AutoIt")) & @LF)
ConsoleWrite("7) " & _MyUDF_ReturnResults(GUICreate("")) & @LF)
ConsoleWrite("8) " & _MyUDF_ReturnResults(ObjCreate("shell.application")) & @LF)
ConsoleWrite("9) " & _MyUDF_ReturnResults(DllStructCreate("int")) & @LF)
ConsoleWrite("10) " & _MyUDF_ReturnResults(DllStructGetPtr(DllStructCreate("char"))) & @LF)
ConsoleWrite("11) " & _MyUDF_ReturnResults(StringSplit("1.2.3", ".")) & @LF)

Func _MyUDF_ReturnResults($arg1)
Local $Is
If IsNumber($arg1) Then $Is &= "NUMBER "
If IsFloat($arg1) Then $Is &= "FLOAT "
If IsString($arg1) Then $Is &= "STRING "
If IsInt($arg1) Then $Is &= "INTEGER "
If IsBinary($arg1) Then $Is &= "BINARY "
If IsArray($arg1) Then $Is &= "ARRAY "
If IsPtr($arg1) Then $Is &= "POINTER "
If IsDllStruct($arg1) Then $Is &= "DLL_STRUCTURE "
If IsHWnd($arg1) Then $Is &= "WINDOW_HANDLE "
If IsBool($arg1) Then $Is &= "BOOL "
If IsKeyword($arg1) Then $Is &= "KEYWORD "
If IsObj($arg1) Then $Is &= "OBJECT "
Return $Is
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Arrays

2012-11-10T00:10:32Z

FlutterShy: /* Comparing Arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
$iMax = UBound($arr); get array size
ConsoleWrite("Items in the array: " & $iMax & @LF)
For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array stored in the element. You have to go through a variable to get access to the embedded array which may make your code overly complicated and difficult to debug.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

That said, here is an example.
<syntaxhighlight lang="autoit">Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:
<syntaxhighlight lang="autoit">
$NewArray = $OldArray
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array[1] = "Element 1"
</syntaxhighlight>
Or
<syntaxhighlight lang="autoit">
$Content = $Array[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
Local $Array1[3] = [1, 2, 3]
Local $Array2[3] = [1, 2, 3]
Local $Array3[4] = [1, 2, 3, 4]

If $Array1 = $Array2 then ConsoleWrite("1.) $Array1 is equal to $Array2! which might be correct in some sense." & @LF); while they cintain the same data, the comparison does not work.
If $Array1 == $Array3 Then ConsoleWrite("2.) $Array1 is equal to $Array3! which is incorrect." & @LF); even though they're different in size, it's incorrectly determined that they're equal.
</syntaxhighlight>

I have the impression that such comparisons compare the memory address of the arrays instead of the array elements values. And the addresses are always different for different arrays.
<br/>
You have to instead, compare all elements one after the other. It might be a good idea to first compare array sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-10T00:04:11Z

FlutterShy: /* Comparing Arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
$iMax = UBound($arr); get array size
ConsoleWrite("Items in the array: " & $iMax & @LF)
For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array stored in the element. You have to go through a variable to get access to the embedded array which may make your code overly complicated and difficult to debug.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

That said, here is an example.
<syntaxhighlight lang="autoit">Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:
<syntaxhighlight lang="autoit">
$NewArray = $OldArray
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array[1] = "Element 1"
</syntaxhighlight>
Or
<syntaxhighlight lang="autoit">
$Content = $Array[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
Local $Array1[3] = [1, 2, 3]
Local $Array2[3] = [1, 2, 3]

If $Array1 = $Array2 then; incorrect array comparison, never do this!
ConsoleWrite("+>Array is equal!" & @LF)
Else
ConsoleWrite("!>Array is not equal!" & @LF)
EndIf
</syntaxhighlight>

I have the impression that such comparisons compare the memory address of the arrays instead of the array elements values. And the addresses are always different for different arrays.
<br/>
You have to instead, compare all elements one after the other. It might be a good idea to first compare array sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-09T08:37:27Z

FlutterShy: /* Determine array size with UBound */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
$iMax = UBound($arr); get array size
ConsoleWrite("Items in the array: " & $iMax & @LF)
For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array stored in the element. You have to go through a variable to get access to the embedded array which may make your code overly complicated and difficult to debug.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

That said, here is an example.
<syntaxhighlight lang="autoit">Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:
<syntaxhighlight lang="autoit">
$NewArray = $OldArray
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array[1] = "Element 1"
</syntaxhighlight>
Or
<syntaxhighlight lang="autoit">
$Content = $Array[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
Local $Array1[3] = [1, 2, 3]
Local $Array2[3] = [1, 2, 3]

If $Array1 = $Array2 then
ConsoleWrite("+>Array is equal!" & @LF)
Else
ConsoleWrite("!>Array is not equal!" & @LF)
EndIf
</syntaxhighlight>

I have the impression that such comparisons compare the memory address of the arrays instead of the array elements values. And the addresses are always different for different arrays.
<br/>
You have to instead, compare all elements one after the other. It might be a good idea to first compare array sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

AutoIt Team

2012-11-09T08:28:16Z

FlutterShy: Created page with "==Administrators== * <span style="color: #FF0000;font-weight:bold;"><abbr title="There is only one Admin, and that is Jon">Jon</abbr></span> - [http://www.autoitscript.com/for..."

==Administrators==
* <span style="color: #FF0000;font-weight:bold;"><abbr title="There is only one Admin, and that is Jon">Jon</abbr></span> - [http://www.autoitscript.com/forum/user/1-jon/ Profile]

==Developers==
* <span style="color: #008000;font-weight:bold;"><abbr title="Current most active developer">Trancexx</abbr></span> - [http://www.autoitscript.com/forum/user/33569-trancexx/ Profile]
* <span style="color: #008000;font-weight:bold;"><abbr title="Retired/No longer active">Valik</abbr></span> - [http://www.autoitscript.com/forum/user/39-valik/ Profile]
* <span style="color: #008000;font-weight:bold;"><abbr title="SciTE4AutoIt3 Developer">Jos</abbr></span> - [http://www.autoitscript.com/forum/user/19-jos/ Profile]
* <span style="color: #008000;font-weight:bold;">jpm</span> - [http://www.autoitscript.com/forum/user/8-jpm/ Profile]
* <span style="color: #008000;font-weight:bold;">GaryFrost</span> - [http://www.autoitscript.com/forum/user/1967-garyfrost/ Profile]
* <span style="color: #008000;font-weight:bold;">Nutster</span> - [http://www.autoitscript.com/forum/user/88-nutster/ Profile]
* <span style="color: #008000;font-weight:bold;">tylo</span> - [http://www.autoitscript.com/forum/user/149-tylo/ Profile]
* <span style="color: #008000;font-weight:bold;">Holger</span> - [http://www.autoitscript.com/forum/user/1133-holger/ Profile]
* <span style="color: #008000;font-weight:bold;">DaveF</span> - [http://www.autoitscript.com/forum/user/1944-davef/ Profile]
* <span style="color: #008000;font-weight:bold;">SvenP</span> - [http://www.autoitscript.com/forum/user/4276-svenp/ Profile]

==Moderators==
* <span style="color: #FF0000;font-weight:bold;"><abbr title="Most notorious moderator">Melba23</abbr></span> - [http://www.autoitscript.com/forum/user/38576-melba23/ Profile]
* <span style="color: #FF0000;font-weight:bold;">big_daddy</span> - [http://www.autoitscript.com/forum/user/8730-big-daddy/ Profile]
* <span style="color: #FF0000;font-weight:bold;">SmOke_N</span> - [http://www.autoitscript.com/forum/user/4813-smoke-n/ Profile]

If I missed anyone, feel free to add them.

User:FlutterShy

2012-11-09T07:46:42Z

FlutterShy: Blanked the page

SciTE4AutoIt3

2012-11-09T07:42:54Z

FlutterShy:

SciTE4AutoIt3 is a specialist editor package based around the excellent [http://www.scintilla.org/SciTE.html SciTE] editor. The editor has been set up to compile AutoIt scripts. SciTE has been extended with a multitude of lua scripts. SciTE4AutoIt3 may be downloaded here: [http://www.autoitscript.com/site/autoit-script-editor/ SciTE4AutoIt3]

SciTE4AutoIt3 comes with an array of tools and advanced options including a configuration program named "SciTE Config" under the "tools" menu. With ''SciTE Config'' a user may change the color scheme of SciTE's syntax highlighting, change the default Au3 script file double-click action, create a script backup policy and determine what tools are shown in SciTE's tools menu. Also available are calltips, abbreviations, and quick access to the helpfiles.

==SciTE Quick Tips==

To access the helpfile the user may press [Alt] + [F1].
To quickly access help information on a specific function/statement, simply click/highlight the function/statement in question and press the [F1] key to bring up the help file on a relevant page.

For SciTE related help, use the key combination [Ctrl] + [F1] to bring up a help file detailing SciTE related help documentation. ''It's recommended you read it.''

For anyone not familiar with SciTE, here are a few tips and tricks to help you easily modify the installation to suit your needs. For any "truly" advanced info, you should visit the [[http://www.scintilla.org/SciTEDoc.html SciTE home page]].

With the information below, you will be doing some minor editing to SciTEs configuration files.
It is imperative that you know the hierarchy of SciTEs configuration files. The main files we will be dealing with here are listed below.

Remember there are four properties files used:

# ''SciTE.properties''
# ''SciTEDirectory.properties''
# ''SciTEUser.properties''
# ''SciTEGlobal.properties''

<table border="1">
<tr><td>SciTE.properties</td><td>Local properties file which may be present in the same directory as the file being edited. This file overrides any other properties files settings below. This file is user created.</td></tr>
<tr><td>SciTEDirectory.properties</td><td>Directory properties file which may be present in the same or in a parent directory as the file being edited. This file overrides all properties setting of the files below, but not the local properties settings aka ''SciTE.properties''. This file is user created.</td></tr>
<tr><td>SciTEUser.properties</td><td>User properties file, this files settings override only the Global properties settings aka ''SciTEGlobal.properties''. This file is found under the current logged on users profile directory.</td></tr>
<tr><td>SciTEGlobal.properties</td><td>All settings in this file can be overridden by any of the above files. Typically you shouldn't mess with this file and use any of the above methods to implement a setting change. This file can be found in SciTE's installation directory.</td></tr>
</table>

''If you're having any trouble finding any of the previously mentioned files, I recommend you NOT continue with this information...''

===Inline Errors===
[[File:InlineError.JPG‎‎|200px|thumb|right|Intentional error prone code used to display the "Inline Error" feature.]]
In the latest version of SciTE, there exists a new feature called "Inline Errors", some users find them annoying. Inline Error marks are error messages that will appear in the source code within the Scintilla window. While helpful, some users prefer to disable this feature often for unknown reasons.
You can quickly disable/enable them using the '''SciTEUser.properties'''.

Open the SciTE user properties file in a text editor and add the following code to the file.

To disable Inline Errors, add the following.
<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=0
</syntaxhighlight>
To enable Inline Errors, add the following.

<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=1
</syntaxhighlight>

===Selection Highlighting===
In the latest SciTEforAutoIt3, there is a new feature which highlights other instances of the highlighted word or string. Due to the colors, sometimes it's hard to tell the selection apart.

If you'd like, you can do either of two things using the ''SciTEUser.properties''.
# Disable it
# Change the color scheme

To disable it
<syntaxhighlight lang="properties">
highlight.current.word=0
</syntaxhighlight>
To re-enable it, just delete it and save.

To change the color scheme, add the following to your SciTEUser properties file.
<syntaxhighlight lang="properties">
highlight.current.word.colour=#000040
selection.alpha=50
selection.back=#F025A8
</syntaxhighlight>

Try adjusting the ''#COLOR'' values to get an effect you'd prefer.

===More Language Highlighting Options===

In the SciTEUser.properties file, add the following code.

<syntaxhighlight lang="properties">
# Language Highlighting Options
menu.language=\
#FreeBasic|bas||\
Text|txt|Shift+F11|\
#Ada|ads||\
AutoIt3|au3|Shift+F12|\
#Apache Confi&g|conf||\
#Assembler|asm||\
#ASN.1|asn1||\
#Avenue|ave||\
#Baan|bc||\
#&Batch|bat||\
#Bullant|ant||\
#&C / C++|cpp||\
#CMake|cmake||\
#C&#|cs||\
#COBOL|cob||\
#Csound|orc||\
#CSS|css||\
#D|d||\
#&Difference|diff||\
#&Eiffel|e||\
#Erlang|erl||\
#&Errorlist|err||\
#FlagShip|prg||\
#&Fortran|f90||\
#&Fortran|f90||\
#Gap|g||\
#Haskell|hs||\
#H&ypertext|html|$(keyHTML)|\
#&InnoSetup|iss||\
#&Java|java||\
#Java&Script|js||\
#&Kix|kix||\
#Lisp|lisp||\
#Lot|lot||\
#Lout|lt||\
#Lu&a|lua||\
#Matlab|m.matlab||\
#&Makefile|mak||\
#MetaPost|mp||\
#MMIXAL|mms||\
#Modula-3|m3||\
#&nnCron crontab|tab||\
#NSIS|nsis||\
#Objective Caml|ml||\
#Octave|m.octave||\
#Opal|impl||\
#Pascal|pas||\
#Pe&rl|pl||\
#P&HP|php||\
#P&LSQL|spec||\
#P&ostScript|ps||\
#P&OV-Ray SDL|pov||\
#PowerShell|ps1||\
#PowerPro|powerpro||\
#&Properties|properties||\
#Pytho&n|py||\
#R|R||\
#Reso&urce|rc||\
#Ruby|rb||\
#Shell|sh||\
#S&QL|sql||\
#Specman|e||\
#&TCL|tcl||\
#TeX|tex||\
#&txt2tags|t2t||\
#&VB|vb||\
#VBScr&ipt|vbs||\
#Verilog|v||\
#VHDL|vhd||\
#&XML|xml||\
#&YAML|yaml||
</syntaxhighlight>

For whatever language you wish to have an option appear under the ''Language'' menu option, uncomment the language.

Say you want to SciTE to give you the option to highlight batch script code, change the following string in the above list from

<syntaxhighlight lang="properties">
#&Batch|bat||\
</syntaxhighlight>
to
<syntaxhighlight lang="properties">
&Batch|bat||\
</syntaxhighlight>
Restart SciTE and if done correctly, the option should be present!
Do this for any language listed in the above example list.

In the case that you uncommented a language and you notice that it's not being highlighted correctly, then we will have to edit some things in the '''SciTEGlobal.properties''' file.

Open the '''SciTEGlobal.properties''' file in a text editor and find the section

<syntaxhighlight lang="properties">
# import properties\all the language specific properties files
</syntaxhighlight>
Below that section there will be a few strings that look like
<syntaxhighlight lang="properties">
#import properties\[syntax]

</syntaxhighlight>
Uncomment the syntax related property you wish to have support for.

Say you wanted support for ruby, just locate the one that says ''ruby'' where ''[syntax]'' is written.

Tutorial Core Language

2012-11-09T06:51:18Z

FlutterShy: /* Returning data */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
;A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Local $var
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF(); define a simple user defined function
;Generate a random capital alphabetical letter
Return Chr(Random(65, 90, 1))
EndFunc
ConsoleWrite(MySimplestUDF() & @LF); call the function
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
ConsoleWrite("1) " & _MyUDF_ReturnResults(10) & @LF)
ConsoleWrite("2) " & _MyUDF_ReturnResults(10.5) & @LF)
ConsoleWrite("3) " & _MyUDF_ReturnResults("10") & @LF)
ConsoleWrite("4) " & _MyUDF_ReturnResults(True) & @LF)
ConsoleWrite("5) " & _MyUDF_ReturnResults(Default) & @LF)
ConsoleWrite("6) " & _MyUDF_ReturnResults(Binary("AutoIt")) & @LF)
ConsoleWrite("7) " & _MyUDF_ReturnResults(GUICreate("")) & @LF)
ConsoleWrite("8) " & _MyUDF_ReturnResults(ObjCreate("shell.application")) & @LF)
ConsoleWrite("9) " & _MyUDF_ReturnResults(DllStructCreate("int")) & @LF)
ConsoleWrite("10) " & _MyUDF_ReturnResults(DllStructGetPtr(DllStructCreate("char"))) & @LF)
ConsoleWrite("11) " & _MyUDF_ReturnResults(StringSplit("1.2.3", ".")) & @LF)

Func _MyUDF_ReturnResults($arg1)
Local $Is
If IsNumber($arg1) Then $Is &= "NUMBER "
If IsFloat($arg1) Then $Is &= "FLOAT "
If IsString($arg1) Then $Is &= "STRING "
If IsInt($arg1) Then $Is &= "INTEGER "
If IsBinary($arg1) Then $Is &= "BINARY "
If IsArray($arg1) Then $Is &= "ARRAY "
If IsPtr($arg1) Then $Is &= "POINTER "
If IsDllStruct($arg1) Then $Is &= "DLL_STRUCTURE "
If IsHWnd($arg1) Then $Is &= "WINDOW_HANDLE "
If IsBool($arg1) Then $Is &= "BOOL "
If IsKeyword($arg1) Then $Is &= "KEYWORD "
If IsObj($arg1) Then $Is &= "OBJECT "
Return $Is
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-09T06:50:29Z

FlutterShy: /* Returning data */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
;A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Local $var
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF(); define a simple user defined function
;Generate a random capital alphabetical letter
Return Chr(Random(65, 90, 1))
EndFunc
ConsoleWrite(MySimplestUDF() & @LF); call the function
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
ConsoleWrite("1) " & _MyUDF_ReturnResults(10) & @LF)
ConsoleWrite("2) " & _MyUDF_ReturnResults(10.5) & @LF)
ConsoleWrite("3) " & _MyUDF_ReturnResults("10") & @LF)
ConsoleWrite("4) " & _MyUDF_ReturnResults(True) & @LF)
ConsoleWrite("5) " & _MyUDF_ReturnResults(Default) & @LF)
ConsoleWrite("6) " & _MyUDF_ReturnResults(Binary("AutoIt")) & @LF)
ConsoleWrite("7) " & _MyUDF_ReturnResults(GUICreate("")) & @LF)
ConsoleWrite("8) " & _MyUDF_ReturnResults(ObjCreate("shell.application")) & @LF)
ConsoleWrite("9) " & _MyUDF_ReturnResults(DllStructCreate("int")) & @LF)
ConsoleWrite("10) " & _MyUDF_ReturnResults(DllStructGetPtr(DllStructCreate("char"))) & @LF)
ConsoleWrite("11) " & _MyUDF_ReturnResults(StringSplit("1.2.3", ".")) & @LF)

Func _MyUDF_ReturnResults($arg1)
Local $Is
If IsNumber($arg1) Then $Is &= "NUMBER "
If IsFloat($arg1) Then $Is &= "FLOAT "
If IsString($arg1) Then $Is &= "STRING "
If IsInt($arg1) Then $Is &= "INTEGER "
If IsBinary($arg1) Then $Is &= "BINARY "
If IsArray($arg1) Then $Is &= "ARRAY "
If IsPtr($arg1) Then $Is &= "POINTER "
If IsDllStruct($arg1) Then $Is &= "DLL_STRUCTURE "
If IsHWnd($arg1) Then $Is &= "WINDOW_HANDLE "
If IsBool($arg1) Then $Is = "BOOL "
If IsKeyword($arg1) Then $Is &= "KEYWORD "
If IsObj($arg1) Then $Is &= "OBJECT "
Return $Is
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-09T05:57:30Z

FlutterShy: /* Defining */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
;A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Local $var
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF(); define a simple user defined function
;Generate a random capital alphabetical letter
Return Chr(Random(65, 90, 1))
EndFunc
ConsoleWrite(MySimplestUDF() & @LF); call the function
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
Func MyUDFReturningResults($arg1, ByRef $arg2)
Local $ret = 1
;Changing $arg2 is a way of returning data
If IsNumeric($arg2) Then
$arg2 = 2*$arg2
Else
$arg2 &= @CRLF & $arg2
EndIf
Return $ret
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-09T05:50:19Z

FlutterShy: /* Do ... Until */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
;A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Local $var
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF()
;This does nothing at the moment
EndFunc
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
Func MyUDFReturningResults($arg1, ByRef $arg2)
Local $ret = 1
;Changing $arg2 is a way of returning data
If IsNumeric($arg2) Then
$arg2 = 2*$arg2
Else
$arg2 &= @CRLF & $arg2
EndIf
Return $ret
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-09T05:45:55Z

FlutterShy: /* While ... WEnd */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
Local $var
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF()
;This does nothing at the moment
EndFunc
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
Func MyUDFReturningResults($arg1, ByRef $arg2)
Local $ret = 1
;Changing $arg2 is a way of returning data
If IsNumeric($arg2) Then
$arg2 = 2*$arg2
Else
$arg2 &= @CRLF & $arg2
EndIf
Return $ret
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-09T05:44:57Z

FlutterShy: /* For ... Next */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
For $i = 1 to 10 Step 2; in a For..Next loop, the For variable is automatically declared locally
ConsoleWrite($i & @LF)
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF()
;This does nothing at the moment
EndFunc
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
Func MyUDFReturningResults($arg1, ByRef $arg2)
Local $ret = 1
;Changing $arg2 is a way of returning data
If IsNumeric($arg2) Then
$arg2 = 2*$arg2
Else
$arg2 &= @CRLF & $arg2
EndIf
Return $ret
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

User:FlutterShy

2012-11-09T05:18:36Z

FlutterShy:

SciTE4AutoIt3 is a specialist editor package based around the excellent [http://www.scintilla.org/SciTE.html SciTE] editor. The editor has been set up to compile AutoIt scripts. SciTE has been extended with a multitude of lua scripts. SciTE4AutoIt3 may be downloaded here: [http://www.autoitscript.com/site/autoit-script-editor/ SciTE4AutoIt3]

SciTE4AutoIt3 comes with an array of tools and advanced options including a configuration program named "SciTE Config" under the "tools" menu. With SciTEConfig a user may change the color scheme of SciTE's syntax highlighting, change the default Au3 script file double-click action, create a script backup policy and determine what tools are shown in SciTE's tools menu. Also available are calltips, abbreviations, and quick access to the helpfile. To access the helpfile the user may press Alt + F1. To quickly access help information on a specific function/statement, simply click/highlight the function/statement in question and press the F1 key to bring up the help file on a relevant page.

==Advanced==

For AutoIt related SciTE help, use the key combination [CTRL] + [F1] to bring up a help file detailing SciTE related help documentation.

For anyone not familiar with SciTE, here are a few tips and tricks to help you easily modify the installation to suit your needs. For any "truly" advanced info, you should visit the [[http://www.scintilla.org/SciTEDoc.html SciTE home page]].

With the information below, you will be doing some minor editing to SciTEs configuration files.
It is imperative that you know the hierarchy of SciTEs configuration files. The three main files we will be dealing with here are listed below.

* '''SciTEGlobal.properties''', located in SciTE's installation directory, usually under '''[Drive]:\Program Files\AutoIt3\SciTE\'''.
* '''SciTEUser.properties''', located in current users profile or "user profile directory".
* '''SciTE.properties''', user created file.

<table border="1">
<tr><td>SciTEGlobal.properties</td><td>This is the config file you should not mess with. This file has most of the stock setting shipped with SciTE4AutoIt3.</td></tr>
<tr><td>SciTEUser.properties</td><td>This is the recommended config file to use. All settings added to this file will override and existing settings in the "SciTEGlobal.properties" file.</td></tr>
<tr><td>SciTE.properties</td><td>This is a local project file, all settings in this file only apply to scripts inside this files directory and sub-directories.</td></tr>
</table>

''If you're having any trouble finding any of the previously mentioned file, I would recommend you NOT continue with this information...''

===Inline Errors===
[[File:InlineError.JPG‎‎|200px|thumb|right|Intentional error prone code used to display the "Inline Error" feature.]]
In the latest version of SciTE, there exists a new feature called "Inline Errors", some users find them annoying. Inline Error marks are error messages that will appear in the source code within the Scintilla window. While helpful, some users prefer to disable this feature often for unknown reasons.
You can quickly disable/enable them using the '''SciTEUser.properties'''.

Open the SciTE user properties file in a text editor and add the following code to the file.

To disable Inline Errors, add the following.
<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=0
</syntaxhighlight>
To enable Inline Errors, add the following.

<syntaxhighlight lang="properties">
# Display settings for inline errors on the source
error.inline=1
</syntaxhighlight>

===More Language Highlighting Option===

In the SciTEUser.properties file, add the following code.

<syntaxhighlight lang="properties">
# Language Highlighting Options
menu.language=\
#FreeBasic|bas||\
Text|txt|Shift+F11|\
#Ada|ads||\
AutoIt3|au3|Shift+F12|\
#Apache Confi&g|conf||\
#Assembler|asm||\
#ASN.1|asn1||\
#Avenue|ave||\
#Baan|bc||\
#&Batch|bat||\
#Bullant|ant||\
#&C / C++|cpp||\
#CMake|cmake||\
#C&#|cs||\
#COBOL|cob||\
#Csound|orc||\
#CSS|css||\
#D|d||\
#&Difference|diff||\
#&Eiffel|e||\
#Erlang|erl||\
#&Errorlist|err||\
#FlagShip|prg||\
#&Fortran|f90||\
#&Fortran|f90||\
#Gap|g||\
#Haskell|hs||\
#H&ypertext|html|$(keyHTML)|\
#&InnoSetup|iss||\
#&Java|java||\
#Java&Script|js||\
#&Kix|kix||\
#Lisp|lisp||\
#Lot|lot||\
#Lout|lt||\
#Lu&a|lua||\
#Matlab|m.matlab||\
#&Makefile|mak||\
#MetaPost|mp||\
#MMIXAL|mms||\
#Modula-3|m3||\
#&nnCron crontab|tab||\
#NSIS|nsis||\
#Objective Caml|ml||\
#Octave|m.octave||\
#Opal|impl||\
#Pascal|pas||\
#Pe&rl|pl||\
#P&HP|php||\
#P&LSQL|spec||\
#P&ostScript|ps||\
#P&OV-Ray SDL|pov||\
#PowerShell|ps1||\
#PowerPro|powerpro||\
#&Properties|properties||\
#Pytho&n|py||\
#R|R||\
#Reso&urce|rc||\
#Ruby|rb||\
#Shell|sh||\
#S&QL|sql||\
#Specman|e||\
#&TCL|tcl||\
#TeX|tex||\
#&txt2tags|t2t||\
#&VB|vb||\
#VBScr&ipt|vbs||\
#Verilog|v||\
#VHDL|vhd||\
#&XML|xml||\
#&YAML|yaml||
</syntaxhighlight>

For whatever language you wish to have an option appear under the ''Language'' menu option, uncomment the language.

Say you want to SciTE to give you the option to highlight batch script code, change the following string in the above list from

<syntaxhighlight lang="properties">
#&Batch|bat||\
</syntaxhighlight>
to
<syntaxhighlight lang="properties">
&Batch|bat||\
</syntaxhighlight>
Restart SciTE and if done correctly, the option should be present!
Do this for any language listed in the above example list.

In the case that you uncommented a language and you notice that it's not being highlighted correctly, then we will have to edit some things in the '''SciTEGlobal.properties''' file.

Open the '''SciTEGlobal.properties''' file in a text editor and find the section

<syntaxhighlight lang="properties">
# import properties\all the language specific properties files
</syntaxhighlight>
Below that section there will be a few strings that look like
<syntaxhighlight lang="properties">
#import properties\[syntax]

</syntaxhighlight>
Uncomment the syntax related property you wish to have support for.

Say you wanted support for ruby, just locate the one that says ''ruby'' where ''[syntax]'' is written.

File:InlineError.JPG

2012-11-09T04:30:34Z

FlutterShy:

User:FlutterShy

2012-11-09T03:16:17Z

FlutterShy:

SciTE4AutoIt3

2012-11-09T03:12:51Z

FlutterShy:

An Introduction to Computer Science with AutoIt

2012-11-09T01:56:59Z

FlutterShy: /* What is computer science? */

Before starting this series, it is assumed you have a firm grasp of programming in the AutoIt language, and a firm grasp on general aspects of computers.During this series, I will attempt to augment your programming knowledge with an informed understanding of some elements of computer science. I will show you a practical and efficient approach to solving computational and implementational problems, as well as provide you with a range of common algorithms and methodologies that will enrich your programming.So lets get started …

== What is computer science? ==

Wikipedia says:
<nowiki>Computer science is the scientific and practical approach to computation and its applications....
A computer scientist specializes in the design of computation systems.</nowiki>
As such, computer science has two elements:
* Approach to problem solving
* Theoretical understanding

During this series, I will focus on both of these objectives, and present them in such a way that they can be used to inform your programming. I will try and keep the theory component to only what is required, to avoid creeping out the less mathy readers with all the abstraction. That said, it is important to remember that the theory is important; and abstracting in this way will broaden your ability to think, reason, and solve computational problems.

== Computer Science :: A Practical Approach ==

If you asked a computer scientist and an ordinary programmer to come up with a solution to the same problem, you would likely get two entirely different pieces of code. These variations are drawn from the considerations each individual have, and the process at which they arrive at their solutions.

A typical programmer's considerations:
# A clean, working solution
# good code readability
A computer scientists' considerations:
# A working solution, with known limitations
# Efficiency / Scalability
# code readability

In this way, the problem solving process can be broken down into a few distinct phases:

'''1. Understand the problem. No really.'''

A key element of time is spent stepping through and investigating the properties of the problem. Only by doing this, is it possible to realise the limitations of any specific solution, and have epiphanies where you realise new optimizations that greatly improve the efficiency of your solution.For example, consider the task is to write a function that finds the n-th number of the Fibonacci sequence.

The Fibonacci sequence looks something like: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34 …

The n-th number in the sequence is dependent on the sum of the two numbers before it.

Knowing this, a typical programmer might write a function like this:
<nowiki>
Func Fib($n)
if $n = 0 return 0
if $n = 1 return 1
return fib(n-1) + fib(n-2)
Endfunc</nowiki>

When the function is called, it repeatedly calls itself to find the previous two Fibonacci numbers, which in turn call the function again, and so on. (a technique known as recursion).However, a computer scientist will investigate the nature of the problem. For instance, he may find that a solution like the one above, when given any value for n, needlessly repeats calculations it has already done previously:

<nowiki>
fib(5)
1. fib(4) + fib(3)
2. (fib(3) + fib(2)) + (fib(2) + fib(1))
3. ((fib(2) + fib(1)) + (fib(1) + fib(0))) + ((fib(1) + fib(0)) + fib(1))
4. (((fib(1) + fib(0)) + fib(1)) + (fib(1) + fib(0))) + ((fib(1) + fib(0)) + fib(1))
</nowiki>

And the computer scientist would use this understanding to his advantage when coming up with a solution.

'''2. Evaluating solutions based on efficiency / scalability'''

Before solutions can be evaluated, one needs a benchmark on which to evaluate them on, which brings us to complexity theory. If you excuse the fancy name, complexity is really just a rough measurement of the speed and efficiency of some solution/algorithm.

Normally, one talks about time complexity, ie the fast your solution is, but memory complexity may also be a consideration.

The measurements are in reference to n. n is some number that represents the input to our program. So under different problems and algorithms, n can be the number of elements in an array, the number of input, the nth number that we are trying to find....etc.

There are three ways of looking at complexity; best case, average case, and worst case scenario. Lets look at an example:

<nowiki>
For $x in $array[0]
if $array[$x] = $val return $x
Next
return $notfound</nowiki>

In the worst case, the element we are searching for is not in the array. Thus, it must search through every element in the array to find a result. Thus, we say it has a worst case time complexity of n, where n is the number of items in the array.

The shorthand for writing worst-case is called big-o notation, and it is written like this: O(n).

If we were to graph y=n, you would find a straight line. Thus, we can say the performance of this solution is directly proportional to the number of elements in the array. This is a good thing, as it means that performance does not degrade at an increasing rate for large values of n.

In the best case scenario, the element we are looking for is in the first element of the array, so complexity is o(1) ie: it only ever takes one iteration. Notice that the little o is used for notation in this case.

I leave it to an exercise to the reader to determine what the average case time complexity is. Θ (???)

In computer science, we are almost always only concerned about the worst-case scenario, and the shape of the graph if we plot y=timecomplexity where x=n. For instance, O(n^2) looks like this:

http://sqlinthewild.co.za/wp-content/uploads/2011/11/On2_thumb.png

By the shape of the graph, it is clear that it takes an increasing amount of time per value of n, as n becomes large. Thus, it is clear that this algorithm doesnt scale well for large values of n.

Additionally, when writing the notation for complexity, we only care about the highest power of n. Say you had some function that had O(44n + 4n^2 + 88), you would write it as O(n^2), as all other terms become insignificant as n gets really large. Moreover, as we are only concerned about the shape of the graph, we can drop the numbers before the n.

In this way, you should evaluate the efficiency of your potential solutions, and be able to project how the solution will behave when heavily loaded (ie: large values for n). You should then pick one which is the best balance of complexity, and ease of implementation.A large part of this series will be detailing how to implement various algorithms, which have varying complexities. Often, there will be many possible choices, and you will need to pick the one best for you.

'''3. Pick, implement, and test your solution'''

The final stage of development. Going back to our Fibonacci function example, our computer scientist may decide to store the results of calculations (like answer of fib(2)) to stop unnessessary recursion and repeated calculations. This is a technique known as dynamic programming, and it greatly improves the complexity of this algorithm, and works really fast for large values of n.

== Conclusion ==
This concludes part one of this series. In the next part, [[An Introduction to Computer Science with AutoIt pt2]], we start to go through comventional algorithms / solutions to sorting, and in future parts, move on to datastructures, and searching algorithms.

FAQ

2012-11-09T01:43:44Z

FlutterShy: /* _Singleton function */

This is a list of frequently asked questions asked on the forums.
Other FAQs include:
* The one found in the [http://www.autoitscript.com/autoit3/docs/faq.htm AutoIt HelpFile]. Much of it is about the transition from V2 to V3, but most is still relevant and should be a port of call, as well as this one.

==How can I debug my script?==

=== In SciTE ===
This one has a myriad of answers, but the most effective is to begin by using the [http://www.autoitscript.com/autoit3/scite/ SciTE4AutoIt3 Editor] to create or edit scripts. This program is useful in debugging for the following reasons:

* Syntax highlighting allows for immediate viewing of any mistakes from unended script tags or quotes. This allows the scripter to visibly see the difference between the following portions of code.
[[File:FAQ_Q1_2.jpg|center|Incorrect code]]
And the incorrect version:
[[File:FAQ_Q1_3.jpg|center||Correct Code]]
* Global Syntax check built directly into the tools menu allows you to check an entire script for problems all at once.
* Built-in code tidying program that correctly indents untidy code and repairs messy scripts to allow them to be more readable. It also corrects problems with incorrectly capitalised function names and variables.
* Per-line trace insertion allows you to log every line of code executed to debug errors.
* Debug MsgBox's or ConsoleWrite's are able to be added anywhere in the script directly from SciTE. ConsoleWrite lines are less intrusive and prevent the added annoyance to the user of MsgBox's.

[[File:FAQ_Q1_4.jpg|center|Picture of SciTE4AutoIt3]]

=== Using more code to check @error value ===
Nearly all functions will return something. Most of the time when a function fails, it returns 0 and sets @error. You can use this information not only to create scripts that handle for different errors but to debug and find out exactly why you are having problems. Check the help file for specific functions and their return values.

=== Via the Tray icon===
You can add this line at the top of your script (1 is on, 0 is off) to enable debugging from the tray icon.

<syntaxhighlight lang="autoit">AutoItSetOption ("TrayIconDebug", 1);0-off</syntaxhighlight>
Then if you run the script (uncompiled as an AU3 file), you can mouse over the AutoIt icon in the system tray (down by the clock) to display debugging information.

[[File:FAQ_Q1_1.jpg|center|Example output for TrayIconDebug]]

=== OutputDebugString native call ===
You can also debug a script on any computer by adding the following code to your script:

<syntaxhighlight lang="autoit">Func dbg($msg)
DllCall("kernel32.dll", "none", "OutputDebugString", "str", $msg)
EndFunc</syntaxhighlight>
Then, when you need to add a debug line, call it as necessary. Example:

<syntaxhighlight lang="autoit">dbg("The value of Variable 1 at this time is " & $var1)</syntaxhighlight>
This debugging is completely transparent to the user, and is only viewable with a program such as DebugView from SysInternals. This method of debugging has the added advantage of being available to the developer in situations where is not acceptable or feasable to install SciTE on a client's unit.

=== Graphical debugger ===
Stumpii created a [http://www.autoitscript.com/forum/index.php?showtopic=21834 Graphical AutoIt Debugger], similar to Dev-C++'s debugging style.

[[File:FAQ_Q1_5.jpg|center|Stumpii's Graphical AutoIt Debugger]]

==How can I run something that is not an exe file [.txt, .msi, .pdf,.jpg etc.] [or] How can I open a webpage in the default browser?==
It was for this reason that the ShellExecute function was created. Here is one example:

<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3", "", "", "edit", @SW_MAXIMIZE)</syntaxhighlight>

You can also specify a web address this way:

<syntaxhighlight lang="autoit">ShellExecute("http://www.autoitscript.com/forum", "", "", "open")</syntaxhighlight>

If you normally are able to right-click the file and select print, then you can also print the file from AutoIt using this function:

<syntaxhighlight lang="autoit">ShellExecute("C:\boot.ini", "", "", "print")</syntaxhighlight>

If you wish to open the file with the default program, you can do as follows (BETA ONLY):
<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3")</syntaxhighlight>

If you wish your script to wait until the process is finished, you can use the ShellExecuteWait function with the same parameters.

Note:
The default verb is the verb configured in the registry. If no verb is set as default in the registry then the "open" verb is used. If the "open" verb is not present then the first verb listed in the registry is used (except on Windows 2000).

==How can I prevent more than one copy of my script from running at once / detect another copy of my script running?==

=== _Singleton function ===
There are a few different ways to go about this. You can use a function called _Singleton to detect multiple instances of your script. An example of how to use this code:

<syntaxhighlight lang="autoit">#include <Misc.au3>
_Singleton("TheNameOfMyScript")</syntaxhighlight>

In this instance, the script will bring up some messages explaining to the user of the occurring events.
This example will show you how the above function can be used in a real world application.
<syntaxhighlight lang="autoit">#include <Misc.au3>
If _Singleton("MyScriptName", 1) = 0 Then
; If successful, running our script a second time should cause us to fall through here
MsgBox(16, "User Generated Error Message", "Error: This script is already running!")
Else
; We have detected that we are the only instance running, now we will run a second instance to display _Singleton's function!
MsgBox(64, "Information!", "We are the first instance of this script, press OK to run another instance and trigger the error message!")
Switch @Compiled
Case 1
Run(FileGetShortName(@ScriptFullPath));when running an app, it's usually better to use its short name
Case 0
Run(FileGetShortName(@AutoItExe) & ' /AutoIt3ExecuteScript ' & FileGetShortName(@ScriptFullPath))
EndSwitch
Sleep(1000)
MsgBox(64, "Information!", "We ran a second instance, you should have recieved an error message!", 5)
EndIf
Exit</syntaxhighlight>

===_MutexExists function ===
Another method is to use _MutexExists.

<syntaxhighlight lang="autoit">
If _MutexExists("MydeswswScriptName") Then
; We know the script is already running. Let the user know.
MsgBox(0, "Script Name", "This script is already running. Using multiple copies of this script at the same time is unsupported!")
Exit
EndIf

;Function Author- Martin
Func _MutexExists($sOccurenceName)
Local $ERROR_ALREADY_EXISTS = 183, $handle, $lastError
$sOccurenceName = StringReplace($sOccurenceName, "", ""); to avoid error
$handle = DllCall("kernel32.dll", "int", "CreateMutex", "int", 0, "long", 1, "str", $sOccurenceName)
$lastError = DllCall("kernel32.dll", "int", "GetLastError")
Return $lastError[0] = $ERROR_ALREADY_EXISTS
EndFunc;==>_MutexExists</syntaxhighlight>

==How can I run my script as a service?==
This is also a question with multiple answers, and none of them are the only way to do it. The first question to ask yourself is whether or not you wish to install the service on other computers besides your own.

=== On your own computer - One time only ===
The easiest way to do this is to use Pirmasoft RunAsSvc. This program makes services easy to install and easy to remove when necessary.

=== On all computers that run your script===
To do this you can use SRVANY.EXE and [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3]. You can then use this code to install your script as a service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_CreateService("", $servicename, "My AutoIt Script", "C:\Path_to_\srvany.exe", "LocalSystem", "", 0x110)
RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\" & $servicename & "\Parameters", "Application", "REG_SZ", @ScriptFullPath)
</syntaxhighlight>

Or use the following code to delete this service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_DeleteService("", $servicename)
</syntaxhighlight>

There is one caveat to setting up AutoIt as a service. If the service is not installed using the above code, it must have the "allow service to interact with the desktop" setting or else automation functions such as Control* or Win* functions will not function. To assure the service does indeed have this setting, use the following code:

<syntaxhighlight lang="autoit">RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\[ServiceName]", "Type", "REG_DWORD", 0x110)</syntaxhighlight>

==How can I create/start/stop or otherwise control a service?==
There are two include libraries that are designed specifically to interact with services. These are the following:

* [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3] made by SumTingWong. Functionality:
** _StartService()
** _StopService()
** _ServiceExists()
** _ServiceRunning()
** _CreateService()
** _DeleteService()
* [http://www.autoitscript.com/forum/index.php?showtopic=22165 _NTServices.au3] made by CatchFish. Functionality:
** _ServiceStart()
** _ServiceStop()
** _ServiceStatus()
** _ServicePause()

==How can I display a progress bar while copying files or directories?==
There are a many different topics on how to do this. For more, just search the forums for [http://www.autoitscript.com/forum/index.php?act=Search&CODE=show&searchid=22030d4d4effe5e32da23fdb69ed772f&search_in=posts&result_type=topics&highlite=%2BCopy%2B Progress Copy + Progress].
* [http://www.autoitscript.com/forum/index.php?showtopic=11313 Copy with progress dialog]... By ezztabi
* [http://www.autoitscript.com/forum/index.php?showtopic=11888 Yet another copy with progress]... By SumTingWong
* [http://www.autoit.de/index.php?page=Thread&postID=58875 _MultiFileCopy]... By Oscar (German Forums)
* [http://www.autoitscript.com/forum/index.php?showtopic=19370&st=45&p=186198&#entry186198 _FileCopy]... By Jos

[[File:FAQ_Q6_1.jpg|center|Copy progress dialog by ezztabi]]

==How can I make a hotkey that only works in my GUI?==
It used to be quite tedious setting hotkeys to only work in your GUI. Now there is an easier way with the function GUISetAccelerators.

(From Helpfile example)
<syntaxhighlight lang="autoit">
; A simple custom messagebox that uses the MessageLoop mode
#include <GUIConstantsEx.au3>

GUICreate("Custom Msgbox", 210, 80)

GUICtrlCreateLabel("Please click a button!", 10, 10)
$YesID = GUICtrlCreateButton("Yes", 10, 50, 50, 20)
$NoID = GUICtrlCreateButton("No", 80, 50, 50, 20)
$ExitID = GUICtrlCreateButton("Exit", 150, 50, 50, 20)

; Set accelerators for Ctrl+y and Ctrl+n
Dim $AccelKeys[2][2]=[["^y", $YesID], ["^n", $NoID]]
GUISetAccelerators($AccelKeys)

GUISetState(); display the GUI

Do
$msg = GUIGetMsg()

Select
Case $msg = $YesID
MsgBox(0, "You clicked on", "Yes")
Case $msg = $NoID
MsgBox(0, "You clicked on", "No")
Case $msg = $ExitID
MsgBox(0, "You clicked on", "Exit")
Case $msg = $GUI_EVENT_CLOSE
MsgBox(0, "You clicked on", "Close")
EndSelect
Until $msg = $GUI_EVENT_CLOSE Or $msg = $ExitID
</syntaxhighlight>

==How can I perform an action while a key is held down?==
You can use the _IsPressed() function to determine when a key is held down. The values that can be specified in this function are listed in the AutoIt Help File under User Defined Functions -> Misc Management -> _IsPressed. The following example will press the left mouse button while the k key is held down.

<syntaxhighlight lang="autoit">#include <Misc.au3>
$pressed = 0
While 1
If _IsPressed("4B") Then
If Not $pressed Then
ToolTip("K Key being held down")
MouseDown("left")
$pressed = 1
EndIf
Else
If $pressed Then
ToolTip("")
MouseUp("left")
$pressed = 0
EndIf
EndIf
Sleep(250)
WEnd</syntaxhighlight>

==How can I run my script on a remote computer over the network?==
The answer to this question depends on how much experience you have in networking. If the target system is a Windows 2000 or Windows XP Pro system to which you have administrator access then you may use one of the following programs:

* PsExec from SysInternals
* BeyondExec from BeyondLogic

With either of these programs it is possible to launch any process on a remote system and even copy your script to the target computer before starting it. Neither these programs nor any others will work with Windows XP Home Edition unless you create a custom "command listener" that you manually install on the target system.

NOTE: Those of you with more advanced programming skills and a little imagination can figure out how to use the service control libraries and srvany.exe to do this same thing without either of the above mentioned programs.

==How can I make a User Defined Function with optional parameters like the ones I see in the Help File?==
You can specify optional parameters by giving them a default value in the Func declaration. An example of how this is

done:
<syntaxhighlight lang="autoit">
Func testme($param1, $param2 = "nothing", $param3 = 5)
MsgBox(0, "", "Parameter one is required. The value of Parameter 1 is " & $param1 & @CRLF & _
"Parameter 2 is optional. The value of Parameter 2 is " & $param2 & @CRLF & _
"Parameter 3 is optional. The value of Parameter 3 is " & $param3)
EndFunc</syntaxhighlight>

If testme() is called with only one parameter [I.E. testme("test")] then the output is:
<blockquote>
Parameter one is required. The value of Parameter 1 is test<br />
Parameter 2 is optional. The value of Parameter 2 is nothing<br />
Parameter 3 is optional. The value of Parameter 3 is 5<br />
</blockquote>
However, if the function is called with more than one parameter like this testme("test", "something"), then the output is
<blockquote>
Parameter one is required. The value of Parameter 1 is test<br />
Parameter 2 is optional. The value of Parameter 2 is something<br />
Parameter 3 is optional. The value of Parameter 3 is 5<br />
</blockquote>

==How can I make my script start every time windows starts?==
You can use one of the following codes to allow your script to start with Windows:
<syntaxhighlight lang="autoit">RegWrite("HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run", "MyProgramName", "REG_SZ", @ScriptFullPath)</syntaxhighlight>
or
<syntaxhighlight lang="autoit">FileCreateShortcut(@ScriptFullPath, @StartupCommonDir & "\MyProgramName.lnk")</syntaxhighlight>

==How can I have the script delete itself?==
The following function will delete the running script or .exe once it has finished execution.

'''WARNING: Make a copy of your script before calling this function!!!'''

<syntaxhighlight lang="autoit">
Func _SelfDelete($iDelay = 0)
Local $sCmdFile
FileDelete(@TempDir & "\scratch.bat")
$sCmdFile = 'ping -n ' & $iDelay & ' 127.0.0.1 > nul' & @CRLF _
& ':loop' & @CRLF _
& 'del "' & @ScriptFullPath & '"' & @CRLF _
& 'if exist "' & @ScriptFullPath & '" goto loop' & @CRLF _
& 'del %0'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc;==>_SelfDelete
</syntaxhighlight>

==How can I create a clickable website hyperlink in my gui?==
[[File:FAQ_Q13_1.jpg|center|Example GUI using Gary's UDF.]]

Gary Frost has made great advances in this area and has provided a [http://www.autoitscript.com/forum/index.php?showtopic=23111&st=0 UDF here] to help with doing this.

==How can I change the screen resolution / refresh rate / color depth?==
[http://www.autoitscript.com/forum/index.php?showtopic=20121 ChangeResolution.au3] is a library function created to make changes to these settings.

== How can I get the screen resolution in multiple monitor setups?==
The following code was worked out by Larry to determine the total screen resolution of multiple monitors:

<syntaxhighlight lang="autoit">
$aTSR = _GetTotalScreenResolution()
MsgBox(0, "Total Screen Resolution", "Width = " & $aTSR[0] & @CRLF & _
"Height = " & $aTSR[1])

;Original code by Larry.
;Edited by BrettF
Func _GetTotalScreenResolution()
Local $aRet[2]
Global Const $SM_VIRTUALWIDTH = 78
Global Const $SM_VIRTUALHEIGHT = 79
$VirtualDesktopWidth = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALWIDTH)
$aRet[0] = $VirtualDesktopWidth[0]
$VirtualDesktopHeight = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALHEIGHT)
$aRet[1] = $VirtualDesktopHeight[0]
Return $aRet
EndFunc
</syntaxhighlight>

== How can I register a file type with my program [or] How can I make files with a certain extension open in my program?==
[[File:FAQ_Q16_1.jpg|center|Example of how a file type can be registered.]]
File registration can be a tricky business for those who have not done it before. The first thing to be done is to modify your script to allow it to accept files from the command line. Here is one example of how to do this:

<syntaxhighlight lang="autoit">
;$cmdline[0] is the number of parameters passed
If $cmdline[0] <> 0 Then
$filename = $cmdline[1]
;Do something with the file here
MsgBox(0, "UXYFixer", 'The file name passed to the command line is "' & $filename & '"')
Else
; We did not get any command line parameters.
; If this is a command line only program, you would want to
; alert the user that the command line parameters were incorrect.
; If this is a GUI program (like a notepad program), you would
; want to simply continue from here without opening a file.
MsgBox(0, "UXYFixer", 'Command line parameters incorrect.' & @CRLF & 'Command line usage: "' & @ScriptName & '" "file to process"')
EndIf</syntaxhighlight>
After your script is ready to accept files, you can begin to register the file type you need with your program. To prevent errors, this-is-me has created a UDF that will allow you to do this easily:

Here is an example of how to register and unregister a file extension using this UDF:
<syntaxhighlight lang="autoit">#include "FileRegister.au3"
;================================================
;
; Description: FileRegister($ext, $cmd, $verb [, $def [, $icon = "" [, $desc = "" ]]])
; Registers a file type in Explorer
;
; Parameter(s): $ext - File Extension without period eg. "zip"
; $cmd - Program path with arguments eg. '"C:\test\testprog.exe" "%1"'
; (%1 is 1st argument, %2 is 2nd, etc.)
; $verb - Name of action to perform on file
; eg. "Open with ProgramName" or "Extract Files"
; $def - Action is the default action for this filetype
; (1 for true 0 for false)
; If the file is not already associated, this will be the default.
; $icon - Default icon for filetype including resource # if needed
; eg. "C:\test\testprog.exe,0" or "C:\test\filetype.ico"
; $desc - File Description eg. "Zip File" or "ProgramName Document"
;
;================================================

FileRegister("uxy", '"' & @ScriptFullPath & '" "%1"', "Open in UXYFixer", 1, @ScriptFullPath & ',0', "UXYFixer Document")

;========================================
;
; Description: FileUnRegister($ext, $verb)
; UnRegisters a verb for a file type in Explorer
; Parameter(s): $ext - File Extension without period eg. "zip"
; $verb - Name of file action to remove
; eg. "Open with ProgramName" or "Extract Files"
;
;========================================

FileUnRegister("uxy", "Open in UXYFixer")</syntaxhighlight>

'''Download here:'''
[http://www.autoitscript.com/forum/index.php?app=core&module=attach&section=attach&attach_id=26378 FileRegister.au3]

==Why doesn't my combobox (GUICtrlCreateCombo) show a dropdown list when clicked?==
When using GUICtrlCreateCombo be sure to enter the desired height for your combobox list in the "height" parameter. Windows XP automatically selects an appropriate height for combo boxes, but other versions of Windows usually do not.
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,20)</syntaxhighlight>
Would correctly be changed to:
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,200)</syntaxhighlight>

==Why isn't my thread getting any replies?==

=== Asking the right question right ===
Did you give a good description of the problem? If your title or explanation of the issue is not descriptive, users are likely to bypass your issue instead of helping. Post titles such as "Help Me", "I Have A Problem", "Question", "Help me fix my code", "This code doesn't work" or similarly worded titles will not readily draw forum users to your post. Experienced users (which are your best hope of resolving the issue) will often skip your post altogether in cases like this. An example of a post title descriptive enough to attract users to assist you is "Problem with WinWaitClose" or "Loop never ends".

=== Example for reproduction ===
Did you post example code? If you have not posted an example of the code you are having an issue with, then you will not recieve support. When posting a non-working script, please do so in the smallest amount of stand-alone code possible. If the code you post cannot run by itself on another person's computer, they will not be able to recreate the issue.

=== Speak English and speak it right ===
Did you use proper English? Here are guidelines for posting properly in the english language:
* Use proper case. THIS IS CONSIDERED YELLING. If you post in ALL UPPERCASE or all lowercase then you will look like a doofus.
* Use proper punctuation. Complete sentences need only one trailing punctuation mark -- not three!!! Writing a sentance without simple punctuation such as commas or other punctuation is considered lazy, which is considered a good judge of the poster's coding style. If you cannot summon the strength to write a sentence with correct punctuation, you will most likely miss simple coding mistakes such as unterminated quotes.

=== Breaking forum rules, law, modesty, or common Sense ===
Make sure you are not giving the impression of breaking forum rules, http://www.autoitscript.com/forum/forum-2/announcement-15-forum-rules-7-nov-2012/. Make sure you are not doing anything that can be perceived as breaking the law.

==Why does the Ctrl key get stuck down after I run my script?==

=== Keys virtually stuck ===
It could equally be the Shift Or the Alt key.

If you use Send In a script And you have a problem With keys being stuck down Then Send is the most likely culprit. A similar problem can occur With BlockInput. The solution is generally quite simple. If there is a key like Shift Or Alt held down at the start of the Send sequence, but that key is released by the time the Send sequence finishes Then the key will get 'stuck' down. As an example of a solution, you could replace the Send function in your script with the _SendEx function below.

The _SendEx function waits for the Shift, Alt And Ctrl keys to be released or pops up a warning if the $warn parameter is not an empty string. Therefore it is not intended to be used when one of these modifier keys has been set to be down using any combination of {ALTDOWN}, {SHIFTDOWN} and {ALTDOWN}.
<syntaxhighlight lang="autoit">
#include < Misc.au3 >
;Send the string $ss after the Shift Alt and Ctrl keys are released. Optionally give a warning after 1 sec if any of those keys are still down.
;Requires misc.au3 to be included in the script for the _IsPressed function.
Func _SendEx($ss, $warn = "")
Local $iT = TimerInit()

While _IsPressed("10") Or _IsPressed("11") Or _IsPressed("12")
If $warn <> "" And TimerDiff($iT) > 1000 Then
MsgBox(262144, "Warning", $warn)
EndIf
Sleep(50)
WEnd
Send($ss)
EndFunc;==>_SendEx</syntaxhighlight>

=== General unstuck method ===
Shilbiz also discovered that the following can 'clear' locked down keys.
<syntaxhighlight lang="autoit"> ControlSend("", "", "", "text", 0)</syntaxhighlight>

==How can I use Pixel functions?==

=== Using a color change as an event ===
The following is an example of using the pixel to check if the colour has changed in a specific region.
<syntaxhighlight lang="autoit">
Local $PixelCheck, $NewCheck
$PixelCheck = PixelCheckSum(40, 50, 60, 70); Get the checksum for this area.
While 1; Keep going
$NewCheck = PixelCheckSum(40, 50, 60, 70)
If $PixelCheck <> $NewCheck Then
; The old pixel checksum and the new one are different.
$PixelCheck = $NewCheck; Update the $PixelCheck to the new value
; Let us now it has changed. Change this to what you want to happen when the colour in the region changes.
Msgbox(48,"PixelChecksum","Pixel region has changed !")
EndIf
Sleep(50); Just to give the CPU a bit of a break.
Wend</syntaxhighlight>

=== Searching for a specific pixel color ===
This is an example of searching for a specific pixel (red), both pure red (0xFF0000) and red in a few different shades.
<syntaxhighlight lang="autoit">; Find a pure red pixel in the range 0,0-20,300
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000 )
If Not @error Then
MsgBox(0, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf

; Find a pure red pixel or a red pixel within 10 shades variations of pure red
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000, 10 )
If Not @error Then
MsgBox(0, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf</syntaxhighlight>

==Why doesn't my script work on a locked workstation?==
On a locked station any window will never be active (active is only dialog with text "Press Ctrl+Alt+Del"). In Windows locked state applications run hidden (behind that visible dialog) and do not have focus and active status. So generally don't use Send() MouseClick() WinActivate() WinWaitActive() WinActive() etc. Instead use ControlSend() ControlSetText() ControlClick() WinWait() WinExists() WinMenuSelectItem() etc. This way you may have your script resistive against another active windows. It's possible to run such a script from scheduler on locked Windows stations.

==Where can I learn AutoIt? Are there any tutorials?==
To learn AutoIt you have two main options available to you:

AutoIt 1-2-3, an interactive classroom by Valuater. You may find it here:
[http://www.autoitscript.com/forum/index.php?showtopic=21048 http://www.autoitscript.com/forum/index.php?showtopic=21048]

There is also updated LxP's AutoIt tutorial by BrettF. You can find it here:
[http://www.autoitscript.com/forum/index.php?showtopic=84960 http://www.autoitscript.com/forum/index.php?showtopic=84960]

There is also a book; AutoIt v3: Your Quick Guide by Andy Flessner.
You can buy the book from here:
[http://oreilly.com/catalog/9780596515126/ http://oreilly.com/catalog/9780596515126/]

On YouTube there are many videos available:
[http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt]

==Why does my script no longer decompile?==
Decompilation is no longer supported, and is only available for the older versions of AutoIt (Version 3.2.5.1 and earlier compiled scripts).

Please '''do not''' post on this topic, but search the forums for more information. Posting topics like this will usually get the topic locked.

Also posting the source (if a hacked decompiler was used) of other compiled scripts, or otherwise mentioning these hacked decompilers will probably get you banned. It is also in violation of the AutoIt EULA (End-User-License-Agreement).

<blockquote>You may not reverse engineer or disassemble the SOFTWARE PRODUCT or compiled scripts that were created with the SOFTWARE PRODUCT.</blockquote>

Please see the [[Decompiling FAQ]] for more information.

==How can I get a window handle when all I have is a PID?==
Refer to the following example showing converting and use when manipulating the window. The function is based on work by Smoke_N/Hubertus and Helge.
<syntaxhighlight lang="autoit">;Run process
$iPID = Run("Notepad.exe")

;Allow window to initialize...
Sleep (500)

;Get HWND.
$hWnd = _GetHwndFromPID($iPID)

;Maximize
WinSetState($hWnd, "", @SW_MAXIMIZE)

;Wait 2 seconds
Sleep(2000)

;Minimize
WinSetState($hWnd, "", @SW_MINIMIZE)

;Wait 2 seconds
Sleep(2000)

;Restore window
WinSetState($hWnd, "", @SW_RESTORE)

;Wait 2 seconds
Sleep(2000)

;Move top left corner of screen, and resize to 800x600
WinMove($hWnd, "", 0, 0, 800, 600)

;Wait 2 seconds
Sleep(2000)

;Calculate Center of screen.
$x = (@DesktopWidth / 2) - 400; Desktop width divided by 2, then minus half the width of the window
$y = (@DesktopHeight / 2) - 300; Desktop height divided by 2, then minus half the height of the window

;Move to center of screen
WinMove($hWnd, "", $x, $y)

;Wait 2 seconds
Sleep(2000)

;Close notepad
WinClose($hWnd)

;Function for getting HWND from PID
Func _GetHwndFromPID($PID)
$hWnd = 0
$winlist = WinList()
Do
For $i = 1 To $winlist[0][0]
If $winlist[$i][0] <> "" Then
$iPID2 = WinGetProcess($winlist[$i][1])
If $iPID2 = $PID Then
$hWnd = $winlist[$i][1]
ExitLoop
EndIf
EndIf
Next
Until $hWnd <> 0
Return $hWnd
EndFunc;==>_GetHwndFromPID</syntaxhighlight>

==How can I use single or double quotes in strings?==
It is a fairly simple concept once you get the basics down. Basically there are a few different ways to go about mixing quotes in strings.

A string in AutoIt can be encased in either single(') or double (") quotes. So if you want to add only one type of quote into your string, your first port of call is to use the other type of quote to encase the string. Like so:

<syntaxhighlight lang="autoit">$var = "I am a 'quote' inside the string"
MsgBox (0, "Test 1", $var)
$var = 'I wish I could be a "quote" inside the string!'
MsgBox (0, "Test 1", $var)</syntaxhighlight>

If you have to have both types of quotes in the string, the easiest way is to escape the quote ending the string as so to speak. To do this, use two quotes instead of one. Like so:

<syntaxhighlight lang="autoit">$var = 'I am a single ''quote'' inside the string made using "single quote!"'
MsgBox (0, "Test 1", $var)</syntaxhighlight>

==When should I bump my threads?==
As a courtesy to other users you should only bump your post once in a 24 hour period. Doing this allows all users the chance to get helped equally. Also refer to [http://www.autoitscript.com/forum/index.php?showtopic=95704&view=findpost&p=688050 Why isn't my thread getting any replies?], as this will help you get replies.

==How can I protect my code from decompilation?==
The fact of the matter is '''you can't fully protect your code'''. AutoIt is an interpreted language, so all scripts are interpreted, and that script has to get stored somewhere. There is still hope though. You can take certain measures to prevent decompiled code from being usable to the person that decompiled. The first step is to obfuscate your code. This causes the code to become unreadable. Basically variables and functions are renamed, making it very hard to make head or tail of what is what.

Please see the [[Decompiling FAQ]] for more information.

==How can I decompile my AutoIt EXEs?==
You cannot decompile your AutoIt compiled scripts unless it was compiled with AutoIt 3.2.5.1 or earlier.

If you wish to simulate decompilation for your script, you can do this using the following simple example:

<syntaxhighlight lang="autoit">;Original Author SmokeN
If $CMDLINE[0] Then
If $CMDLINE[1] == "/SOURCE" AND $CMDLINE[2] == "MYPASSWORD" Then
FileInstall("ThisSCript.au3", @ScriptDir & "\DecompiledScript.au3")
EndIf
EndIf</syntaxhighlight>

Then if you run the exe with the following command line parameters your source will be installed.

<blockquote>myscript.exe /SOURCE MYPASSWORD</blockquote>

== What is proper forum etiquette? What rules are there for the forum?==
Proper forum etiquette will ensure you will stay a member of these forums. So try to follow these rules. Also see this [http://www.autoitscript.com/forum/index.php?showtopic=95704&st=15&p=688050&#entry688050 FAQ post], as you should follow what is outlined there as well.

* Use proper English. MSN speak and the like makes it very hard to understand what you want. Keep posts in proper case because UPPERCASE is considered yelling and lowercase makes you look stupid. Don't use more punctuation marks than necessary. For example ?!!!? and ????? is completely unnecessary.
* Before posting help with a script, make sure you follow these steps:
*# Search for your issue.
*#* There are many thousands of posts on this forum, and chances are your question has been asked before. Make sure to use a variety of terms to maximize your results.
*# Read the helpfile
*#* Most if not all things in the help file will have an example (native functions) or two. Give them a go to try see how the functions work. Most of the time it helps!
*# Give it a go
*#* Seriously, if you can't be bothered to give it a go, then why should we be bothered to help you? If you feel you can't do it and you don't try then how will you ever know? We always prefer that you give it a go because you can learn from your mistakes and hopefully understand it better.
*# Post your problem
*#* Make sure you post in the correct forum.
*#** AutoIt Specific
*#*** General Help and Support (Most support questions)
*#*** GUI Support (Support for the Graphical User Interface)
*#** Non-AutoIT
*#*** Chat
*#*** Developer Chat (Usually for C++ questions.)
*#* Include a detailed description in the content of the post, and a detailed title
*#** Titles such as 'Help' and 'What's wrong?' are not acceptable. To get the most help with your problem, be as descriptive as you can in the title, but keep in mind your title cannot be too long.
*#** Make sure you also include a descriptive question. Just saying 'what is wrong with the following' is also not acceptable, as we will have no idea what the problem is. Describe what you think is wrong and what is not working. It makes our job easier.
*#* Always include your code
*#** It shows us that you have tried and gives us a head start with something to play with.
* Usually asking for a script is not taken too well, within reason. Keep in mind that this is a support forum, so please acknowledge that. Most of us would rather that you learn rather than just having a script written for you. If you do need something written for you, maybe try [http://www.rentacoder.com/ RentACoder], as they are more suited to requests.
* Don't PM other members asking for them to look at threads of to help you unless they request it. It is actually quite rude and annoying to receive PMs of that nature.
* Lurk a little before you dive right in. Read a number of posts, or check out the group's archives. Get a feel for the tone of the forum so you can participate accordingly.
* Say online exactly what you would say in person. In other words, if you wouldn't say it to the person's face in front of your Grandmother, you shouldn't type it here.
* Remember your face doesn't show. Words alone can convey sentiment, but without benefit of inflection or facial expression, they can be misconstrued. Use descriptive wording, emoticons or .gifs to ensure your meaning is clear. By the same token, don't jump to conclusions about another person's intent in posting an unclear comment. When in doubt, ask for clarification.
* Be respectful. Internet etiquette is similar to standard etiquette in this area. Appreciate that your opinion is one of many. You can disagree with another person without being disrespectful or rude to other people.
* Ignore Trolls. If you engage in conversation with one, you'll raise your blood pressure and empower the troll. You can't win a flame war, and you can't sway a troll's opinion. Often, they don't even care about the subject. They live for the conflict and nothing more. Trolls are common and not worthy of your time. Ignore their posts no matter how inflammatory and eventually they'll get bored and move on.
* When you have found an answer for your question:
*# Do not edit your post to be blank or to have worthless information. People may be searching for the same issue you have, so be courteous to them by leaving your question there.
*# It is also optional to add the likes of [SOLVED] into the title, and redirecting people to the answer that helped you. It can make the lives of people searching easier.
* Finally follow the rules:
** [http://www.autoitscript.com/forum/forum-6/announcement-13-forum-rules/ Forum rules]
** [http://www.autoitscript.com/forum/index.php?showtopic=54168 Rules for the Chat forum]
** [http://www.autoitscript.com/forum/index.php?showtopic=65889 Rules for asking for source code]
** [http://www.autoitscript.com/forum/index.php?showtopic=37739 General policies and forum settings]

Some general points taken from [http://www.ehow.com/how_2106033_use-proper-forum-etiquette.html here].

==Are there forums available in my local language?==
Yes there are some available. Some forum members here participate in multiple forums.
* [http://www.autoit.de/ German Forums]
* [http://www.autoit.fr/ French Forums]
* [http://www.autoit.es/ Spanish Forums]
* [http://autoit-script.ru/ Russian Forums]

Please note that these are independent, community-run message boards and not just a translation of this board.

FAQ

2012-11-09T01:24:51Z

FlutterShy: /* _Singleton function */

This is a list of frequently asked questions asked on the forums.
Other FAQs include:
* The one found in the [http://www.autoitscript.com/autoit3/docs/faq.htm AutoIt HelpFile]. Much of it is about the transition from V2 to V3, but most is still relevant and should be a port of call, as well as this one.

==How can I debug my script?==

=== In SciTE ===
This one has a myriad of answers, but the most effective is to begin by using the [http://www.autoitscript.com/autoit3/scite/ SciTE4AutoIt3 Editor] to create or edit scripts. This program is useful in debugging for the following reasons:

* Syntax highlighting allows for immediate viewing of any mistakes from unended script tags or quotes. This allows the scripter to visibly see the difference between the following portions of code.
[[File:FAQ_Q1_2.jpg|center|Incorrect code]]
And the incorrect version:
[[File:FAQ_Q1_3.jpg|center||Correct Code]]
* Global Syntax check built directly into the tools menu allows you to check an entire script for problems all at once.
* Built-in code tidying program that correctly indents untidy code and repairs messy scripts to allow them to be more readable. It also corrects problems with incorrectly capitalised function names and variables.
* Per-line trace insertion allows you to log every line of code executed to debug errors.
* Debug MsgBox's or ConsoleWrite's are able to be added anywhere in the script directly from SciTE. ConsoleWrite lines are less intrusive and prevent the added annoyance to the user of MsgBox's.

[[File:FAQ_Q1_4.jpg|center|Picture of SciTE4AutoIt3]]

=== Using more code to check @error value ===
Nearly all functions will return something. Most of the time when a function fails, it returns 0 and sets @error. You can use this information not only to create scripts that handle for different errors but to debug and find out exactly why you are having problems. Check the help file for specific functions and their return values.

=== Via the Tray icon===
You can add this line at the top of your script (1 is on, 0 is off) to enable debugging from the tray icon.

<syntaxhighlight lang="autoit">AutoItSetOption ("TrayIconDebug", 1);0-off</syntaxhighlight>
Then if you run the script (uncompiled as an AU3 file), you can mouse over the AutoIt icon in the system tray (down by the clock) to display debugging information.

[[File:FAQ_Q1_1.jpg|center|Example output for TrayIconDebug]]

=== OutputDebugString native call ===
You can also debug a script on any computer by adding the following code to your script:

<syntaxhighlight lang="autoit">Func dbg($msg)
DllCall("kernel32.dll", "none", "OutputDebugString", "str", $msg)
EndFunc</syntaxhighlight>
Then, when you need to add a debug line, call it as necessary. Example:

<syntaxhighlight lang="autoit">dbg("The value of Variable 1 at this time is " & $var1)</syntaxhighlight>
This debugging is completely transparent to the user, and is only viewable with a program such as DebugView from SysInternals. This method of debugging has the added advantage of being available to the developer in situations where is not acceptable or feasable to install SciTE on a client's unit.

=== Graphical debugger ===
Stumpii created a [http://www.autoitscript.com/forum/index.php?showtopic=21834 Graphical AutoIt Debugger], similar to Dev-C++'s debugging style.

[[File:FAQ_Q1_5.jpg|center|Stumpii's Graphical AutoIt Debugger]]

==How can I run something that is not an exe file [.txt, .msi, .pdf,.jpg etc.] [or] How can I open a webpage in the default browser?==
It was for this reason that the ShellExecute function was created. Here is one example:

<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3", "", "", "edit", @SW_MAXIMIZE)</syntaxhighlight>

You can also specify a web address this way:

<syntaxhighlight lang="autoit">ShellExecute("http://www.autoitscript.com/forum", "", "", "open")</syntaxhighlight>

If you normally are able to right-click the file and select print, then you can also print the file from AutoIt using this function:

<syntaxhighlight lang="autoit">ShellExecute("C:\boot.ini", "", "", "print")</syntaxhighlight>

If you wish to open the file with the default program, you can do as follows (BETA ONLY):
<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3")</syntaxhighlight>

If you wish your script to wait until the process is finished, you can use the ShellExecuteWait function with the same parameters.

Note:
The default verb is the verb configured in the registry. If no verb is set as default in the registry then the "open" verb is used. If the "open" verb is not present then the first verb listed in the registry is used (except on Windows 2000).

==How can I prevent more than one copy of my script from running at once / detect another copy of my script running?==

=== _Singleton function ===
There are a few different ways to go about this. You can use a function called _Singleton to detect multiple instances of your script. An example of how to use this code:

<syntaxhighlight lang="autoit">#include <Misc.au3>
_Singleton("TheNameOfMyScript")</syntaxhighlight>

In this instance, the script will immediately exit if there is already one copy running. If you simply want to know if another copy is running, you can use code similar to the next example:

<syntaxhighlight lang="autoit">#include <Misc.au3>
If _Singleton("MyScriptName", 1) = 0 Then
; We know the script is already running. Let the user know.
MsgBox(0, "Script Name", "This script is already running. Using multiple copies of this script at the same time is unsupported!")
Exit
EndIf</syntaxhighlight>

===_MutexExists function ===
Another method is to use _MutexExists.

<syntaxhighlight lang="autoit">
If _MutexExists("MydeswswScriptName") Then
; We know the script is already running. Let the user know.
MsgBox(0, "Script Name", "This script is already running. Using multiple copies of this script at the same time is unsupported!")
Exit
EndIf

;Function Author- Martin
Func _MutexExists($sOccurenceName)
Local $ERROR_ALREADY_EXISTS = 183, $handle, $lastError
$sOccurenceName = StringReplace($sOccurenceName, "", ""); to avoid error
$handle = DllCall("kernel32.dll", "int", "CreateMutex", "int", 0, "long", 1, "str", $sOccurenceName)
$lastError = DllCall("kernel32.dll", "int", "GetLastError")
Return $lastError[0] = $ERROR_ALREADY_EXISTS
EndFunc;==>_MutexExists</syntaxhighlight>

==How can I run my script as a service?==
This is also a question with multiple answers, and none of them are the only way to do it. The first question to ask yourself is whether or not you wish to install the service on other computers besides your own.

=== On your own computer - One time only ===
The easiest way to do this is to use Pirmasoft RunAsSvc. This program makes services easy to install and easy to remove when necessary.

=== On all computers that run your script===
To do this you can use SRVANY.EXE and [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3]. You can then use this code to install your script as a service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_CreateService("", $servicename, "My AutoIt Script", "C:\Path_to_\srvany.exe", "LocalSystem", "", 0x110)
RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\" & $servicename & "\Parameters", "Application", "REG_SZ", @ScriptFullPath)
</syntaxhighlight>

Or use the following code to delete this service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_DeleteService("", $servicename)
</syntaxhighlight>

There is one caveat to setting up AutoIt as a service. If the service is not installed using the above code, it must have the "allow service to interact with the desktop" setting or else automation functions such as Control* or Win* functions will not function. To assure the service does indeed have this setting, use the following code:

<syntaxhighlight lang="autoit">RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\[ServiceName]", "Type", "REG_DWORD", 0x110)</syntaxhighlight>

==How can I create/start/stop or otherwise control a service?==
There are two include libraries that are designed specifically to interact with services. These are the following:

* [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3] made by SumTingWong. Functionality:
** _StartService()
** _StopService()
** _ServiceExists()
** _ServiceRunning()
** _CreateService()
** _DeleteService()
* [http://www.autoitscript.com/forum/index.php?showtopic=22165 _NTServices.au3] made by CatchFish. Functionality:
** _ServiceStart()
** _ServiceStop()
** _ServiceStatus()
** _ServicePause()

==How can I display a progress bar while copying files or directories?==
There are a many different topics on how to do this. For more, just search the forums for [http://www.autoitscript.com/forum/index.php?act=Search&CODE=show&searchid=22030d4d4effe5e32da23fdb69ed772f&search_in=posts&result_type=topics&highlite=%2BCopy%2B Progress Copy + Progress].
* [http://www.autoitscript.com/forum/index.php?showtopic=11313 Copy with progress dialog]... By ezztabi
* [http://www.autoitscript.com/forum/index.php?showtopic=11888 Yet another copy with progress]... By SumTingWong
* [http://www.autoit.de/index.php?page=Thread&postID=58875 _MultiFileCopy]... By Oscar (German Forums)
* [http://www.autoitscript.com/forum/index.php?showtopic=19370&st=45&p=186198&#entry186198 _FileCopy]... By Jos

[[File:FAQ_Q6_1.jpg|center|Copy progress dialog by ezztabi]]

==How can I make a hotkey that only works in my GUI?==
It used to be quite tedious setting hotkeys to only work in your GUI. Now there is an easier way with the function GUISetAccelerators.

(From Helpfile example)
<syntaxhighlight lang="autoit">
; A simple custom messagebox that uses the MessageLoop mode
#include <GUIConstantsEx.au3>

GUICreate("Custom Msgbox", 210, 80)

GUICtrlCreateLabel("Please click a button!", 10, 10)
$YesID = GUICtrlCreateButton("Yes", 10, 50, 50, 20)
$NoID = GUICtrlCreateButton("No", 80, 50, 50, 20)
$ExitID = GUICtrlCreateButton("Exit", 150, 50, 50, 20)

; Set accelerators for Ctrl+y and Ctrl+n
Dim $AccelKeys[2][2]=[["^y", $YesID], ["^n", $NoID]]
GUISetAccelerators($AccelKeys)

GUISetState(); display the GUI

Do
$msg = GUIGetMsg()

Select
Case $msg = $YesID
MsgBox(0, "You clicked on", "Yes")
Case $msg = $NoID
MsgBox(0, "You clicked on", "No")
Case $msg = $ExitID
MsgBox(0, "You clicked on", "Exit")
Case $msg = $GUI_EVENT_CLOSE
MsgBox(0, "You clicked on", "Close")
EndSelect
Until $msg = $GUI_EVENT_CLOSE Or $msg = $ExitID
</syntaxhighlight>

==How can I perform an action while a key is held down?==
You can use the _IsPressed() function to determine when a key is held down. The values that can be specified in this function are listed in the AutoIt Help File under User Defined Functions -> Misc Management -> _IsPressed. The following example will press the left mouse button while the k key is held down.

<syntaxhighlight lang="autoit">#include <Misc.au3>
$pressed = 0
While 1
If _IsPressed("4B") Then
If Not $pressed Then
ToolTip("K Key being held down")
MouseDown("left")
$pressed = 1
EndIf
Else
If $pressed Then
ToolTip("")
MouseUp("left")
$pressed = 0
EndIf
EndIf
Sleep(250)
WEnd</syntaxhighlight>

==How can I run my script on a remote computer over the network?==
The answer to this question depends on how much experience you have in networking. If the target system is a Windows 2000 or Windows XP Pro system to which you have administrator access then you may use one of the following programs:

* PsExec from SysInternals
* BeyondExec from BeyondLogic

With either of these programs it is possible to launch any process on a remote system and even copy your script to the target computer before starting it. Neither these programs nor any others will work with Windows XP Home Edition unless you create a custom "command listener" that you manually install on the target system.

NOTE: Those of you with more advanced programming skills and a little imagination can figure out how to use the service control libraries and srvany.exe to do this same thing without either of the above mentioned programs.

==How can I make a User Defined Function with optional parameters like the ones I see in the Help File?==
You can specify optional parameters by giving them a default value in the Func declaration. An example of how this is

done:
<syntaxhighlight lang="autoit">
Func testme($param1, $param2 = "nothing", $param3 = 5)
MsgBox(0, "", "Parameter one is required. The value of Parameter 1 is " & $param1 & @CRLF & _
"Parameter 2 is optional. The value of Parameter 2 is " & $param2 & @CRLF & _
"Parameter 3 is optional. The value of Parameter 3 is " & $param3)
EndFunc</syntaxhighlight>

If testme() is called with only one parameter [I.E. testme("test")] then the output is:
<blockquote>
Parameter one is required. The value of Parameter 1 is test<br />
Parameter 2 is optional. The value of Parameter 2 is nothing<br />
Parameter 3 is optional. The value of Parameter 3 is 5<br />
</blockquote>
However, if the function is called with more than one parameter like this testme("test", "something"), then the output is
<blockquote>
Parameter one is required. The value of Parameter 1 is test<br />
Parameter 2 is optional. The value of Parameter 2 is something<br />
Parameter 3 is optional. The value of Parameter 3 is 5<br />
</blockquote>

==How can I make my script start every time windows starts?==
You can use one of the following codes to allow your script to start with Windows:
<syntaxhighlight lang="autoit">RegWrite("HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run", "MyProgramName", "REG_SZ", @ScriptFullPath)</syntaxhighlight>
or
<syntaxhighlight lang="autoit">FileCreateShortcut(@ScriptFullPath, @StartupCommonDir & "\MyProgramName.lnk")</syntaxhighlight>

==How can I have the script delete itself?==
The following function will delete the running script or .exe once it has finished execution.

'''WARNING: Make a copy of your script before calling this function!!!'''

<syntaxhighlight lang="autoit">
Func _SelfDelete($iDelay = 0)
Local $sCmdFile
FileDelete(@TempDir & "\scratch.bat")
$sCmdFile = 'ping -n ' & $iDelay & ' 127.0.0.1 > nul' & @CRLF _
& ':loop' & @CRLF _
& 'del "' & @ScriptFullPath & '"' & @CRLF _
& 'if exist "' & @ScriptFullPath & '" goto loop' & @CRLF _
& 'del %0'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc;==>_SelfDelete
</syntaxhighlight>

==How can I create a clickable website hyperlink in my gui?==
[[File:FAQ_Q13_1.jpg|center|Example GUI using Gary's UDF.]]

Gary Frost has made great advances in this area and has provided a [http://www.autoitscript.com/forum/index.php?showtopic=23111&st=0 UDF here] to help with doing this.

==How can I change the screen resolution / refresh rate / color depth?==
[http://www.autoitscript.com/forum/index.php?showtopic=20121 ChangeResolution.au3] is a library function created to make changes to these settings.

== How can I get the screen resolution in multiple monitor setups?==
The following code was worked out by Larry to determine the total screen resolution of multiple monitors:

<syntaxhighlight lang="autoit">
$aTSR = _GetTotalScreenResolution()
MsgBox(0, "Total Screen Resolution", "Width = " & $aTSR[0] & @CRLF & _
"Height = " & $aTSR[1])

;Original code by Larry.
;Edited by BrettF
Func _GetTotalScreenResolution()
Local $aRet[2]
Global Const $SM_VIRTUALWIDTH = 78
Global Const $SM_VIRTUALHEIGHT = 79
$VirtualDesktopWidth = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALWIDTH)
$aRet[0] = $VirtualDesktopWidth[0]
$VirtualDesktopHeight = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALHEIGHT)
$aRet[1] = $VirtualDesktopHeight[0]
Return $aRet
EndFunc
</syntaxhighlight>

== How can I register a file type with my program [or] How can I make files with a certain extension open in my program?==
[[File:FAQ_Q16_1.jpg|center|Example of how a file type can be registered.]]
File registration can be a tricky business for those who have not done it before. The first thing to be done is to modify your script to allow it to accept files from the command line. Here is one example of how to do this:

<syntaxhighlight lang="autoit">
;$cmdline[0] is the number of parameters passed
If $cmdline[0] <> 0 Then
$filename = $cmdline[1]
;Do something with the file here
MsgBox(0, "UXYFixer", 'The file name passed to the command line is "' & $filename & '"')
Else
; We did not get any command line parameters.
; If this is a command line only program, you would want to
; alert the user that the command line parameters were incorrect.
; If this is a GUI program (like a notepad program), you would
; want to simply continue from here without opening a file.
MsgBox(0, "UXYFixer", 'Command line parameters incorrect.' & @CRLF & 'Command line usage: "' & @ScriptName & '" "file to process"')
EndIf</syntaxhighlight>
After your script is ready to accept files, you can begin to register the file type you need with your program. To prevent errors, this-is-me has created a UDF that will allow you to do this easily:

Here is an example of how to register and unregister a file extension using this UDF:
<syntaxhighlight lang="autoit">#include "FileRegister.au3"
;================================================
;
; Description: FileRegister($ext, $cmd, $verb [, $def [, $icon = "" [, $desc = "" ]]])
; Registers a file type in Explorer
;
; Parameter(s): $ext - File Extension without period eg. "zip"
; $cmd - Program path with arguments eg. '"C:\test\testprog.exe" "%1"'
; (%1 is 1st argument, %2 is 2nd, etc.)
; $verb - Name of action to perform on file
; eg. "Open with ProgramName" or "Extract Files"
; $def - Action is the default action for this filetype
; (1 for true 0 for false)
; If the file is not already associated, this will be the default.
; $icon - Default icon for filetype including resource # if needed
; eg. "C:\test\testprog.exe,0" or "C:\test\filetype.ico"
; $desc - File Description eg. "Zip File" or "ProgramName Document"
;
;================================================

FileRegister("uxy", '"' & @ScriptFullPath & '" "%1"', "Open in UXYFixer", 1, @ScriptFullPath & ',0', "UXYFixer Document")

;========================================
;
; Description: FileUnRegister($ext, $verb)
; UnRegisters a verb for a file type in Explorer
; Parameter(s): $ext - File Extension without period eg. "zip"
; $verb - Name of file action to remove
; eg. "Open with ProgramName" or "Extract Files"
;
;========================================

FileUnRegister("uxy", "Open in UXYFixer")</syntaxhighlight>

'''Download here:'''
[http://www.autoitscript.com/forum/index.php?app=core&module=attach&section=attach&attach_id=26378 FileRegister.au3]

==Why doesn't my combobox (GUICtrlCreateCombo) show a dropdown list when clicked?==
When using GUICtrlCreateCombo be sure to enter the desired height for your combobox list in the "height" parameter. Windows XP automatically selects an appropriate height for combo boxes, but other versions of Windows usually do not.
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,20)</syntaxhighlight>
Would correctly be changed to:
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,200)</syntaxhighlight>

==Why isn't my thread getting any replies?==

=== Asking the right question right ===
Did you give a good description of the problem? If your title or explanation of the issue is not descriptive, users are likely to bypass your issue instead of helping. Post titles such as "Help Me", "I Have A Problem", "Question", "Help me fix my code", "This code doesn't work" or similarly worded titles will not readily draw forum users to your post. Experienced users (which are your best hope of resolving the issue) will often skip your post altogether in cases like this. An example of a post title descriptive enough to attract users to assist you is "Problem with WinWaitClose" or "Loop never ends".

=== Example for reproduction ===
Did you post example code? If you have not posted an example of the code you are having an issue with, then you will not recieve support. When posting a non-working script, please do so in the smallest amount of stand-alone code possible. If the code you post cannot run by itself on another person's computer, they will not be able to recreate the issue.

=== Speak English and speak it right ===
Did you use proper English? Here are guidelines for posting properly in the english language:
* Use proper case. THIS IS CONSIDERED YELLING. If you post in ALL UPPERCASE or all lowercase then you will look like a doofus.
* Use proper punctuation. Complete sentences need only one trailing punctuation mark -- not three!!! Writing a sentance without simple punctuation such as commas or other punctuation is considered lazy, which is considered a good judge of the poster's coding style. If you cannot summon the strength to write a sentence with correct punctuation, you will most likely miss simple coding mistakes such as unterminated quotes.

=== Breaking forum rules, law, modesty, or common Sense ===
Make sure you are not giving the impression of breaking forum rules, http://www.autoitscript.com/forum/forum-2/announcement-15-forum-rules-7-nov-2012/. Make sure you are not doing anything that can be perceived as breaking the law.

==Why does the Ctrl key get stuck down after I run my script?==

=== Keys virtually stuck ===
It could equally be the Shift Or the Alt key.

If you use Send In a script And you have a problem With keys being stuck down Then Send is the most likely culprit. A similar problem can occur With BlockInput. The solution is generally quite simple. If there is a key like Shift Or Alt held down at the start of the Send sequence, but that key is released by the time the Send sequence finishes Then the key will get 'stuck' down. As an example of a solution, you could replace the Send function in your script with the _SendEx function below.

The _SendEx function waits for the Shift, Alt And Ctrl keys to be released or pops up a warning if the $warn parameter is not an empty string. Therefore it is not intended to be used when one of these modifier keys has been set to be down using any combination of {ALTDOWN}, {SHIFTDOWN} and {ALTDOWN}.
<syntaxhighlight lang="autoit">
#include < Misc.au3 >
;Send the string $ss after the Shift Alt and Ctrl keys are released. Optionally give a warning after 1 sec if any of those keys are still down.
;Requires misc.au3 to be included in the script for the _IsPressed function.
Func _SendEx($ss, $warn = "")
Local $iT = TimerInit()

While _IsPressed("10") Or _IsPressed("11") Or _IsPressed("12")
If $warn <> "" And TimerDiff($iT) > 1000 Then
MsgBox(262144, "Warning", $warn)
EndIf
Sleep(50)
WEnd
Send($ss)
EndFunc;==>_SendEx</syntaxhighlight>

=== General unstuck method ===
Shilbiz also discovered that the following can 'clear' locked down keys.
<syntaxhighlight lang="autoit"> ControlSend("", "", "", "text", 0)</syntaxhighlight>

==How can I use Pixel functions?==

=== Using a color change as an event ===
The following is an example of using the pixel to check if the colour has changed in a specific region.
<syntaxhighlight lang="autoit">
Local $PixelCheck, $NewCheck
$PixelCheck = PixelCheckSum(40, 50, 60, 70); Get the checksum for this area.
While 1; Keep going
$NewCheck = PixelCheckSum(40, 50, 60, 70)
If $PixelCheck <> $NewCheck Then
; The old pixel checksum and the new one are different.
$PixelCheck = $NewCheck; Update the $PixelCheck to the new value
; Let us now it has changed. Change this to what you want to happen when the colour in the region changes.
Msgbox(48,"PixelChecksum","Pixel region has changed !")
EndIf
Sleep(50); Just to give the CPU a bit of a break.
Wend</syntaxhighlight>

=== Searching for a specific pixel color ===
This is an example of searching for a specific pixel (red), both pure red (0xFF0000) and red in a few different shades.
<syntaxhighlight lang="autoit">; Find a pure red pixel in the range 0,0-20,300
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000 )
If Not @error Then
MsgBox(0, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf

; Find a pure red pixel or a red pixel within 10 shades variations of pure red
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000, 10 )
If Not @error Then
MsgBox(0, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf</syntaxhighlight>

==Why doesn't my script work on a locked workstation?==
On a locked station any window will never be active (active is only dialog with text "Press Ctrl+Alt+Del"). In Windows locked state applications run hidden (behind that visible dialog) and do not have focus and active status. So generally don't use Send() MouseClick() WinActivate() WinWaitActive() WinActive() etc. Instead use ControlSend() ControlSetText() ControlClick() WinWait() WinExists() WinMenuSelectItem() etc. This way you may have your script resistive against another active windows. It's possible to run such a script from scheduler on locked Windows stations.

==Where can I learn AutoIt? Are there any tutorials?==
To learn AutoIt you have two main options available to you:

AutoIt 1-2-3, an interactive classroom by Valuater. You may find it here:
[http://www.autoitscript.com/forum/index.php?showtopic=21048 http://www.autoitscript.com/forum/index.php?showtopic=21048]

There is also updated LxP's AutoIt tutorial by BrettF. You can find it here:
[http://www.autoitscript.com/forum/index.php?showtopic=84960 http://www.autoitscript.com/forum/index.php?showtopic=84960]

There is also a book; AutoIt v3: Your Quick Guide by Andy Flessner.
You can buy the book from here:
[http://oreilly.com/catalog/9780596515126/ http://oreilly.com/catalog/9780596515126/]

On YouTube there are many videos available:
[http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt]

==Why does my script no longer decompile?==
Decompilation is no longer supported, and is only available for the older versions of AutoIt (Version 3.2.5.1 and earlier compiled scripts).

Please '''do not''' post on this topic, but search the forums for more information. Posting topics like this will usually get the topic locked.

Also posting the source (if a hacked decompiler was used) of other compiled scripts, or otherwise mentioning these hacked decompilers will probably get you banned. It is also in violation of the AutoIt EULA (End-User-License-Agreement).

<blockquote>You may not reverse engineer or disassemble the SOFTWARE PRODUCT or compiled scripts that were created with the SOFTWARE PRODUCT.</blockquote>

Please see the [[Decompiling FAQ]] for more information.

==How can I get a window handle when all I have is a PID?==
Refer to the following example showing converting and use when manipulating the window. The function is based on work by Smoke_N/Hubertus and Helge.
<syntaxhighlight lang="autoit">;Run process
$iPID = Run("Notepad.exe")

;Allow window to initialize...
Sleep (500)

;Get HWND.
$hWnd = _GetHwndFromPID($iPID)

;Maximize
WinSetState($hWnd, "", @SW_MAXIMIZE)

;Wait 2 seconds
Sleep(2000)

;Minimize
WinSetState($hWnd, "", @SW_MINIMIZE)

;Wait 2 seconds
Sleep(2000)

;Restore window
WinSetState($hWnd, "", @SW_RESTORE)

;Wait 2 seconds
Sleep(2000)

;Move top left corner of screen, and resize to 800x600
WinMove($hWnd, "", 0, 0, 800, 600)

;Wait 2 seconds
Sleep(2000)

;Calculate Center of screen.
$x = (@DesktopWidth / 2) - 400; Desktop width divided by 2, then minus half the width of the window
$y = (@DesktopHeight / 2) - 300; Desktop height divided by 2, then minus half the height of the window

;Move to center of screen
WinMove($hWnd, "", $x, $y)

;Wait 2 seconds
Sleep(2000)

;Close notepad
WinClose($hWnd)

;Function for getting HWND from PID
Func _GetHwndFromPID($PID)
$hWnd = 0
$winlist = WinList()
Do
For $i = 1 To $winlist[0][0]
If $winlist[$i][0] <> "" Then
$iPID2 = WinGetProcess($winlist[$i][1])
If $iPID2 = $PID Then
$hWnd = $winlist[$i][1]
ExitLoop
EndIf
EndIf
Next
Until $hWnd <> 0
Return $hWnd
EndFunc;==>_GetHwndFromPID</syntaxhighlight>

==How can I use single or double quotes in strings?==
It is a fairly simple concept once you get the basics down. Basically there are a few different ways to go about mixing quotes in strings.

A string in AutoIt can be encased in either single(') or double (") quotes. So if you want to add only one type of quote into your string, your first port of call is to use the other type of quote to encase the string. Like so:

<syntaxhighlight lang="autoit">$var = "I am a 'quote' inside the string"
MsgBox (0, "Test 1", $var)
$var = 'I wish I could be a "quote" inside the string!'
MsgBox (0, "Test 1", $var)</syntaxhighlight>

If you have to have both types of quotes in the string, the easiest way is to escape the quote ending the string as so to speak. To do this, use two quotes instead of one. Like so:

<syntaxhighlight lang="autoit">$var = 'I am a single ''quote'' inside the string made using "single quote!"'
MsgBox (0, "Test 1", $var)</syntaxhighlight>

==When should I bump my threads?==
As a courtesy to other users you should only bump your post once in a 24 hour period. Doing this allows all users the chance to get helped equally. Also refer to [http://www.autoitscript.com/forum/index.php?showtopic=95704&view=findpost&p=688050 Why isn't my thread getting any replies?], as this will help you get replies.

==How can I protect my code from decompilation?==
The fact of the matter is '''you can't fully protect your code'''. AutoIt is an interpreted language, so all scripts are interpreted, and that script has to get stored somewhere. There is still hope though. You can take certain measures to prevent decompiled code from being usable to the person that decompiled. The first step is to obfuscate your code. This causes the code to become unreadable. Basically variables and functions are renamed, making it very hard to make head or tail of what is what.

Please see the [[Decompiling FAQ]] for more information.

==How can I decompile my AutoIt EXEs?==
You cannot decompile your AutoIt compiled scripts unless it was compiled with AutoIt 3.2.5.1 or earlier.

If you wish to simulate decompilation for your script, you can do this using the following simple example:

<syntaxhighlight lang="autoit">;Original Author SmokeN
If $CMDLINE[0] Then
If $CMDLINE[1] == "/SOURCE" AND $CMDLINE[2] == "MYPASSWORD" Then
FileInstall("ThisSCript.au3", @ScriptDir & "\DecompiledScript.au3")
EndIf
EndIf</syntaxhighlight>

Then if you run the exe with the following command line parameters your source will be installed.

<blockquote>myscript.exe /SOURCE MYPASSWORD</blockquote>

== What is proper forum etiquette? What rules are there for the forum?==
Proper forum etiquette will ensure you will stay a member of these forums. So try to follow these rules. Also see this [http://www.autoitscript.com/forum/index.php?showtopic=95704&st=15&p=688050&#entry688050 FAQ post], as you should follow what is outlined there as well.

* Use proper English. MSN speak and the like makes it very hard to understand what you want. Keep posts in proper case because UPPERCASE is considered yelling and lowercase makes you look stupid. Don't use more punctuation marks than necessary. For example ?!!!? and ????? is completely unnecessary.
* Before posting help with a script, make sure you follow these steps:
*# Search for your issue.
*#* There are many thousands of posts on this forum, and chances are your question has been asked before. Make sure to use a variety of terms to maximize your results.
*# Read the helpfile
*#* Most if not all things in the help file will have an example (native functions) or two. Give them a go to try see how the functions work. Most of the time it helps!
*# Give it a go
*#* Seriously, if you can't be bothered to give it a go, then why should we be bothered to help you? If you feel you can't do it and you don't try then how will you ever know? We always prefer that you give it a go because you can learn from your mistakes and hopefully understand it better.
*# Post your problem
*#* Make sure you post in the correct forum.
*#** AutoIt Specific
*#*** General Help and Support (Most support questions)
*#*** GUI Support (Support for the Graphical User Interface)
*#** Non-AutoIT
*#*** Chat
*#*** Developer Chat (Usually for C++ questions.)
*#* Include a detailed description in the content of the post, and a detailed title
*#** Titles such as 'Help' and 'What's wrong?' are not acceptable. To get the most help with your problem, be as descriptive as you can in the title, but keep in mind your title cannot be too long.
*#** Make sure you also include a descriptive question. Just saying 'what is wrong with the following' is also not acceptable, as we will have no idea what the problem is. Describe what you think is wrong and what is not working. It makes our job easier.
*#* Always include your code
*#** It shows us that you have tried and gives us a head start with something to play with.
* Usually asking for a script is not taken too well, within reason. Keep in mind that this is a support forum, so please acknowledge that. Most of us would rather that you learn rather than just having a script written for you. If you do need something written for you, maybe try [http://www.rentacoder.com/ RentACoder], as they are more suited to requests.
* Don't PM other members asking for them to look at threads of to help you unless they request it. It is actually quite rude and annoying to receive PMs of that nature.
* Lurk a little before you dive right in. Read a number of posts, or check out the group's archives. Get a feel for the tone of the forum so you can participate accordingly.
* Say online exactly what you would say in person. In other words, if you wouldn't say it to the person's face in front of your Grandmother, you shouldn't type it here.
* Remember your face doesn't show. Words alone can convey sentiment, but without benefit of inflection or facial expression, they can be misconstrued. Use descriptive wording, emoticons or .gifs to ensure your meaning is clear. By the same token, don't jump to conclusions about another person's intent in posting an unclear comment. When in doubt, ask for clarification.
* Be respectful. Internet etiquette is similar to standard etiquette in this area. Appreciate that your opinion is one of many. You can disagree with another person without being disrespectful or rude to other people.
* Ignore Trolls. If you engage in conversation with one, you'll raise your blood pressure and empower the troll. You can't win a flame war, and you can't sway a troll's opinion. Often, they don't even care about the subject. They live for the conflict and nothing more. Trolls are common and not worthy of your time. Ignore their posts no matter how inflammatory and eventually they'll get bored and move on.
* When you have found an answer for your question:
*# Do not edit your post to be blank or to have worthless information. People may be searching for the same issue you have, so be courteous to them by leaving your question there.
*# It is also optional to add the likes of [SOLVED] into the title, and redirecting people to the answer that helped you. It can make the lives of people searching easier.
* Finally follow the rules:
** [http://www.autoitscript.com/forum/forum-6/announcement-13-forum-rules/ Forum rules]
** [http://www.autoitscript.com/forum/index.php?showtopic=54168 Rules for the Chat forum]
** [http://www.autoitscript.com/forum/index.php?showtopic=65889 Rules for asking for source code]
** [http://www.autoitscript.com/forum/index.php?showtopic=37739 General policies and forum settings]

Some general points taken from [http://www.ehow.com/how_2106033_use-proper-forum-etiquette.html here].

==Are there forums available in my local language?==
Yes there are some available. Some forum members here participate in multiple forums.
* [http://www.autoit.de/ German Forums]
* [http://www.autoit.fr/ French Forums]
* [http://www.autoit.es/ Spanish Forums]
* [http://autoit-script.ru/ Russian Forums]

Please note that these are independent, community-run message boards and not just a translation of this board.

User Defined Functions

2012-11-09T01:13:51Z

FlutterShy: /* Internet protocol suite */

{{WIP}}

This page is a listing of libraries of user defined functions. These libraries have been written to allow easy integration into your own script and are a very valuable resource for any programmer.

== Automation ==
* [http://www.autoitscript.com/forum/index.php?showtopic=87956 Java UDF] - Creates an access bridge between your application and a Java application. Allowing you to automate some Java applications.
* [http://www.autoitscript.com/forum/index.php?showtopic=86574 SAP] - SAP business management automation.
* [http://www.autoitscript.com/forum/index.php?showtopic=42776 PDFCreator] - Automation of PDFCreator allows you to create and manipulate PDF files.
* [http://www.autoitscript.com/forum/index.php?showtopic=91018 WiFi] - Low level control over your wireless LAN
* [http://www.autoitscript.com/forum/index.php?showtopic=106163 Active Directory] - Extensive library to control and manipulate the Windows active directory. Link to the [[Active_Directory_UDF_-_General|documentation]] pages.
* [http://www.autoitscript.com/forum/index.php?showtopic=28436 Windows Events] - Create your own Windows events.

===Browsers===
* Internet Explorer - Everything about Internet explorer can be automated with the IE library supplied with a standard AutoIt install.
* [http://www.autoitscript.com/forum/index.php?showtopic=95595 FireFox] - A little less support for automation than IE, but still very good.
* [http://www.autoitscript.com/forum/index.php?showtopic=61090 Opera] - The same as above for Opera. Automate the most common tasks in Opera with the Opera UDF.

===Microsoft Office Automation===
* [http://www.autoitscript.com/forum/index.php?showtopic=32144 Microsoft Office Access] - Automation of Access.
* [http://www.autoitscript.com/forum/index.php?showtopic=34302 Microsoft Office Excel] - Large automation library for Excel.
* [http://www.autoitscript.com/forum/topic/135312-excelchart-udf Microsoft Office Excel] - Creating charts using Excel.
* [http://www.autoitscript.com/forum/topic/126305-outlookex-udf/ Microsoft Office Outlook] - Extended Outlook UDF. Link to the [[OutlookEX_UDF_-_General|documentation]] pages.
* Microsoft Office Word UDF - A way to automate Office Word is included with AutoIt.

== Hardware ==
* [http://www.autoitscript.com/forum/index.php?showtopic=45842 Serial port (COM port)] - Requires my comMG.dll (included)

== Information gathering ==
* [http://www.autoitscript.com/forum/index.php?showtopic=29404 Computer information] - A general purpose library to get various details about a Windows machine.

== Databases and web connections ==
* FTP - A FTP library is now included with the AutoIt libraries.
* [http://www.autoitscript.com/forum/index.php?showtopic=17099 SQLite] - "SQLite is a library that implements a self-contained, embeddable, zero-configuration SQL database engine"
* [http://www.autoitscript.com/forum/index.php?showtopic=19848 XML DOM Wrapper] - Supports CRUD operations on XML. Including XSL and XPath.
* [http://www.autoitscript.com/forum/index.php?showtopic=20814 MySQL] - MySQL relational database management system UDF.

== Internet protocol suite ==
* [http://www.autoitscript.com/forum/topic/84133-winhttp-functions/ HTTP] - For creating GET and POST requests and submitting them with conforming standards.
* [http://www.autoitscript.com/forum/index.php?showtopic=22838 POP3] - POP3 library for retrieving email messages. Not compatible with Gmail because it uses SSL.
* [http://www.autoitscript.com/forum/index.php?showtopic=64051 POP3 SSL] - A POP3 library that's compatible with Gmail. It uses an external executable that must be supplied with your script.
* [http://www.autoitscript.com/forum/index.php?showtopic=43515 IRC] - A lightweight library for communicating with IRC servers.

== Data compression ==
* [http://www.autoitscript.com/forum/index.php?showtopic=116565 zip] - Create ZIP files and unpack ZIP files.
* [http://www.autoitscript.com/forum/index.php?showtopic=85094 7z, zip, gzip, bzip2, tar] - More extensive library than the one above. Uses a external DLL that must be provided with the script.

== Encryption and hash ==
* [http://www.autoitscript.com/forum/index.php?showtopic=76976 MD5,SHA1,CRC32,RC4,BASE64,XXTEA] - Several encryption and hash functions.
* [http://www.autoitscript.com/forum/index.php?showtopic=78745 AES Rijndael] - Very fast AES UDF. Support ECB/CBC/CFB/OFB block cipher mode.

== Media ==
* [http://www.autoitscript.com/forum/index.php?showtopic=94834 Simple DirectMedia Layer UDF] - Adds support for joysticks, CDs, 2D graphics, timers. See [http://www.libsdl.org/ SDL website] for more information.
* [http://www.autoitscript.com/forum/index.php?showtopic=95357 FreeImage library] - Various operations on images, such as rotate, resize, flip.
* [http://www.autoitscript.com/forum/index.php?showtopic=51054 Printer controller] - Print text in any font, size and colour at any position on the page, draw lines, curves, elipses, pies in any colour, and print images.
* [http://www.autoitscript.com/forum/index.php?showtopic=42776 PDF creator]

===Sound===
* [http://www.autoitscript.com/forum/index.php?showtopic=83481 BASS Function Library] - Sound and Music via wrappers for Bass, BassEnc, Bass FX, BassSFX, BassAsio and BassCd DLLs

===3D graphics===
* [http://www.autoitscript.com/forum/index.php?showtopic=70506 IrrLicht] - A 3D graphics engine suitable for creating games.
* [http://www.autoitscript.com/forum/index.php?showtopic=113881 au3Irrlicht2] - Another UDF bringing Irrlicht and au3 together. Historically some kind of a follower of the UDF above, technically with a complete different approach.

== GUI Additions ==
* [http://www.autoitscript.com/forum/index.php?showtopic=32494 XSkin] - A large library that allows skinning of your GUI and to apply custom skins.
* [http://www.autoitscript.com/forum/index.php?showtopic=20967 Modern tray menu] - Allows the creation of modern, fancy GUI and tray menus with icons.
* [http://www.autoitscript.com/forum/index.php?showtopic=71811 SetOnEvent] - Provides an easy way for an event to call functions with parameters.
* [http://www.autoitscript.com/forum/topic/119505-guiframe-udf-melba23-version/ GUIFrame] - Divide a GUI into adjustable frames.
* [http://www.autoitscript.com/forum/topic/113723-scrollbars-made-easy/ Easy Scrollbars] - Easily create scrollable sections in your GUI
* [http://www.autoitscript.com/forum/index.php?showtopic=105582 GUICtrlOnChangeRegister] - Call a function when an edits content is changed.
* [http://www.autoitscript.com/forum/topic/96258-contexthelp-au3/ ContextHelp.au3] - Management of context help ([http://www.autoitscript.com/forum/topic/72152-contexthelp/ original])
* [http://www.autoitscript.com/forum/topic/117909-guiextender-new-version-171110/ GUIExtender] - Expand and contract sections of your GUI
* [http://www.autoitscript.com/forum/topic/109096-extended-message-box-new-version-3-dec-10/ ExtMsgBox] - A very customisable replacement for MsgBox
* [http://www.autoitscript.com/forum/topic/108445-how-to-make-toast/ Toast] - Small message GUIs which pop out of the Systray

=== Controls ===
* [http://www.autoitscript.com/forum/index.php?showtopic=79412 Graph control UDF] - Easily create and show bar chart and line charts.
* [http://www.autoitscript.com/forum/index.php?showtopic=105682 GUICtrlCreateFinder] - Allows you to create a window finder control like the one seen in AutoIt Window Info.
* [http://www.autoitscript.com/forum/index.php?showtopic=111438 GUIPager] - Create and control native pager controls.
* [http://www.autoitscript.com/forum/index.php?showtopic=90598 Hotkey input control] - Hotkeys Input Control UDF Library (Non-native)
* [http://www.autoitscript.com/forum/index.php?showtopic=107965 GUIHotkey] - UDF for using native hotkey controls.
* [http://www.autoitscript.com/forum/topic/103904-info-bar-like-tickertape/page__view__findpost__p__735769 Marquees] - Make tickertape info bars
* [http://www.autoitscript.com/forum/topic/96464-colorpicker-udf/ Colorpicker] - Create a button for the user to select a color.
* [http://www.autoitscript.com/forum/topic/126958-guisyslink-udf/ Syslink] - Provides a convenient way to embed hypertext links in a window
* [http://www.autoitscript.com/forum/topic/74649-progressbar-with-gdiplus/ Progressbar with GDIplus] - You even can use full textured images

== Maths ==
* [http://www.autoitscript.com/forum/index.php?showtopic=83091 Primes UDF] - Many functions dealing with prime number generation and calculations.
* [http://www.autoitscript.com/forum/index.php?showtopic=83529 Big number UDF] - Make calculations with extremely large numbers that AutoIt normally is not able to support.
* [http://www.autoitscript.com/forum/index.php?showtopic=81189 Number base conversion] - From, to and between positive bases less than 63 (decimals supported)
* [http://www.autoitscript.com/forum/index.php?showtopic=106551 Decimal To fraction] - Converts any decimal number to a fraction. Example: 1.2 to 6/5
* [http://www.autoitscript.com/forum/index.php?showtopic=82722 Trigonometry math functions] - _ATan2(), _Cosh(), _Frexp(), _Hypot(), _Ldexp(), _Logb(), _Sinh(), _Tanh()
* [http://www.autoitscript.com/forum/index.php?showtopic=108803 Polynomials] - Functions for using polynomials.
* [http://www.autoitscript.com/forum/index.php?showtopic=117156 NumToWord] - Convert numerals to a human readable string.
* [http://www.autoitscript.com/forum/index.php?showtopic=98160 Root function] - Working out real roots of numbers.
* [http://www.autoitscript.com/forum/topic/102686-advanced-rounding/ Advanced rounding] - Support for different measures of accuracy and 8 ways to resolve tie breaks.

== Misc ==
* [http://www.autoitscript.com/forum/topic/90492-hotkey-au3/ Hotkey.au3] - Management of Hotkeys UDF, with several advantages over HotkeySet().
* [http://www.autoitscript.com/forum/topic/97826-animateau3-updated/ Animated tray icons] - Make animated tray icons easily.
* [http://www.autoitscript.com/forum/topic/101733-prevent-dotted-focus-lines-on-controls/ NoFocusLines] - Remove the dotted focus lines from buttons, sliders, radios and checkboxes which spoil the look of your GUI
* [http://www.autoitscript.com/forum/topic/114034-stringsize-m23/ StringSize] - Automatically size controls to fit the text you want to put in them

SciTE4AutoIt3

2012-11-09T00:57:17Z

FlutterShy: /* Features */

User:FlutterShy

2012-11-09T00:48:02Z

FlutterShy: Created page with "I try to fix grammatical errors, syntax errors as I see and remember them."

I try to fix grammatical errors, syntax errors as I see and remember them.

Tutorial Core Language

2012-11-09T00:46:20Z

FlutterShy: Undo revision 10900 by FlutterShy (talk)

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == 5 Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
Local $i
For $i = 1 to 10 Step 2
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF()
;This does nothing at the moment
EndFunc
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
Func MyUDFReturningResults($arg1, ByRef $arg2)
Local $ret = 1
;Changing $arg2 is a way of returning data
If IsNumeric($arg2) Then
$arg2 = 2*$arg2
Else
$arg2 &= @CRLF & $arg2
EndIf
Return $ret
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Tutorial Core Language

2012-11-09T00:43:57Z

FlutterShy: /* Mathematical Comparison */

This is a tutorial describing the core elements of the AutoIt language.

=Comments=
Two types of comments tend to exist in every language. Comments are simply lines/blocks of code that are meant as guidelines or notes to help understand what the code is doing.

Inline/Single-line comments may be added using a preceeding semicolon.
<syntaxhighlight lang="autoit">
; This is a single-line comment
msgbox(1,"Title","Text") ; This is an inline comment
</syntaxhighlight>
Where as multiline comments are a little less intuitive but just as effective...
<syntaxhighlight lang="autoit">
#comments-start
All code within this block is commented and will not be interpretted at compile/run time.
#comments-end
</syntaxhighlight>
There's also a shorthand method to this.
<syntaxhighlight lang="autoit">
#cs
All code within this block is commented as well.
#ce
</syntaxhighlight>

=Variables=
==Declarations==
A variable is a placeholder in memory where we can store some kind of data. In AutoIt the data is a string, number or reference to an array.
AutoIt has three keywords to declare a variable. Namely Global, Local and Dim. When we declare a variable we set aside some memory for the variable.
All variable names in AutoIt starts with a $ sign. So they are easy spotted in the code.
<syntaxhighlight lang="autoit">
Global $gVar
Local $Var
Dim $i
</syntaxhighlight>
Arrays are simply collections of variables stored under a common name using addresses as a means of defining their position within memory. Similar to defining a variable, the only difference in defining an array is expressing the number of elements to be attributed to that collection.

<syntaxhighlight lang="autoit">
Global $aarr[4] ; 4 elements allocated.
Local $barr[1] ; 1 element allocated.
Dim $carr[3] ; 3 elements allocated. ; Try to avoid Dim, use Global and Local.
</syntaxhighlight>

For more on arrays visit the [[Arrays|Arrays Tutorial]] page.

==Scope==
Generally speaking, scope pertains to the length of time for which a variable is visible or more precisely how long a variable is stored in memory before it returns to a free state. As such, the allocation(declaration) and deallocation(trash collection) of a variable is usually left up to the compiler/interpreter and occasionally is given to the user to play with. As a rule of thumb, all information stored in memory for a program is deallocated upon completion of the program.

Why is this important? Scope allows a developer to track and reuse variable names for multiple occurances. Imagine having to create a unique name for every single variable stored in memory at that point. You would have to compensate for all the variable names used in the operating system, other programs running parallel to yours, and every name in your own script. It wouldn't be long before randomly generated 256 character names would be more efficient than a list of used names.

With this in mind the three methods of declaring a variable explained above have different scopes in mind:
*Global variables are given scope over the entire program's run.
*Local variables have a scope that is immediately related to the block of code they're currently a member of.
*Dim variables are hybrid-like depending upon whether or not the name is already defined in a global variable status:
**Global variable exists of the same name
***Overwrites the Global variable
**Global variable does not exist
***Creates a Local variable for that block

=Assignment=
Assigning a value to a variable is the only way to get things going. Fortunately, AutoIt uses loose typing...

<syntaxhighlight lang="autoit">
Local $x = "Hi there!" ; $x is a string
$x = 7 ; $x is an integer
$x = .15 ; $x is a float
$x = 123456789 ; $x is a double
$x = "Hello again!" ; $x is back to a string
</syntaxhighlight>
Loose typing simply means a variable is malleable and its format can be changed to your liking, this also means that you have to watch your scope and what's going in and out of that variable.

Arrays are handled a bit differently. They may contain several different types and those types are loosely typed but the array must have a predetermined size.

<syntaxhighlight lang="autoit">
Local $y[3]
$y[0] = 1 ; first address is an integer
$y[1] = "two" ; second address is a string
$y[2] = 3.33333 ; third address is a float
</syntaxhighlight>
Equivalently
<syntaxhighlight lang="autoit">
Local $z[3] = [1,"two",3.3333]
</syntaxhighlight>
Again, for more on arrays see the [[Arrays|Arrays Tutorial]].

You may also declare and assign several variables at the same time.
<syntaxhighlight lang="autoit">
Local $x = 1, $y = "", $z[3] = [1,2,3]
</syntaxhighlight>

=Operators=
===Assignment===
<table border="1">
<tr><td> = </td><td>Assignment operator. e.g. $var = 5</td></tr>
<tr><td> &= </td><td>Concatenation assignment. e.g. $var &= "Hello" equivalent to $var = $var & "Hello"</td></tr>
</table>
===Mathematical Operation===
<table border="1">
<tr><td> + </td><td>Addition operator. e.g. 10 + 20</td></tr>
<tr><td> - </td><td>Subtraction operator. e.g. 20 - 10</td></tr>
<tr><td> * </td><td>Multiplication operator. e.g. 20 * 10</td></tr>
<tr><td> / </td><td>Division operator. e.g. 20 / 10</td></tr>
<tr><td> ^ </td><td>Powers operator. e.g. 2 ^ 4</td></tr>
<tr><td> += </td><td>Addition assignment. e.g. $var += 1 is equivalent to $var = $var + 1</td></tr>
<tr><td> -= </td><td>Subtraction assignment. e.g. $var -= 1 is equivalent to $var = $var -1</td></tr>
<tr><td> *= </td><td>Multiplicative assignment. e.g. $var *= 2 is equivalent to $var = $var * 2</td></tr>
<tr><td> /= </td><td>Divisive assignment. e.g. $var /= 2 is equivalent to $var = $var / 2</td></tr>
</table>

===Mathematical Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator for numerical values. e.g. If $var = 5 Then ...</td></tr>
<tr><td> == </td><td>Equivalence operator for string values. e.g. If $string == "string" Then ...</td></tr>
<tr><td> <> </td><td>Not equal operator. e.g. If $var <> 5 Then ...</td></tr>
<tr><td> > </td><td>Greater-than operator. e.g. If $var > 5 Then ...</td></tr>
<tr><td> >= </td><td>Greater-than-or-Equal-to operator. e.g. If $var >= 5 Then ...</td></tr>
<tr><td> < </td><td>Less-than operator. e.g. If $var < 5 Then ...</td></tr>
<tr><td> <= </td><td>Less-than-or-Equal-to operator. e.g. If $var <= 5 Then ...</td></tr>
</table>

===String Comparison===
<table border="1">
<tr><td> = </td><td>Equivalence operator. e.g. If $var = "Hi" Then ... ; case insensitive.</td></tr>
<tr><td> == </td><td>Equivalence operator. e.g. If $var == "Bye" Then ... ; case sensitive.</td></tr>
<tr><td> <> </td><td>Not equivalent operator. e.g. If $var <> "blah" Then ... ; case insensitive.</td></tr>
<tr><td>Not <></td><td>Not equivalent combinative operator. e.g. If Not $var <> "blah" Then ... ; case sensitive.</td></tr>
</table>

===Logical===
<table border="1">
<tr><td> And </td><td>Binary logical And operator. e.g. If $var > 5 And $var < 3 Then ...</td></tr>
<tr><td> Or </td><td>Binary logical Or operator. e.g. If $var <> 5 Or $var <> 6 Then ...</td></tr>
<tr><td> Not </td><td>Unary inversion operator. e.g. If Not $var > 5 Then ...</td></tr>
</table>

===Precedence===
All languages have a list of precedences that define when an operator is to be evaluated. Operators with equal precedence are evaluated from ''left'' to ''right''.
From highest to lowest:
<syntaxhighlight lang="autoit">
'''Not'''
''' ^ '''
'''* /'''
'''+ -'''
''' & '''
'''< > <= >= = <> =='''
'''And Or'''
</syntaxhighlight>
It should be noted that the use of And/Or operators evaluate from left to right such that
<syntaxhighlight lang="autoit">
If $x < 5 And $x > 3 Then
</syntaxhighlight>
checks the ''$x < 5'' first and if it returns false will not evaluate ''$x > 3''.

Similarly for Or
<syntaxhighlight lang="autoit">
If $x <> 5 Or $x <> 6 Then
</syntaxhighlight>
will evaluate ''$x <> 5'' and if it returns true will not evaluate ''$x <> 6''

All tables and information adapted from the [http://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm AutoIt intro].

=Branching=
Branching is to let the computer compare something and based on the result let it execute a block of code.
Autoit has three keywords for identifying branching. They are If, Select and Switch. In addition there are several sub keywords to identify the comparing code and assosiated block of code.
==If-ElseIf-Else==
When a test returns a true statement then execute code block down to the assosiated ElseIf, Else or EndIf keyword. If Else or Else if was encountered then jump to the EndIf Line.

<syntaxhighlight lang="autoit">
Local $x = 1

If $x = 1 Then
;Code block
EndIf

If $x < 2 Then
;Code block
ElseIf $x >= 3 Then
;Code block
Else
;Code block
EndIf
</syntaxhighlight>
There also exists a shorthand method of the If statement:
<syntaxhighlight lang="autoit">
If true = 1 then MsgBox(1,"Is it true?","Yarp!")
</syntaxhighlight>

==Select==
''Select'' is simply a (arguably) more readable version of an if-elseif-else statement.
<syntaxhighlight lang="autoit">
Select
Case $var = 1
;Code block
Case $var = 2
;Code block
Case Else
;Code block
EndSelect
</syntaxhighlight>

==Switch==
The Switch statement contains an interesting difference to most languages. In AutoIt's case, it is equivalent to the Select statement. Once a block of code is executed the Switch statement exits. Unlike most other languages, a ''break'' is not required at the end of each case to avoid trickle-down. This may be considered disadvantageous due to the lack of multi-conditional executions that the Switch statement is generally used for.
<syntaxhighlight lang="autoit">
Switch $var
Case 1
;Code block
Case 2
;Code block
Case Else
;Code block
EndSwitch
</syntaxhighlight>

=Loops=
A loop is used on a code block that we want to execute several times. In the codebloc we can have variables changing state for each iteration in the loop.
AutoIt has four types of loops. For...Next, For Each, While...Wend and Do ... Until
==For ... Next==
<syntaxhighlight lang="autoit">
Local $i
For $i = 1 to 10 Step 2
Next
</syntaxhighlight>

==While ... WEnd==
<syntaxhighlight lang="autoit">
While $var < 100
Sleep(100)
$var += 1
WEnd
</syntaxhighlight>

==Do ... Until==
<syntaxhighlight lang="autoit">
A Do .. Until block will run at least once as the conditional check is done at the bottom of the block.
Do
Sleep(100)
$var += 1
Until $var = 100
</syntaxhighlight>
The code inside this Do ... Until block should only run once
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until True
</syntaxhighlight>
This sample will run until we forcefully us a ExitLoop command to escape the loop
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
If $c = 2 Then ExitLoop
Until False
</syntaxhighlight>
This sample should run until $c equals 3
<syntaxhighlight lang="autoit">
Local $c
Do
$c += 1
ConsoleWrite("Run nr " & $c & @crlf)
Until $c=3
</syntaxhighlight>

==For Each==
The For Each loop is often used for associative arrays however it is often handy when you don't know the size of your current array. In this case, the syntax and implementation is very similar to javascript which is slightly off the standard.
Assume we have an array $arr of undetermined size:
<syntaxhighlight lang="autoit">
Local $str = ""
for $stuff in $arr ; for each item in our array
$str &= $stuff ; copy the item into our string
Next
MsgBox(1,"",$str) ; displays the contents of our string
</syntaxhighlight>

=User defined functions=
A function is a code block encapsulated by the keywords Func and EndFunc. Everytime you find yourselfe writing the same code again you can do three things. Write the code. Copy and paste the previously written code or wrap the code up in a function and call the function by name in your code.
==Defining==
<syntaxhighlight lang="autoit">
Func MySimplestUDF()
;This does nothing at the moment
EndFunc
</syntaxhighlight>

==Passing data==
<syntaxhighlight lang="autoit">
Func MyUDFAcceptingArguments($arg1, ByRef $arg2)
EndFunc
</syntaxhighlight>

==Returning data==
<syntaxhighlight lang="autoit">
Func MyUDFReturningResults($arg1, ByRef $arg2)
Local $ret = 1
;Changing $arg2 is a way of returning data
If IsNumeric($arg2) Then
$arg2 = 2*$arg2
Else
$arg2 &= @CRLF & $arg2
EndIf
Return $ret
EndFunc
</syntaxhighlight>

=File I/O=

==INI Files==

Using IniWrite & IniRead to store values. Useful for scripts that run from independent source (network, USB Drive, etc..).

Write:
<syntaxhighlight lang="autoit">
IniWrite("FileName.INI", "Section", "Key", "Value")
</syntaxhighlight>
Read:
<syntaxhighlight lang="autoit">
$MyVar = IniRead("FileName.INI", "Section", "Key", "Default"); If INI data missing, $MyVar set to "Default"
</syntaxhighlight>

Sample "FileName.INI":
<syntaxhighlight lang="autoit">
[Section]
Key=Value
</syntaxhighlight>

<nowiki>***TODO: File I/O stuffs***</nowiki>

Arrays

2012-11-09T00:28:47Z

FlutterShy: /* Comparing Arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax Local $data="Element 1|Element 2|Element 3" ; The string in data will be split into an array everywhere | is encountered Local $arr = StringSplit($data, "|") If IsArray($arr) Then $iMax = UBound($arr); get array size ConsoleWrite("Items in the array: " & $iMax & @LF) For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error ConsoleWrite($arr[$i] & @LF) Next EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array stored in the element. You have to go through a variable to get access to the embedded array which may make your code overly complicated and difficult to debug.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

That said, here is an example.
<syntaxhighlight lang="autoit">Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:
<syntaxhighlight lang="autoit">
$NewArray = $OldArray
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array[1] = "Element 1"
</syntaxhighlight>
Or
<syntaxhighlight lang="autoit">
$Content = $Array[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
Local $Array1[3] = [1, 2, 3]
Local $Array2[3] = [1, 2, 3]

If $Array1 = $Array2 then
ConsoleWrite("+>Array is equal!" & @LF)
Else
ConsoleWrite("!>Array is not equal!" & @LF)
EndIf
</syntaxhighlight>

I have the impression that such comparisons compare the memory address of the arrays instead of the array elements values. And the addresses are always different for different arrays.
<br/>
You have to instead, compare all elements one after the other. It might be a good idea to first compare array sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-09T00:21:06Z

FlutterShy: /* Accessing Arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax Local $data="Element 1|Element 2|Element 3" ; The string in data will be split into an array everywhere | is encountered Local $arr = StringSplit($data, "|") If IsArray($arr) Then $iMax = UBound($arr); get array size ConsoleWrite("Items in the array: " & $iMax & @LF) For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error ConsoleWrite($arr[$i] & @LF) Next EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array stored in the element. You have to go through a variable to get access to the embedded array which may make your code overly complicated and difficult to debug.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

That said, here is an example.
<syntaxhighlight lang="autoit">Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:
<syntaxhighlight lang="autoit">
$NewArray = $OldArray
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array[1] = "Element 1"
</syntaxhighlight>
Or
<syntaxhighlight lang="autoit">
$Content = $Array[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-09T00:13:07Z

FlutterShy: /* Arrays in arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax Local $data="Element 1|Element 2|Element 3" ; The string in data will be split into an array everywhere | is encountered Local $arr = StringSplit($data, "|") If IsArray($arr) Then $iMax = UBound($arr); get array size ConsoleWrite("Items in the array: " & $iMax & @LF) For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error ConsoleWrite($arr[$i] & @LF) Next EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array stored in the element. You have to go through a variable to get access to the embedded array which may make your code overly complicated and difficult to debug.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

That said, here is an example.
<syntaxhighlight lang="autoit">Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-09T00:10:55Z

FlutterShy: /* Arrays in arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax Local $data="Element 1|Element 2|Element 3" ; The string in data will be split into an array everywhere | is encountered Local $arr = StringSplit($data, "|") If IsArray($arr) Then $iMax = UBound($arr); get array size ConsoleWrite("Items in the array: " & $iMax & @LF) For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error ConsoleWrite($arr[$i] & @LF) Next EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array, stored in the element, again. You have to go through a variable to get access to the embedded array.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely have to and are prepared to do rigorous testing to make sure your code will always work as you expect it to.

That said, here is an example.
<syntaxhighlight lang="autoit">Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-08T23:58:39Z

FlutterShy: /* Multi dimensional arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax Local $data="Element 1|Element 2|Element 3" ; The string in data will be split into an array everywhere | is encountered Local $arr = StringSplit($data, "|") If IsArray($arr) Then $iMax = UBound($arr); get array size ConsoleWrite("Items in the array: " & $iMax & @LF) For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error ConsoleWrite($arr[$i] & @LF) Next EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array, stored in the element, again. You have to go through a variable to get access to the embedded array.

Remember this. There are issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, do not use arrays embedded in an array unless you absolutely have to, and are prepared to do rigorously testing to make sure your code work as you expect it to.

That said, here is an example
<syntaxhighlight lang="autoit">
Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $i , $j
Local $dumy
For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!UPS, What happened? Expected an array" & @LF)
EndIf
Next
</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-08T22:57:54Z

FlutterShy: /* Changing array sizes with ReDim */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax Local $data="Element 1|Element 2|Element 3" ; The string in data will be split into an array everywhere | is encountered Local $arr = StringSplit($data, "|") If IsArray($arr) Then $iMax = UBound($arr); get array size ConsoleWrite("Items in the array: " & $iMax & @LF) For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error ConsoleWrite($arr[$i] & @LF) Next EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi dimensional array?
It could be a table where you access one item in the table at the time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
Local $i, $j
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
But you can add dimensions, how many was not mentioned in the help files limits page as of writing. But drop me a note if you find a problem where it is easier to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit">; NOTE: Then next line is supposed to be on one line
Local $arr[3][3][3][3] = [[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]]],[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]]]

Local $i, $j, $k, $l
For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & _
"][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array, stored in the element, again. You have to go through a variable to get access to the embedded array.

Remember this. There are issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, do not use arrays embedded in an array unless you absolutely have to, and are prepared to do rigorously testing to make sure your code work as you expect it to.

That said, here is an example
<syntaxhighlight lang="autoit">
Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $i , $j
Local $dumy
For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!UPS, What happened? Expected an array" & @LF)
EndIf
Next
</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-08T22:26:48Z

FlutterShy: /* Accessing Data in Arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax Local $data="Element 1|Element 2|Element 3" ; The string in data will be split into an array everywhere | is encountered Local $arr = StringSplit($data, "|") If IsArray($arr) Then $iMax = UBound($arr); get array size ConsoleWrite("Items in the array: " & $iMax & @LF) For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error ConsoleWrite($arr[$i] & @LF) Next EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of itterations. If the array are to small it should automatically be increased. Before we dump the array to output, we should adjust the it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
Local $i
;Get a random number between 0 and 20
Local $rnd = Random(0, 20, 1)
For $i = 1 to $rnd
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i
; Remember to update the count or last item
$arr[0] = $i
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0]
ReDim $arr[$arr[0]+1]
;Now dump the result
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $rnd:=" & $rnd & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi dimensional array?
It could be a table where you access one item in the table at the time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
Local $i, $j
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
But you can add dimensions, how many was not mentioned in the help files limits page as of writing. But drop me a note if you find a problem where it is easier to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit">; NOTE: Then next line is supposed to be on one line
Local $arr[3][3][3][3] = [[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]]],[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]]]

Local $i, $j, $k, $l
For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & _
"][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array, stored in the element, again. You have to go through a variable to get access to the embedded array.

Remember this. There are issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, do not use arrays embedded in an array unless you absolutely have to, and are prepared to do rigorously testing to make sure your code work as you expect it to.

That said, here is an example
<syntaxhighlight lang="autoit">
Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $i , $j
Local $dumy
For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!UPS, What happened? Expected an array" & @LF)
EndIf
Next
</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-08T22:18:53Z

FlutterShy: /* Accessing Data in Arrays */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.<br>
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
$iMax = UBound($arr); get array size
ConsoleWrite("Items in the array: " & $iMax)
For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of StringSplit thought it was a good idea to use the first item, item 0, to keep a count of valid items in the array. This makes sense in many situations as you now have a array containing data with a index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of itterations. If the array are to small it should automatically be increased. Before we dump the array to output, we should adjust the it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
Local $i
;Get a random number between 0 and 20
Local $rnd = Random(0, 20, 1)
For $i = 1 to $rnd
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i
; Remember to update the count or last item
$arr[0] = $i
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0]
ReDim $arr[$arr[0]+1]
;Now dump the result
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $rnd:=" & $rnd & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi dimensional array?
It could be a table where you access one item in the table at the time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
Local $i, $j
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
But you can add dimensions, how many was not mentioned in the help files limits page as of writing. But drop me a note if you find a problem where it is easier to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit">; NOTE: Then next line is supposed to be on one line
Local $arr[3][3][3][3] = [[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]]],[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]]]

Local $i, $j, $k, $l
For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & _
"][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array, stored in the element, again. You have to go through a variable to get access to the embedded array.

Remember this. There are issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, do not use arrays embedded in an array unless you absolutely have to, and are prepared to do rigorously testing to make sure your code work as you expect it to.

That said, here is an example
<syntaxhighlight lang="autoit">
Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $i , $j
Local $dumy
For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!UPS, What happened? Expected an array" & @LF)
EndIf
Next
</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-08T21:58:18Z

FlutterShy: /* Assigning Data to Array Elements */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $i
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The 3 - 1 construct used in the last sample looked strange. It is not a good idea to hardcode size like that. So lets improve our sample a litle bit.
<source lang=autoit>
Local $iMax=3
Local $i
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that is a bit cleaner. It is also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because you get the array from somewhere else.<br>
<source lang=autoit>
Local $iMax
Local $i
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
Local $iMax = UBound($arr)
ConsoleWrite("Items in the array: " & $iMax)
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of StringSplit thought it was a good idea to use the first item, item 0, to keep a count of valid items in the array. This makes sense in many situations as you now have a array containing data with a index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $i
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create a array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array as reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While itterating with $arr[0] needs no other change than maintaining the correct
count in $arr[0]
<source lang=autoit>
Local $iMax=10
Local $i
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of itterations. If the array are to small it should automatically be increased. Before we dump the array to output, we should adjust the it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
Local $i
;Get a random number between 0 and 20
Local $rnd = Random(0, 20, 1)
For $i = 1 to $rnd
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i
; Remember to update the count or last item
$arr[0] = $i
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0]
ReDim $arr[$arr[0]+1]
;Now dump the result
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $rnd:=" & $rnd & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi dimensional array?
It could be a table where you access one item in the table at the time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
Local $i, $j
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
But you can add dimensions, how many was not mentioned in the help files limits page as of writing. But drop me a note if you find a problem where it is easier to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit">; NOTE: Then next line is supposed to be on one line
Local $arr[3][3][3][3] = [[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]]],[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]]]

Local $i, $j, $k, $l
For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & _
"][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array, stored in the element, again. You have to go through a variable to get access to the embedded array.

Remember this. There are issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, do not use arrays embedded in an array unless you absolutely have to, and are prepared to do rigorously testing to make sure your code work as you expect it to.

That said, here is an example
<syntaxhighlight lang="autoit">
Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $i , $j
Local $dumy
For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!UPS, What happened? Expected an array" & @LF)
EndIf
Next
</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-08T21:32:04Z

FlutterShy: /* Array UDF: array.au3 */

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts it's index at 0. So, the first element in the array referenced by a 0.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. Ex: An array with 3 elements has a last index of 2.

If you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get a "out of bounds error".

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $i
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The 3 - 1 construct used in the last sample looked strange. It is not a good idea to hardcode size like that. So lets improve our sample a litle bit.
<source lang=autoit>
Local $iMax=3
Local $i
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that is a bit cleaner. It is also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because you get the array from somewhere else.<br>
<source lang=autoit>
Local $iMax
Local $i
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
Local $iMax = UBound($arr)
ConsoleWrite("Items in the array: " & $iMax)
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of StringSplit thought it was a good idea to use the first item, item 0, to keep a count of valid items in the array. This makes sense in many situations as you now have a array containing data with a index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $i
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create a array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array as reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While itterating with $arr[0] needs no other change than maintaining the correct
count in $arr[0]
<source lang=autoit>
Local $iMax=10
Local $i
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of itterations. If the array are to small it should automatically be increased. Before we dump the array to output, we should adjust the it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
Local $i
;Get a random number between 0 and 20
Local $rnd = Random(0, 20, 1)
For $i = 1 to $rnd
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i
; Remember to update the count or last item
$arr[0] = $i
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0]
ReDim $arr[$arr[0]+1]
;Now dump the result
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $rnd:=" & $rnd & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi dimensional array?
It could be a table where you access one item in the table at the time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
Local $i, $j
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
But you can add dimensions, how many was not mentioned in the help files limits page as of writing. But drop me a note if you find a problem where it is easier to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit">; NOTE: Then next line is supposed to be on one line
Local $arr[3][3][3][3] = [[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]]],[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]]]

Local $i, $j, $k, $l
For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & _
"][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array, stored in the element, again. You have to go through a variable to get access to the embedded array.

Remember this. There are issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, do not use arrays embedded in an array unless you absolutely have to, and are prepared to do rigorously testing to make sure your code work as you expect it to.

That said, here is an example
<syntaxhighlight lang="autoit">
Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $i , $j
Local $dumy
For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!UPS, What happened? Expected an array" & @LF)
EndIf
Next
</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?

Arrays

2012-11-08T20:41:06Z

FlutterShy:

== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts it's index at 0. So, the first element in the array referenced by a 0.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. Ex: An array with 3 elements has a last index of 2.

If you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get a "out of bounds error".

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $i
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The 3 - 1 construct used in the last sample looked strange. It is not a good idea to hardcode size like that. So lets improve our sample a litle bit.
<source lang=autoit>
Local $iMax=3
Local $i
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that is a bit cleaner. It is also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because you get the array from somewhere else.<br>
<source lang=autoit>
Local $iMax
Local $i
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
Local $iMax = UBound($arr)
ConsoleWrite("Items in the array: " & $iMax)
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of StringSplit thought it was a good idea to use the first item, item 0, to keep a count of valid items in the array. This makes sense in many situations as you now have a array containing data with a index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $i
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create a array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array as reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While itterating with $arr[0] needs no other change than maintaining the correct
count in $arr[0]
<source lang=autoit>
Local $iMax=10
Local $i
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of itterations. If the array are to small it should automatically be increased. Before we dump the array to output, we should adjust the it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
Local $i
;Get a random number between 0 and 20
Local $rnd = Random(0, 20, 1)
For $i = 1 to $rnd
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i
; Remember to update the count or last item
$arr[0] = $i
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0]
ReDim $arr[$arr[0]+1]
;Now dump the result
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $rnd:=" & $rnd & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi dimensional array?
It could be a table where you access one item in the table at the time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
Local $i, $j
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
But you can add dimensions, how many was not mentioned in the help files limits page as of writing. But drop me a note if you find a problem where it is easier to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit">; NOTE: Then next line is supposed to be on one line
Local $arr[3][3][3][3] = [[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]]],[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], _
[[1, 2, 3],[2, 3, 4],[3, 4, 5]],[[1, 2, 3],[2, 3, 4],[3, 4, 5]]]]

Local $i, $j, $k, $l
For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & _
"][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array, stored in the element, again. You have to go through a variable to get access to the embedded array.

Remember this. There are issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, do not use arrays embedded in an array unless you absolutely have to, and are prepared to do rigorously testing to make sure your code work as you expect it to.

That said, here is an example
<syntaxhighlight lang="autoit">
Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $i , $j
Local $dumy
For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!UPS, What happened? Expected an array" & @LF)
EndIf
Next
</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:<br/>
<syntaxhighlight lang="autoit">
$Array1=$Array1 .
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array1[1]="blabla"
</syntaxhighlight>or<br/>
<syntaxhighlight lang="autoit">
$Content=$Array1[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
if $Array1 == $Array2 then $OK="equal"
</syntaxhighlight>I have the impressionthat such comparisions compare the memory adress of the arrays instead of the array elements values. And the adresses are always different for different arrays.
<br/>
You have, instead to compare all elements one after the other. It might be a good idea to first compare arry sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIT features a large list of User-Defined Functions (UDF), amoung is a module supplying extra array functions. You can find a reference on those functions in AutoIT's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==
== TODO ==
Update information about UBound($arr, 0).
Create a section with utility functions? Include _ArrayWalk by @Saunders(http://www.autoitscript.com/forum/index.php?s=&showtopic=53390&view=findpost&p=410283)?