win32console 1.2.0-x86-mswin32-60

data/HISTORY.txt

@@ -0,0 +1,7 @@
+v1.0 - Added .dup to _printString function to avoid mangling outside
+       string references.  Removed the other (later) .dup call.
+       Turned of some exceptions that were conflicting with using
+       the module with pipes or redirections.
+v0.8 - Fixed bugs in reading routines, added ruby docs, and 
+       sample test suite.
+v0.5 - First public release.

data/HISTORY_GEM.txt

@@ -0,0 +1,38 @@
+1.2.0 - Code corrections integrated from GitHub
+  * Removed license conflicting ANSI Term code and functionality.
+  * Better code organization and clenaup
+
+1.1.0 - Bug fixes provided by Gordon Thiesfeld (gthiesfeld at gmail dot com).
+  * added #putc to Win32::Console::ANSI::IO 
+    This putc buffers escape sequences so that they will be handled properly
+  *added Kernel#putc
+    Redefined Kernel#putc to wrap Win32::Console::ANSI::IO#putc
+  *added #redirected? to Win32::Console::ANSI::IO
+    Checks the mode of the console to see if IO is being redirected or not
+  * fixed "Invalid Handle" error in compiled version of GetConsoleMode
+    I'm actually not sure of the source of this error.  It may be expected behavior when output is being redirected.  I worked around it by rescuing the exception in Win32::Console#Mode and returning 9999.  I picked that arbitrary value, because it is higher than 31, which is what I think is the highest value Mode would return if output isn't being redirected.
+  * modified Win32::Console::ANSI::IO#write
+  to check for redirection.  If output is redirected, it uses WriteFile instead of  WriteConosle.  It also skips the parsing step, and passes the escape sequences through.
+  * added Win32::Console::API#WriteFile
+    to both the Ruby and compiled versions
+  * added Win32::Console*WriteFile
+  This is a wrapper around Win32::Console::API#WriteFile
+  * modified Win32::Console::ANSI::IO#_PrintString
+  Didn't change behavior, just tried to make it more idiomatic ruby.  I didn't make all of the changes I wanted to, because I wasn't sure how to test them all.
+  * split Win32::Console::Constants and Win32::Console::API out into seperate files.
+  These two classes were in 'Win32/Console.rb'  I moved them into 'Win32/Console/constants.rb' and 'Win32/Console/api.rb' respectively.
+  * cleaned up indentation
+  indentations was a mixture of tabs and spaces.  I made everything indented with 2 spaces.
+  * modified all Win32::Console::API methods
+  It was assigning Win32API functions to class variables.  I switched them to instance variables. I also changed the idiom it was using to instantiate the objects.
+  For instance, instead of:
+  
+    if @@m_AllocConsole == nil
+    @@m_AllocConsole = Win32API.new( "kernel32", "AllocConsole", 
+            [], 'l' )
+            
+  It is now:
+  
+    @AllocConsole ||= Win32API.new( "kernel32", "AllocConsole", [], 'l' )
+  * Non-string arguments passed to Win32::Console::ANSI#write caused error - fix by Ivan Evtuhovich (evtuhovich at gmail dot com).
+1.0.8 - First public release of win32console gem by Justin Bailey (jgbailey at gmail dot com).

data/INSTALL.txt

@@ -0,0 +1,18 @@
+
+To compile and install:
+
+
+Open a windows console.
+> vcvars32.bat    # to set up microsoft's compiling environment
+                  # this is located in the bin/ directory of the MSVC compiler
+> ruby extconf.rb # to create a Makefile
+> nmake           # to compile
+> nmake install   # to install
+
+
+To test:
+
+> cd test
+> dir              # to see available samples
+> ruby [anysample]
+

data/README.txt

