DESCRIPTION

Windows NT/2000/XP does not support ANSI escape sequences in Win32 Console applications. This module emulates an ANSI console for the script that uses it and also converts the characters from Windows code page to DOS code page (the so-called ANSI to OEM conversion). This conversion permits the display of the accented characters in the console like in the Windows- based editor used to type the script.

Escape sequences for Cursor Movement

\e[#A

CUU: CUrsor Up: Moves the cursor up by the specified number of lines without changing columns. If the cursor is already on the top line, this sequence is ignored. \e[A is equivalent to \e[1A.

\e[#B

CUD: CUrsor Down: Moves the cursor down by the specified number of lines without changing columns. If the cursor is already on the bottom line, this sequence is ignored. \e[B is equivalent to \e[1B.

\e[#C

CUF: CUrsor Forward: Moves the cursor forward by the specified number of columns without changing lines. If the cursor is already in the rightmost column, this sequence is ignored. \e[C is equivalent to \e[1C.

\e[#D

CUB: CUrsor Backward: Moves the cursor back by the specified number of columns without changing lines. If the cursor is already in the leftmost column, this sequence is ignored. \e[D is equivalent to \e[1D.

\e[#E

CNL: Cursor Next Line: Moves the cursor down the indicated # of rows, to column 1. \e[E is equivalent to \e[1E.

\e[#F

CPL: Cursor Preceding Line: Moves the cursor up the indicated # of rows, to column 1. \e[F is equivalent to \e[1F.

\e[#G

CHA: Cursor Horizontal Absolute: Moves the cursor to indicated column in current row. \e[G is equivalent to \e[1G.

\e[#;#H

CUP: CUrsor Position: Moves the cursor to the specified position. The first # specifies the line number, the second # specifies the column. If you do not specify a position, the cursor moves to the home position: the upper-left corner of the screen (line 1, column 1).

\e[#;#f

HVP: Horizontal and Vertical Position. Works in the same way as the preceding escape sequence.

\e[s

SCP: Save Cursor Position: Saves the current cursor position. You can move the cursor to the saved cursor position by using the Restore Cursor Position sequence.

\e[u

RCP: Restore Cursor Position: Returns the cursor to the position stored by the Save Cursor Position sequence.

Escape sequences for Display Edition

\e[#J

ED: Erase Display:

\e[0J

Clears the screen from cursor to end of display. The cursor position is unchanged.

\e[1J

Clears the screen from start to cursor. The cursor position is unchanged.

\e[2J

Clears the screen and moves the cursor to the home position (line 1, column 1).

\e[J is equivalent to \e[0J. (Some terminal/emulators respond to \e[J as if it were \e[2J. Here, the default is 0; it is the norm)

\e[#K

EL: Erase Line:

\e[0K

Clears all characters from the cursor position to the end of the line (including the character at the cursor position). The cursor position is unchanged.

\e[1K

Clears all characters from start of line to the cursor position. (including the character at the cursor position). The cursor position is unchanged.

\e[2K

Clears all characters of the whole line. The cursor position is unchanged.

\e[K is equivalent to \e[0K. (Some terminal/emulators respond to \e[K as if it were \e[2K. Here, the default is 0; it is the norm)

\e[#L

IL: Insert Lines: The cursor line and all lines below it move down # lines, leaving blank space. The cursor position is unchanged. The bottommost # lines are lost. \e[L is equivalent to \e[1L.

\e[#M

DL: Delete Line: The block of # lines at and below the cursor are deleted; all lines below them move up # lines to fill in the gap, leaving # blank lines at the bottom of the screen. The cursor position is unchanged. \e[M is equivalent to \e[1M.

\e[#\@

ICH: Insert CHaracter: The cursor character and all characters to the right of it move right # columns, leaving behind blank space. The cursor position is unchanged. The rightmost # characters on the line are lost. \e[\@ is equivalent to \e[1\@.

\e[#P

DCH: Delete CHaracter: The block of # characters at and to the right of the cursor are deleted; all characters to the right of it move left # columns, leaving behind blank space. The cursor position is unchanged. \e[P is equivalent to \e[1P.

Escape sequences for Set Graphics Rendition

\e[#;...;#m

SGM: Set Graphics Mode: Calls the graphics functions specified by the following values. These specified functions remain active until the next occurrence of this escape sequence. Graphics mode changes the colors and attributes of text (such as bold and underline) displayed on the screen.

Text attributes

0 All attributes off
1 Bold on
4 Underscore on
7 Reverse video on
8 Concealed on
21 Bold off
24 Underscore off
27 Reverse video off
28 Concealed off

Escape sequences for Select Character Set

\e(U

Selects null mapping - straight to character from the codepage of the console.

\e(K

Selects Windows to DOS mapping. This is the default mapping. It is useful because one types the script with a Windows-based editor (using a Windows codepage) and the script prints its messages on the console using another codepage: without translation, the characters with a code greatest than 127 are different and the printed messages may be not readable.

The conversion is done by the Windows internal functions. If a character cannot be represented in the console code page it is replaced by a question mark character.

\e(#X

This escape sequence is not standard! It is an experimental one, just for fun :-)

If (and only if) the console uses a Unicode police, it is possible to change its codepage with this escape sequence. No effect with an ordinary "Raster Font". (For Windows NT/2000/XP the currently available Unicode console font is the Lucida Console TrueType font.) # is the number of the codepage needed, 855 for cp855 for instance.

Extra escape sequences for Set Cursor Visibility

The two following escape sequences are not in the ANSI standard. These are private escape sequences introduced by DEC for the VT-300 series of video terminals.

Gets and sets the cursor position (the upper-left corner of the screen is at (1, 1)). With no arguments, the cursor position is not modified. If one of the two coordinates $new_x or $new_y is 0, the corresponding coordinate does not change.

Gets and sets the cursor size i.e. the percentage of the character cell that is filled by the cursor. This value is between 1 and 100. The cursor appearance varies, ranging from completely filling the cell to showing up as a horizontal line at the bottom of the cell. With no argument, the cursor size is not modified.

$success = SetConsoleSize( $width, $height );

Sets the new size, in columns and rows, of the screen buffer. The specified $width and $height cannot be less than the width and height of the screen buffer's window. The specified dimensions also cannot be less than the minimum size allowed by the system.

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero and the extended error message is in $^E.

ShowConsoleWindow( $state )

Sets the console window's show state.

The parameter $state can be one of the following values:

SW_HIDE

Hides the console window and activates another window.

SW_MAXIMIZE

Maximizes the console window.

SW_MINIMIZE

Minimizes the console window and activates the next top-level window in the Z order.

SW_RESTORE

Activates and displays the console window. If the console window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when restoring a minimized console window.

SW_SHOW

Activates the console window and displays it in its current size and position.

SW_SHOWDEFAULT

Sets the show state based on the SW_ value specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application.

SW_SHOWMAXIMIZED

Activates the console window and displays it as a maximized window.

SW_SHOWMINIMIZED

Activates the window and displays it as a minimized window.

SW_SHOWMINNOACTIVE

Displays the console window as a minimized window. This value is similar to SW_SHOWMINIMIZED, except the window is not activated.

SW_SHOWNA

Displays the console window in its current size and position. This value is similar to SW_SHOW, except the window is not activated.

SW_SHOWNOACTIVATE

Displays the console window in its most recent size and position. This value is similar to SW_NORMAL, except the window is not activated.

SW_NORMAL

Activates and displays the console window. If the window is minimized or maximized, the system restores it to its original size and position.

If the console window was previously visible, the return value is nonzero.

If the console window was previously hidden, the return value is zero.

EXPORTS

Nothing by default; the function names and constants must be explicitly exported.

Export Tags:

:func

exports all the functions.

:MS_

exports SetMonitorState and the MS_* constants.

:SW_

exports MinimizeAll, ShowConsoleWindow and the SW_* constants

:all

exports all.

CAVEATS

Due to DOS-console limitations, the blink mode (text attributes 5 and 25) is not implemented.

If you use an integrated environment for developing your program you can see strange results on the console controlled by your IDE. The IDE catches and processes the output of your program so your program does not see a "real" console. In this case test your program in a separate console.