AutoHotkeyU

From AutoHotkey

AutoHotkeyU is a Unicode version of AutoHotkey based on AutoHotkey_L. It also provides some additional features. Windows versions prior to Windows 2000 are not supported.

The codes has been merged into AutoHotkey_L start from L42.

Contents 1 Script file encodings 2 Script compatibility 2.1 Internal format to store strings 2.2 Transform, OutputVar, Unicode 2.3 If var is 3 Features 3.1 Built-in variables 3.1.1 A_IsUnicode 3.1.2 A_OSVersion 3.2 Built-in functions 3.2.1 DllCall 3.2.2 PtrSize 3.2.3 StrGet 3.2.4 FileOpen 3.3 Objects 3.3.1 File 3.3.1.1 Methods 3.4 Commands 3.4.1 Transform 3.4.1.1 ToCodePage 3.4.1.2 FromCodePage 3.4.1.3 HTML 3.4.2 FileRead 3.4.3 FileReadLine 3.4.4 Loop, Read 3.4.5 FileAppend 3.4.6 FileEncoding 3.4.7 SendInput 3.4.8 SetFormat 3.5 Datatypes 3.5.1 WStr 3.5.2 AStr 3.5.3 Ptr 4 See also 5 External links

[edit] Script file encodings

• Scripts with a UTF-8 or UTF-16LE BOM are recognized.
• The default code page (for the files without BOM) to load script files is determined by the AutoHotkey.exe file name. If it begins with AutoHotkeyU (e.g. AutoHotkeyU.exe, case-insensitive) the default is UTF-8, otherwise the system code page is used.
• The compiled version (AutoHotkeySC.bin) supports UTF-8 only. The other encodings are not supported, including the system code page.

[edit] Script compatibility

[edit] Internal format to store strings

Strings are stored in UTF-16 format, which is the native format in current Windows systems. A character consumes (at least) two bytes in this format, so if a script calls functions via DllCall() that take some strings as its parameters, it should call the Unicode version of such function instead. See below for examples.

This doesn't work in the Unicode version:

DllCall("kernel32\DeleteFileA", "UInt", &filename)
DllCall("kernel32\DeleteFileA", "str", filename)

This doesn't work in the ANSI version (However, the last line should work in the ANSI builds of AutoHotkey_L >=L42):

DllCall("kernel32\DeleteFileW", "UInt", &filename)
DllCall("kernel32\DeleteFileW", "str", filename)
DllCall("kernel32\DeleteFileA", "astr", filename)

This should work on both versions:

DllCall("DeleteFile", "UInt", &filename)
DllCall("DeleteFile", "str", filename) 

However, it is recommend to use this style, since it works with any DLL in ANSI/Unicode build.

DllCall("kernel32\DeleteFile",  "UInt", &filename)
DllCall("kernel32\DeleteFile",  "str", filename)

Note that older versions of AutoHotkey_L and official AutoHotkey will add "A" or "W" for the DLLs listed in the manual only.

In addition, buffers to store strings should be enlarged as well.

[edit] Transform, OutputVar, Unicode

It has been replaced by ToCodePage and FromCodePage.

[edit] If var is

This command ignores the system locale by default, since it is only suitable for some users. Use StringCaseSense, Locale to enable it.

[edit] Features

[edit] Built-in variables

[edit] A_IsUnicode

Always 1 in AutoHotkeyU.

[edit] A_OSVersion

Windows 7 support has been added, it returns WIN_7 on such system.

[edit] Built-in functions

[edit] DllCall

For function name lookups, it appends "W" instead of "A" when the function is not found. This mechanism is always applied (the official version ignores this when the function is not in user32.dll, kernel32.dll, comctl32.dll or gdi32.dll).

[edit] PtrSize

Returns the size of a pointer. (For 64bit compatibility, see also IntPtr)

PtrSize(num = 1)

• Parameters
  1. num: Number of pointers.
• Return value

The size of a pointer multiplied by num (in bytes).

[edit] StrGet

Returns a Unicode string from a memory address. This function solves the problem described in this forum post. The address must be a valid address or NULL, otherwise it can crash.

StrGet(address)

• Return value

The null-terminated string in address.

[edit] FileOpen

EXPERIMENTAL

Open a file.

FileOpen(filename, flags[, codepage])

• Parameters
  1. filename: The file name to open.
  2. flags: The combination (bitwise OR) of the values described below.
  3. codepage: The code page of the file. The default is set by the FileEncoding command. However, the BOM will be checked first if the file exists.

Access mode flags (only one of them could be used):

0x00: read. Fails when the file doesn't exist.
0x01: write. Creates a new file. The content of existing file will be lost.
0x02: append. Creates a new file if the file didn't exist.
0x03: update (read/write). Fails when the file doesn't exist.

End of line (EOL) options:

0x04: Convert between LFs and CRLF pairs when reading and writing.
0x08: Convert standalone CRs to LFs when reading.

Byte order mark (BOM) options (a BOM is added when a zero-length file is opened for writing/appending/updating):

0x10: UTF-8 (EF BB BF)
0x20: UTF-16LE (FF FE)

• Return value

An instance of a File object. Use IsObject() to check if it is opened successfully.

[edit] Objects

[edit] File