@@ -0,0 +1,25 @@
+
+This file implements a port of Perl's Win32::Console
+and Win32::Console::ANSI modules.
+
+Win32::Console allows controling the windows command line terminal
+thru an OO-interface.  This allows you to query the terminal (find
+its size, characters, attributes, etc).  The interface and functionality
+should be identical to Perl's.
+
+Win32::Console consists of a Ruby .rb interface.
+For best performance, this library has been also ported to C.  
+If you lack a C compiler, you can still use the class thru the ruby
+interface.  If you can compile it, then the ruby interface is not
+used and the C functions are called instead.
+
+Win32::Console::ANSI is a class derived from IO that seamlessly
+translates ANSI Esc control character codes into Windows' command.exe 
+or cmd.exe equivalents.
+
+These modules allow you to develop command-line tools that can take 
+advantage of the unix terminal functions while still being portable.
+One of the most common uses for this is to allow to color your
+output.
+The modules are disted with Term/ansicolor.rb, too, as it is a nice
+thing to verify it is working properly.

data/README_GEM.txt

@@ -0,0 +1,64 @@
+= Introduction
+
+This gem packages Gonzalo Garramuno's Win32::Console project, and includes a compiled binary for speed. The Win32::Console project's home can be found at:
+
+http://rubyforge.org/projects/win32console
+  
+To use the gem, just put
+
+  require 'win32console'
+  
+At the top of your file.
+
+= Example
+
+To output a simple bolded string, try this script:
+
+  require 'rubygems'
+  require 'win32console'
+  include Win32::Console::ANSI
+  include Term::ANSIColor
+  
+  puts bold << "bolded text" << clear << " and no longer bold."
+
+= Formatting Methods Available
+
+The full list of methods available is found in lib/Term/ansicolor.rb (generated from the @@attributes array):
+
+  clear
+  reset # synonym for clear
+  bold
+  dark
+  italic # not widely implemented
+  underline
+  underscore # synonym for underline
+  blink
+  rapid_blink # not widely implemented
+  negative # no reverse because of String#reverse
+  concealed
+  strikethrough # not widely implemented
+
+  # The following will set the foreground color
+  
+  black
+  red
+  green
+  yellow
+  blue
+  magenta
+  cyan
+  white
+
+  # The following will set the background color
+  
+  on_black
+  on_red
+  on_green
+  on_yellow
+  on_blue
+  on_magenta
+  on_cyan
+  on_white
+
+The methods are fairly sophisticated. If you don't pass an argument, the appropriate escape sequence is returned. If a string is given, it will be outputted with an escape sequence wrapping it to apply the formatting to just that portion. If a block is given, the escape sequence will wrap the output of the block. Finally, if the Term::ANSIColor module is mixed into an object, and that instance supports to_str, tnen the result of to_str will be wrapped in the escape sequence.
+  

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require './tasks/ext_helper'
+
+# House-keeping
+CLEAN.include '**/*.o', '**/*.so', '**/*.bundle', '**/*.a',
+  '**/*.log', '{ext,lib}/*.{bundle,so,obj,pdb,lib,def,exp}',
+  'ext/Makefile', '**/*.db'
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'win32console'
+  s.version           = '1.2.0'
+  s.platform          = Gem::Platform::RUBY
+  s.has_rdoc          = true
+  s.extra_rdoc_files  = %w[ README.txt README_GEM.txt INSTALL.txt HISTORY.txt HISTORY_GEM.txt ]
+  s.summary           = 'A library giving the Win32 console ANSI escape sequence support.'
+  s.description       = s.summary
+  s.author            = 'Original Library by Gonzalo Garramuno, Gem by Justin Bailey'
+  s.email             = 'ggarra @nospam@ advancedsl.com.ar, jgbailey @nospan@ gmail.com'
+  s.homepage          = 'http://rubyforge.org/projects/winconsole'
+  s.rubyforge_project = 'http://rubyforge.org/projects/winconsole'
+  s.description = <<EOS
+This gem packages Gonzalo Garramuno's Win32::Console project, and includes a compiled binary for speed. The Win32::Console project's home can be found at:
+
+  http://rubyforge.org/projects/win32console
+
+The gem project can be found at
+
+  http://rubyforge.org/projects/winconsole
+EOS
+
+  s.require_path      = 'lib'
+  s.extensions        = %w[ ext/extconf.rb ]
+  s.files             = FileList[ '{doc,ext,lib,test}/**/*.{rdoc,c,cpp,rb}', 'Rakefile', *s.extra_rdoc_files ]
+
+  s.rdoc_options << '--title' << 'Win32Console Gem -- Gem for Win32::Console Project' <<
+                   '--main' << 'README_GEM.txt' <<
+                   '--line-numbers'
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+  pkg.gem_spec = spec
+end
+
+# Use of ext_helper to properly setup compile tasks and native gem generation
+# add 'native', 'compile' and some tweaks to gem specifications.
+setup_extension 'Console', spec

