Commits

Anonymous committed 0b1bc02

Whistle innocently while doing a number on the version number.

Comments (0)

Files changed (3)

lib/console-virtual/Console/Virtual.pm

 # Console::Virtual.pm - unbuffered-input/addressed-display layer
-# v2007.1122-YPSILAXDEV Chris Pressey, Cat's Eye Technologies
+# version 2.0 (February 2013)
 
-# Copyright (c)2003-2007, Chris Pressey, Cat's Eye Technologies.
+# Copyright (c)2003-2013, Chris Pressey, Cat's Eye Technologies.
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
   use 5;
   use strict qw(subs);
   use Exporter;
-  $VERSION = 2007.1122;
+  $VERSION = 2.0;
   @ISA = qw(Exporter);
   @EXPORT_OK = qw(&display &clrscr &clreol &gotoxy
                   &bold &inverse &normal

lib/console-virtual/README.markdown

 Console::Virtual
 ================
 
-v2007.1122-YPSILAXDEV Chris Pressey, Cat's Eye Technologies.  
-(c)2003-2007 Cat's Eye Technologies.  All rights reserved.  
+Version 2.0
+(c)2003-2013 Chris Pressey, Cat's Eye Technologies.  All rights reserved.  
 (BSD-style license.  See file `Console/Virtual.pm` for full license info.)
 
 What is Console::Virtual?
 
 Console::Virtual is intended to be only a simple redirection layer that
 insulates the programmer from whatever screen-oriented mechanisms are
-actually installed at the site.  My experience has been that Curses is often
-not installed, or installed incorrectly.  It can be impractical to install,
-for any number of reasons.  While Term::Cap and Term::Screen are part of the
-Perl 5.8.8 core libraries, they too on occasion are not installed correctly.
-Further, they are insufficiently abstract, assuming that the user interacts
-with what is essentially a terminal.  Not all systems look at the world this
-way -- Windows machines being an obvious example.
+actually installed at the site.
+
+On most modern systems, Perl's Curses module is usually installed, or easy
+to install via the package system, and for that reason, Console::Virtual
+defaults to using it as its backend.
+
+On some systems, though (and please understand this was more true when this
+interface was first written), Curses is impractical to install, or installed
+incorrectly.  Perl has other ways of working with an addressable screen,
+such as Term::Cap and Term::Screen (part of the Perl 5.8.8 core libraries),
+but they too on occasion are not installed correctly.  Further, they are
+lacking in abstraction -- they are based on the starting assumption of a
+Unix-like terminal interface.  Not all systems look at the world this way,
+Windows being one example.
 
 Because I was writing a console-based application which was to be highly
 portable, I needed a layer which would automatically decide which unbuffered-
 
 To use Console::Virtual, you will either have to install it somewhere in
 Perl's include path (you can do this by copying the Console directory and
-all of its contents to e.g. /usr/local/lib/perl5/site_perl/5.005), or
+all of its contents to e.g. `/usr/local/lib/perl5/site_perl/5.005`), or
 alternately, give Perl a new include path which contains the Console
 directory.  As usual, there is more than one way to do this: you can
-pass the -I flag to the perl executable, or you can add a line like
+pass the `-I` flag to the perl executable, or you can add a line like
 `BEGIN { push @INC, $dir }` to your script.  If you want to just keep the
 Console directory in the same directory as your script, you can add
 `BEGIN { use File::Basename; push @INC, dirname($0) }` instead.
 
 Then you can insert the following into your Perl script to use it:
 
-    use Console::Virtual 2007.1122
+    use Console::Virtual 2.0
          qw(getkey display gotoxy clrscr clreol
-            normal inverse bold color update_display);
+            normal inverse bold color update_display
+            vsleep);
 
 Console::Virtual first tries to use Curses, if it's installed.  If not, and
 it detects that it's running on a Win32 system, it tries to use
 
 Failing all of that, if Console::Virtual can't find anything that suits your
 platform, it will produce a warning, carry on regardless, and assume that it
-is running on a teletype.  It will emulate an addressible screen on the
+is running on a teletype.  It will emulate an addressable screen on the
 standard output stream the best way it knows how: the entire screen will be
 re-printed whenever an update is requested.  Also, the user will have to
 tolerate line-buffered input, where a carriage return must be issued before
 saddened *by* the fact that teletypes are rare these days.)
 
 A specific input or display methodology can be specified by setting
-values in the %Console::Virtual::setup hash before using Console::Virtual.
+values in the `%Console::Virtual::setup` hash before using Console::Virtual.
 You probably shouldn't do this if you want to retain portability; the intent
 of it is to allow the end user to tailor their local copy of a script,
 forcing it to pick some specific implementation, presumably in preference to
     normal()          set display style back to normal
     update_display()  explicitly refresh the screen (Curses & Teletype need this)
     color($f,$b)      sets the colors of text about to be displayed
+    vsleep($s)        sleep for $s seconds (may be a fraction)
 
 Acceptable arguments for $f and $b in color() are 'black', 'red', 'blue',
 'purple', 'green', 'brown', 'aqua', 'grey', 'pink', 'sky' (blue), 'magenta',
 ought to be.  In fact, last I checked, they are encouraged.
 
 These actions are prohibited in Console::Virtual.  Specifically, you should
-not simply use 'print' to place text on the display device; you must instead
-use display().  If you do not do this, the output of your program will look
+not simply use `print` to place text on the display device; you must instead
+use `display()`.  If you do not do this, the output of your program will look
 funny (to say the least) when the end user is using Curses, or a teletype,
 or some future output technology that Console::Virtual one day delegates to.
-By the same token, you must occasionally use update_display() for the
+By the same token, you must occasionally use `update_display()` for the
 benefit of Curses and other output regimens which require explicit refresh.
-Calling update_display() must be done when the cursor is to be seen, by
+Calling `update_display()` must be done when the cursor is to be seen, by
 the user, to move.  It is also a good idea to do it in anticipation of a
 long upcoming delay in the program (e.g. intense computation.)
 
+A Note on Version Numbers
+-------------------------
+
+There was a point in time when I thought `YYYY.MMDD` was the Only Version
+Number You'd Ever Need.  My opinion on that has changed.  Therefore, I am
+changing the version numbering for Console::Virtual; this is version 2.0.
+
+Alas, this plays havoc with logic that tries to decide which version of a
+package is more recent than another, as `2007.1122` > `2.0`.  However, there
+are two things that soften the blow:
+
+*   I don't think anyone actually uses this module.  Hooray!
+*   The `vsleep` function was introduced in 2.0.  To ensure that you
+    are really getting version 2.x or later, import `vsleep` in your
+    `use Console::Virtual 2.0`.
+
 History
 -------
 
 -   v2007.1122: renamed to Console::Virtual, prettied readme.txt.
     Also updated language in BSD license (no "REGENTS".)
 -   v2007.1122-YPSILAXDEV: made `die` turn off Curses before dying.
-    (will give this a better version RSN)
+    Converted README to Markdown.
+-   v2.0: added `vsleep`.  Did horrific thing to version number.
 
 More Information
 ----------------
 The latest version of Console::Virtual can be found at:
 
     https://github.com/catseye/Console-Virtual
-
-Chris Pressey  
-November 22, 2007  
-Chicago, Illinois, USA

script/ypsilax.pl

 # BEGIN { $Console::Virtual::setup{input} = 'Teletype'; }
 # BEGIN { $Console::Virtual::setup{color} = 'ANSI16'; }
 
-use Console::Virtual 2007.1122
+use Console::Virtual 2.0
      qw(getkey display gotoxy clrscr clreol
         normal inverse bold update_display color
         vsleep);