EXPERIMENTAL

File is an object type that provides an interface to access files. Use FileOpen to instantiate it.

[edit] Methods

Read

Read the specified number of characters from the file.

file.Read(characters)

• Parameters
  1. characters: Number of characters to read.
• Return value

The string read from the file.

ReadLine

Read a line from the file.

file.ReadLine()

• Return value

The string read from the file (including the new line character).

Write

Write a string to the file.

file.Write(string)

• Parameters
  1. string: The string to write.
• Return value

Number of bytes (not characters) that have been written.

RawRead

Read raw binary data from the file (without any kind of conversions). The user must ensure that the buffer is large enough to hold the data (see VarSetCapacity).

file.RawRead(VarOrAddress, bytes)

• Parameters
  1. VarOrAddress: A variable or a memory address in which the data will be read (see NumGet).
  2. bytes: Number of bytes to read.
• Return value

The number of bytes that have been read.

RawWrite

Write raw binary data to the file.

file.RawWrite(VarOrAddress, bytes)

• Parameters
  1. VarOrAddress: A variable or a memory address that contains the data (see NumPut).
  2. bytes: Number of bytes to write.
• Return value

The number of bytes that have been written.

Seek

Moves the file pointer.

file.Seek(distance[, origin = 0])

• Parameters
  1. distance: The length in bytes to move. Negative values means moving back.
  2. origin: Specifies the mode in which the file pointer will be mode. It must be one of the following values.
     • 0 (SEEK_SET): Beginning of the file.
     • 1 (SEEK_CUR): Current position of the file pointer.
     • 2 (SEEK_END): End of file.
• Return value

Returns 1 (true) on success, otherwise, returns 0.

Tell

file.Tell()

• Return value

Returns the current position of the file pointer.

Length

file.Length([length])

• Parameters
  1. length: If specified, the file will be resized to length bytes.
• Return value

Returns the size of the file.

AtEOF

Checks if the file pointer is at the end of file.

file.AtEOF()

• Return value

Returns 1 (true) when the file pointer reaches the end of file, otherwise, returns 0 (false).

Close

Closes the file. This should flush the data in the cache to the disk and release the share locks. Although the file is closed automatically when the object is freed by AutoHotkey, it is recommended to close the file as soon as possible.

file.Close()

• Return value

No return value.

__Handle

file.__Handle()

• Return value

Returns the system file handle (CreateFile).

[edit] Commands

[edit] Transform

[edit] ToCodePage

Converts the native Unicode string to specified code page. Specify value 0 as the code page number to use the system code page.

Transform, OutputVar, ToCodePage, codepage, StringToConvert

[edit] FromCodePage

Converts the string from specified code page to native Unicode format. Specify value 0 as the code page number to use the system code page. StringToConvert can be an expression.

Transform, OutputVar, FromCodePage, codepage, StringToConvert

[edit] HTML

The fourth argument has been added, which is optional. The value is the combination (bitwise OR) of the values described below.

Transform, OutputVar, HTML, StringToConvert[, flags]

Optional flags:

• 0x01: Converts to named expressions if possible. e.g. € is converted to €
• 0x02: Converts to numbered expressions. e.g. € is converted to €

It affects non-ASCII characters only. If both named conversion and numbered conversion are specified, named expressions takes precedence over numbered expressions. Note <, >, ", &, and line feed (\n) are always converted.

[edit] FileRead

File encoding could be specified as *P<CODE PAGE NUMBER>, note that it does not work if *C is also specified. It also checks the BOM. Use *C to read in binary mode (bypass EOL and code page translations).

FileRead, OutputVar, *P[nnn] Filename

[edit] FileReadLine

[edit] Loop, Read

When BOM is not provided, use the code page specified by FileEncoding.

[edit] FileAppend

An additional argument has been added to specify its encoding.

 FileAppend [, Text, Filename, UTF-8|UTF-16|UTF-8-RAW]

[edit] FileEncoding

Set the default encoding for FileRead, FileReadLine, Loop, Read, FileAppend, and FileOpen.

FileEncoding [CPnnn|UTF-8|UTF-8-RAW|UTF-16|UTF-16-RAW]

[edit] SendInput

SendInput can send Unicode characters (> U+007F) directly ({U+XXXX} notation isn't required).

[edit] SetFormat

Set the format as H (uppercase) or h (lowercase) will affect the letters (uppercase or lowercase) in hexadecimal numbers.

[edit] Datatypes

[edit] WStr

[edit] AStr

(Only available in DllCall()) There are two new argument types "WStr" and "AStr" (i.e. Unicode strings and ANSI strings). In this version, "Str" is just an alias of "WStr".

[edit] Ptr

(IntPtr in the existing AutoHotkeyU releases)

New data type "Ptr" for DllCall()/NumGet()/NumPut(), it specifies an integer with the same size as a pointer. Using this data type specifies clearly that we're passing a memory address, additionally if someday a 64-bit port is done, the script should still work without any change (if there is no hard coded address computation that expect a pointer is 32-bit).

[edit] See also

• Unicode
• Windows code page
• Byte order mark (BOM)
• AutoHotkey_L vs AutoHotkeyU

[edit] External links

• Discussion thread (with downloads)
• Source code (gitweb)