data/doc/Console.rdoc

@@ -0,0 +1,690 @@
+#
+#  = NAME
+#
+#  Win32::Console - Win32 Console and Character Mode Functions
+#
+#
+#  = DESCRIPTION
+#
+#  This module implements the Win32 console and character mode
+#  functions.  They give you full control on the console input and output,
+#  including: support of off-screen console buffers (eg. multiple screen
+#  pages)
+#
+#    - reading and writing of characters, attributes and whole portions of
+#      the screen
+#
+#    - complete processing of keyboard and mouse events
+#
+#    - some very funny additional features :)
+#
+#
+#  Those functions should also make possible a port of the Unix's curses
+#  library; if there is anyone interested (and/or willing to contribute)
+#  to this project, e-mail me.  Thank you.
+#
+#
+#  = REFERENCE
+#
+#
+#  == Methods
+#
+#  - Alloc
+#
+#    Allocates a new console for the process.  Returns C<nil> on errors, a
+#    nonzero value on success.  A process cannot be associated with more
+#    than one console, so this method will fail if there is already an
+#    allocated console.  Use Free to detach the process from the console,
+#    and then call Alloc to create a new console.  See also: C<Free>
+#
+#    Example:
+#
+#      Win32::Console::Alloc()
+#
+#  - Attr [attr]
+#
+#    Gets or sets the current console attribute.  This attribute is used by
+#    the Write method.
+#
+#    Example:
+#
+#      attr = console.Attr()
+#      console.Attr(FG_YELLOW | BG_BLUE)
+#
+#  - Close
+#
+#    Closes a shortcut object.  Note that it is not "strictly" required to
+#    close the objects you created, since the Win32::Shortcut objects are
+#    automatically closed when the program ends (or when you elsehow
+#    destroy such an object).
+#
+#    Example:
+#
+#      link.Close()
+#
+#  - Cls [attr]
+#
+#    Clear the console, with the specified I<attr> if given, or using
+#    ATTR_NORMAL otherwise.
+#
+#    Example:
+#
+#      console.Cls()
+#      console.Cls(FG_WHITE | BG_GREEN)
+#
+#  - Cursor [x, y, size, visible]
+#
+#    Gets or sets cursor position and appearance.  Returns C<nil> on
+#    errors, or a 4-element list containing: I<x>, I<y>, I<size>,
+#    I<visible>.  I<x> and I<y> are the current cursor position; ...
+#
+#    Example:
+#
+#      x, y, size, visible = console.Cursor()
+#
+#      # Get position only
+#      x, y = console.Cursor()
+#
+#      console.Cursor(40, 13, 50, 1)
+#
+#      # Set position only
+#      console.Cursor(40, 13)
+#
+#      # Set size and visibility without affecting position
+#      console.Cursor(-1, -1, 50, 1)
+#
+#  - Display
+#
+#    Displays the specified console on the screen.  Returns C<nil> on errors,
+#    a nonzero value on success.
+#
+#    Example:
+#
+#      console.Display()
+#
+#  - FillAttr [attribute, number, col, row]
+#
+#    Fills the specified number of consecutive attributes, beginning at
+#    I<col>, I<row>, with the value specified in I<attribute>.  Returns the
+#    number of attributes filled, or C<nil> on errors.  See also:
+#    C<FillChar>.
+#
+#    Example:
+#
+#      console.FillAttr(FG_BLACK | BG_BLACK, 80*25, 0, 0)
+#
+#  - FillChar char, number, col, row
+#
+#    Fills the specified number of consecutive characters, beginning at
+#    I<col>, I<row>, with the character specified in I<char>.  Returns the
+#    number of characters filled, or C<nil> on errors.  See also:
+#    C<FillAttr>.
+#
+#    Example:
+#
+#      console.FillChar("X", 80*25, 0, 0)
+#
+#  - Flush
+#
+#    Flushes the console input buffer.  All the events in the buffer are
+#    discarded.  Returns C<nil> on errors, a nonzero value on success.
+#
+#    Example:
+#
+#     console.Flush()
+#
+#  - Free
+#
+#    Detaches the process from the console.  Returns C<nil> on errors, a
+#    nonzero value on success.  See also: C<Alloc>.
+#
+#    Example:
+#
+#      Win32::Console::Free()
+#
+#  - GenerateCtrlEvent [type, processgroup]
+#
+#    Sends a break signal of the specified I<type> to the specified
+#    I<processgroup>.  I<type> can be one of the following constants:
+#
+#      CTRL_BREAK_EVENT
+#      CTRL_C_EVENT
+#
+#    they signal, respectively, the pressing of Control + Break and of
+#    Control + C; if not specified, it defaults to CTRL_C_EVENT.
+#    I<processgroup> is the pid of a process sharing the same console.  If
+#    omitted, it defaults to 0 (the current process), which is also the
+#    only meaningful value that you can pass to this function.  Returns
+#    C<nil> on errors, a nonzero value on success.
+#
+#    Example:
+#
+#      # break this script now
+#      Win32::Console::GenerateCtrlEvent()
+#
+#  - GetEvents
+#
+#    Returns the number of unread input events in the console's input
+#    buffer, or C<nil> on errors.  See also: C<Input>, C<InputChar>,
+#    C<PeekInput>, C<WriteInput>.
+#
+#    Example:
+#
+#      events = console.GetEvents()
+#
+#  - Info
+#
+#    Returns an array of informations about the console (or C<nil> on
+#    errors), which contains:
+#
+#       * columns (X size) of the console buffer.
+#
+#       * rows (Y size) of the console buffer.
+#
+#       * current column (X position) of the cursor.
+#
+#       * current row (Y position) of the cursor.
+#
+#       * current attribute used for C<Write>.
+#
+#       * left column (X of the starting point) of the current console window.
+#
+#       * top row (Y of the starting point) of the current console window.
+#
+#       * right column (X of the final point) of the current console window.
+#
+#       * bottom row (Y of the final point) of the current console window.
+#
+#       * maximum number of columns for the console window, given the current
+#         buffer size, font and the screen size.
+#
+#       * maximum number of rows for the console window, given the current
+#         buffer size, font and the screen size.
+#
+#
+#    See also: <b>Attr</b>, <b>Cursor</b>, <b>Size</b>, <b>Window</b>, <b>MaxWindow</b>.
+#
+#    Example:
+#
+#      info = console.Info()
+#      puts "Cursor at #{info[3]}, #{info[4]}."
+#
+#  - Input
+#
+#    Reads an event from the input buffer.  Returns an array of values, which
+#    depending on the event's nature are:
+#
+#    - keyboard event
+#
+#       The array will contain:
+#
+#       * event type: 1 for keyboard
+#
+#       * key down: TRUE if the key is being pressed, FALSE if the key is being released
+#
+#       * repeat count: the number of times the key is being held down
+#
+#       * virtual keycode: the virtual key code of the key
+#
+#       * virtual scancode: the virtual scan code of the key
+#
+#       * char: the ASCII code of the character (if the key is a character key, 0 otherwise)
+#
+#       * control key state: the state of the control keys (SHIFTs, CTRLs, ALTs, etc.)
+#
+#
+#    - mouse event
+#
+#      The array will contain:
+#
+#       * event type: 2 for mouse
+#
+#       * mouse pos. X: X coordinate (column) of the mouse location
+#
+#       * mouse pos. Y: Y coordinate (row) of the mouse location
+#
+#       * button state: the mouse button(s) which are pressed
+#
+#       * control key state: the state of the control keys (SHIFTs, CTRLs, ALTs, etc.)
+#
+#       * event flags: the type of the mouse event
+#
+#
+#    This method will return <b>nil</b> on errors.  Note that the events
+#    returned are depending on the input <b>Mode</b> of the console; for example,
+#    mouse events are not intercepted unless ENABLE_MOUSE_INPUT is
+#    specified.  See also: <b>GetEvents</b>, <b>InputChar</b>, <b>Mode</b>,
+#    <b>PeekInput</b>, <b>WriteInput</b>.
+#
+#    Example:
+#
+#      event = console.Input()
+#
+#  - InputChar number
+#
+#    Reads and returns I<number> characters from the console input buffer,
+#    or <b>nil</b> on errors.  See also: <b>Input</b>, <b>Mode</b>.
+#
+#    Example:
+#
+#      key = console.InputChar(1)
+#
+#  - InputCP [codepage]
+#
+#    Gets or sets the input code page used by the console.  Note that this
+#    doesn't apply to a console object, but to the standard input
+#    console.  This attribute is used by the Write method.  See also:
+#    <b>OutputCP</b>.
+#
+#    Example:
+#
+#      codepage = Win32::Console::InputCP()
+#      Win32::Console::InputCP(437)
+#
+#  - MaxWindow
+#
+#    Returns the size of the largest possible console window, based on the
+#    current font and the size of the display.  The result is <b>nil</b> on
+#    errors, otherwise a 2-element list containing col, row.
+#
+#    Example:
+#
+#      maxCol, maxRow = console.MaxWindow()
+#
+#  - Mode [flags]
+#
+#    Gets or sets the input or output mode of a console.  I<flags> can be a
+#    combination of the following constants:
+#
+#      ENABLE_LINE_INPUT
+#      ENABLE_ECHO_INPUT
+#      ENABLE_PROCESSED_INPUT
+#      ENABLE_WINDOW_INPUT
+#      ENABLE_MOUSE_INPUT
+#      ENABLE_PROCESSED_OUTPUT
+#      ENABLE_WRAP_AT_EOL_OUTPUT
+#
+#    For more informations on the meaning of those flags, please refer to
+#    the L<"Microsoft's Documentation">.
+#
+#    Example:
+#
+#      mode = console.Mode()
+#      console.Mode(ENABLE_MOUSE_INPUT | ENABLE_PROCESSED_INPUT)
+#
+#  - MouseButtons
+#
+#    Returns the number of the buttons on your mouse, or <b>nil</b> on errors.
+#
+#    Example:
+#
+#      puts "Your mouse has #{Win32::Console::MouseButtons()} buttons."
+#
+#  - Win32::Console.new standard_handle
+#
+#  - Win32::Console.new [accessmode, sharemode]
+#
+#    Creates a new console object.  The first form creates a handle to a
+#    standard channel, I<standard_handle> can be one of the following:
+#
+#      STD_OUTPUT_HANDLE
+#      STD_ERROR_HANDLE
+#      STD_INPUT_HANDLE
+#
+#    The second form, instead, creates a console screen buffer in memory,
+#    which you can access for reading and writing as a normal console, and
+#    then redirect on the standard output (the screen) with <b>Display</b>.  In
+#    this case, you can specify one or both of the following values for
+#    I<accessmode>:
+#
+#      GENERIC_READ
+#      GENERIC_WRITE
+#
+#    which are the permissions you will have on the created buffer, and one
+#    or both of the following values for I<sharemode>:
+#
+#      FILE_SHARE_READ
+#      FILE_SHARE_WRITE
+#
+#    which affect the way the console can be shared.  If you don't specify
+#    any of those parameters, all 4 flags will be used.
+#
+#    Example:
+#
+#      stdout = Win32::Console.new(STD_OUTPUT_HANDLE)
+#      stderr = Win32::Console.new(STD_ERROR_HANDLE)
+#      stdin  = Win32::Console.new(STD_INPUT_HANDLE)
+#
+#      buffer = Win32::Console.new()
+#      buffer = Win32::Console.new(GENERIC_READ | GENERIC_WRITE)
+#
+#  - OutputCP [codepage]
+#
+#    Gets or sets the output code page used by the console.  Note that this
+#    doesn't apply to a console object, but to the standard output console.
+#    See also: <b>InputCP</b>.
+#
+#    Example:
+#
+#      codepage = Win32::Console::OutputCP()
+#      Win32::Console::OutputCP(437)
+#
+#  - PeekInput
+#
+#    Does exactly the same as <b>Input</b>, except that the event read is not
+#    removed from the input buffer.  See also: <b>GetEvents</b>, <b>Input</b>,
+#    <b>InputChar</b>, <b>Mode</b>, <b>WriteInput</b>.
+#
+#    Example:
+#
+#      event = console.PeekInput()
+#
+#  - ReadAttr [number, col, row]
+#
+#    Reads the specified I<number> of consecutive attributes, beginning at
+#    I<col>, I<row>, from the console.  Returns the attributes read (a
+#    variable containing one character for each attribute), or <b>nil</b> on
+#    errors.  You can then pass the returned variable to <b>WriteAttr</b> to
+#    restore the saved attributes on screen.  See also: <b>ReadChar</b>,
+#    <b>ReadRect</b>.
+#
+#    Example:
+#
+#      colors = console.ReadAttr(80*25, 0, 0)
+#
+#  - ReadChar [number, col, row]
+#
+#    Reads the specified I<number> of consecutive characters, beginning at
+#    I<col>, I<row>, from the console.  Returns a string containing the
+#    characters read, or <b>nil</b> on errors.  You can then pass the
+#    returned variable to <b>WriteChar</b> to restore the saved characters on
+#    screen.  See also: <b>ReadAttr</b>, <b>ReadRect</b>.
+#
+#    Example:
+#
+#      chars = console.ReadChar(80*25, 0, 0)
+#
+#  - ReadRect left, top, right, bottom
+#
+#    Reads the content (characters and attributes) of the rectangle
+#    specified by I<left>, I<top>, I<right>, I<bottom> from the console.
+#    Returns a string containing the rectangle read, or <b>nil</b> on errors.
+#    You can then pass the returned variable to <b>WriteRect</b> to restore the
+#    saved rectangle on screen (or on another console).  See also:
+#    <b>ReadAttr</b>, <b>ReadChar</b>.
+#
+#    Example:
+#
+#       rect = console.ReadRect(0, 0, 80, 25)
+#
+#  - Scroll left, top, right, bottom, col, row, char, attr,
+#               [cleft, ctop, cright, cbottom]
+#
+#    Moves a block of data in a console buffer the block is identified by
+#    I<left>, I<top>, I<right>, I<bottom>, while I<row>, I<col> identify
+#    the new location of the block.  The cells left empty as a result of
+#    the move are filled with the character I<char> and attribute I<attr>.
+#    Optionally you can specify a clipping region with I<cleft>, I<ctop>,
+#    I<cright>, I<cbottom>, so that the content of the console outside this
+#    rectangle are unchanged.  Returns <b>nil</b> on errors, a nonzero value
+#    on success.
+#
+#    Example:
+#
+#      # scrolls the screen 10 lines down, filling with black spaces
+#      console.Scroll(0, 0, 80, 25, 0, 10, " ", FG_BLACK | BG_BLACK)
+#
+#  - Select standard_handle
+#
+#    Redirects a standard handle to the specified console.
+#    I<standard_handle> can have one of the following values:
+#
+#      STD_INPUT_HANDLE
+#      STD_OUTPUT_HANDLE
+#      STD_ERROR_HANDLE
+#
+#    Returns <b>nil</b> on errors, a nonzero value on success.
+#
+#    Example:
+#
+#      console.Select(STD_OUTPUT_HANDLE)
+#
+#  - Size [col, row]
+#
+#    Gets or sets the console buffer size.
+#
+#    Example:
+#
+#      x, y = console.Size()
+#      console.Size(80, 25)
+#
+#  - Title [title]
+#
+#    Gets or sets the title bar the string of the current console window.
+#
+#    Example:
+#
+#      title = console.Title()
+#      console.Title("This is a title")
+#
+#  - Window [flag, left, top, right, bottom]
+#
+#    Gets or sets the current console window size.  If called without
+#    arguments, returns a 4-element list containing the current window
+#    coordinates in the form of I<left>, I<top>, I<right>, I<bottom>.  To
+#    set the window size, you have to specify an additional I<flag>
+#    parameter: if it is 0 (zero), coordinates are considered relative to
+#    the current coordinates; if it is non-zero, coordinates are absolute.
+#
+#    Example:
+#
+#      left, top, right, bottom = console.Window()
+#      console.Window(1, 0, 0, 80, 50)
+#
+#  - Write string
+#
+#    Writes I<string> on the console, using the current attribute, that you
+#    can set with <b>Attr</b>, and advancing the cursor as needed.  This isn't
+#    so different from Perl's "print" statement.  Returns the number of
+#    characters written or <b>nil</b> on errors.  See also: <b>WriteAttr</b>,
+#    <b>WriteChar</b>, <b>WriteRect</b>.
+#
+#    Example:
+#
+#      console.Write("Hello, world!")
+#
+#  - WriteAttr attrs, col, row
+#
+#    Writes the attributes in the string I<attrs>, beginning at I<col>,
+#    I<row>, without affecting the characters that are on screen.  The
+#    string attrs can be the result of a <b>ReadAttr</b> function, or you can
+#    build your own attribute string; in this case, keep in mind that every
+#    attribute is treated as a character, not a number (see example).
+#    Returns the number of attributes written or <b>nil</b> on errors.  See
+#    also: <b>Write</b>, <b>WriteChar</b>, <b>WriteRect</b>.
+#
+#    Example:
+#
+#      console.WriteAttr($attrs, 0, 0)
+#
+#      # note the use of chr()...
+#      attrs = (FG_BLACK | BG_WHITE).chr() * 80
+#      console.WriteAttr(attrs, 0, 0)
+#
+#  - WriteChar chars, col, row
+#
+#    Writes the characters in the string <i>attr</i>, beginning at <i>col</i>, <i>row</i>,
+#    without affecting the attributes that are on screen.  The string <i>chars</i>
+#    can be the result of a <b>ReadChar</b> function, or a normal string.  Returns
+#    the number of characters written or <b>nil</b> on errors.  See also:
+#    <b>Write</b>, <b>WriteAttr</b>, <b>WriteRect</b>.
+#
+#    Example:
+#
+#      console.WriteChar("Hello, worlds!", 0, 0)
+#
+#  - WriteInput (event)
+#
+#    Pushes data in the console input buffer.  I<(event)> is a list of values,
+#    for more information see <b>Input</b>.  The string chars can be the result of
+#    a <b>ReadChar</b> function, or a normal string.  Returns the number of
+#    characters written or <b>nil</b> on errors.  See also: <b>Write</b>,
+#    <b>WriteAttr</b>, <b>WriteRect</b>.
+#
+#    Example:
+#
+#      console.WriteInput(event)
+#
+#  - WriteRect rect, left, top, right, bottom
+#
+#    Writes a rectangle of characters and attributes (contained in <i>rect</i>)
+#    on the console at the coordinates specified by <i>left</i>, <i>top</i>,
+#    <i>right</i>, <i>bottom</i>.  <i>rect</i> can be the result of a <b>ReadRect</b>
+#    function.  Returns <b>nil</b> on errors, otherwise a 4-element list
+#    containing the coordinates of the affected rectangle, in the format
+#    <i>left</i>, <i>top</i>, <i>right</i>, <i>bottom</i>.  See also: <b>Write</b>,
+#    <b>WriteAttr</b>, <b>WriteChar</b>.
+#
+#    Example:
+#
+#      console.WriteRect(rect, 0, 0, 80, 25)
+#
+#
+#  == Constants
+#
+#  The following constants are defined in the namespace of 
+#  Win32::Console::Constants and are brought into the current
+#  namespace when the module is required:
+#
+#      BACKGROUND_BLUE
+#      BACKGROUND_GREEN
+#      BACKGROUND_INTENSITY
+#      BACKGROUND_RED
+#      CAPSLOCK_ON
+#      CONSOLE_TEXTMODE_BUFFER
+#      ENABLE_ECHO_INPUT
+#      ENABLE_LINE_INPUT
+#      ENABLE_MOUSE_INPUT
+#      ENABLE_PROCESSED_INPUT
+#      ENABLE_PROCESSED_OUTPUT
+#      ENABLE_WINDOW_INPUT
+#      ENABLE_WRAP_AT_EOL_OUTPUT
+#      ENHANCED_KEY
+#      FILE_SHARE_READ
+#      FILE_SHARE_WRITE
+#      FOREGROUND_BLUE
+#      FOREGROUND_GREEN
+#      FOREGROUND_INTENSITY
+#      FOREGROUND_RED
+#      LEFT_ALT_PRESSED
+#      LEFT_CTRL_PRESSED
+#      NUMLOCK_ON
+#      GENERIC_READ
+#      GENERIC_WRITE
+#      RIGHT_ALT_PRESSED
+#      RIGHT_CTRL_PRESSED
+#      SCROLLLOCK_ON
+#      SHIFT_PRESSED
+#      STD_INPUT_HANDLE
+#      STD_OUTPUT_HANDLE
+#      STD_ERROR_HANDLE
+#
+#  Additionally, these other constants are also added to your current
+#  namespace when requiring the module:
+#
+#      FG_BLACK
+#      FG_BLUE
+#      FG_LIGHTBLUE
+#      FG_RED
+#      FG_LIGHTRED
+#      FG_GREEN
+#      FG_LIGHTGREEN
+#      FG_MAGENTA
+#      FG_LIGHTMAGENTA
+#      FG_CYAN
+#      FG_LIGHTCYAN
+#      FG_BROWN
+#      FG_YELLOW
+#      FG_GRAY
+#      FG_WHITE
+#
+#      BG_BLACK
+#      BG_BLUE
+#      BG_LIGHTBLUE
+#      BG_RED
+#      BG_LIGHTRED
+#      BG_GREEN
+#      BG_LIGHTGREEN
+#      BG_MAGENTA
+#      BG_LIGHTMAGENTA
+#      BG_CYAN
+#      BG_LIGHTCYAN
+#      BG_BROWN
+#      BG_YELLOW
+#      BG_GRAY
+#      BG_WHITE
+#
+#      ATTR_NORMAL
+#      ATTR_INVERSE
+#
+#  ATTR_NORMAL is set to gray foreground on black background (DOS's
+#  standard colors).
+#
+#
+#  == Microsoft's Documentation
+#
+#  Documentation for the Win32 Console and Character mode Functions can
+#  be found on Microsoft's site at this URL:
+#
+#  http://www.microsoft.com/msdn/sdk/platforms/doc/sdk/win32/sys/src/conchar.htm
+#
+#  A reference of the available functions is at:
+#
+#  http://www.microsoft.com/msdn/sdk/platforms/doc/sdk/win32/sys/src/conchar_34.htm
+#
+#
+#  = VERSION HISTORY
+#
+#   * 0.031 (24 Sep 1999)
+#
+#     * Fixed typo in GenerateCtrlEvent().
+#
+#     * Converted and added pod documentation (from Jan Dubois <jand@activestate.com>).
+#
+#   * 0.03 (07 Apr 1997)
+#
+#     * Added "GenerateCtrlEvent" method.
+#
+#     * The PLL file now comes in 2 versions, one for Perl version 5.001
+#       (build 110) and one for Perl version 5.003 (build 300 and higher,
+#       EXCEPT 304).
+#
+#     * added an installation program that will automatically copy the right
+#       version in the right place.
+#
+#  * 0.01 (09 Feb 1997)
+#
+#      * First public release.
+#
+#  = AUTHORS
+#
+#  Aldo Calpini <a.calpini@romagiubileo.it> Perl module
+#
+#  Gonzalo Garramu�o <GGarramuno@aol.com>   Ruby Port
+#
+#  = CREDITS
+#
+#  Thanks to: Jesse Dougherty, Dave Roth, ActiveWare, and the
+#  Perl-Win32-Users community.
+#
+#
+#  = DISCLAIMER
+#
+#  This program is FREE; you can redistribute, modify, disassemble, or
+#  even reverse engineer this software at your will.  Keep in mind,
+#  however, that NOTHING IS GUARANTEED to work and everything you do is
+#  AT YOUR OWN RISK - I will not take responsibility for any damage, loss
+#  of money and/or health that may arise from the use of this program!
+#
+#  This is distributed under the terms of Larry Wall's Artistic License.
+#