NAME

Text::TypingEffort - calculate the effort required to type a given text

SYNOPSIS

use Text::TypingEffort qw/effort/;

my $effort = effort("The quick brown fox jumps over the lazy dog");

$effort will be a hashref something like this

$effort = {
    characters => 43,     # the number of characters in the text
    presses    => 44,     # key presses need to type the text
    distance   => 950,    # millimeters the fingers moved while typing
    energy     => 2.2..., # the energy (Joules) used while typing
};

DESCRIPTION

Text::TypingEffort is used to calculate how much physical effort was required to type a given text. Several metrics of effort are used. These metrics are described in detail in the "METRICS" section.

This module is useful for determining which keyboard layout is more efficient, for making API/language design decisions, or to show your boss how hard you're working.

Function Quick Reference

The following quick reference provides brief information about the arguments that the functions can take. More detailed information is given below.

# effort() with a single argument
my $effort = effort(

   $text | \$text                        # the text to analyze
);

# effort() with options
my $effort = effort(

   text     => $text | \$text,           # the text to analyze
   file     => $filename | $filehandle,  # analyze a file
   layout   => 'qwerty'                  # keyboard layout
             | 'dvorak'
             | 'aset',
   unknowns => 0 | 1,                    # tally unknown chars?
   initial  => \%metrics,                # set initial values
);

FUNCTIONS

effort $TEXT | \$TEXT

The argument should be a scalar or a reference to a scalar which contains the text to be analyzed. Leading whitespace on each line of $TEXT is ignored since a decent text editor handles that for the typist. Only characters found on a standard US-104 keyboard are tallied in the metrics. That means that accented characters, unicode, etc. are not included. If a character is unrecognized, it is counted under the 'unknowns' metric.

effort %ARGUMENTS

effort() may also be called with a list of named arguments. This allows more flexibility in how the metrics are calculated. Below is a list of acceptable (or required) arguments. In summary, calling effort like this

effort($text);

is identical to explicitly specifying all the defaults like this

effort(
   text     => $text,
   layout   => 'qwerty',
   unknowns => 0,
   initial  => {},
);

text

Specifies the text to be analyzed. The value should be either a scalar or a reference to a scalar which contains the text. If neither this argument nor file is specified, effort will die.

file

Specifies a file which contains the text to be analyzed. If the value is a filehandle which is open for reading, the text will be read from that file handle. The filehandle will remain open after effort is finished with it.

If the value is a filename, the file will be opened and the text for analysis read from the file. If neither this argument nor text is specified, effort will die.

layout

Default: qwerty

Specifies the keyboard layout to use when calculating metrics. Acceptable, case-insensitive values for layout are: qwerty, dvorak, aset. If some other value is provided, the default value of 'qwerty' is used.

unknowns

Default: 0

Should a histogram of unrecognized characters be returned with the other metrics? A true value indicates yes and a false value no. Tallying this histogram takes a little bit more work in the inner loop and therefore makes processing ever so slightly slower. It can be useful for seeing how much of the text was not counted in the other metrics.

See unknowns in the "METRICS" section for information on how this option affects effort's return value.

initial

Default: {}

Sets the initial values for each of the metrics. This option is the way to have effort accumulate the results of multiple calls. By doing something like

$effort = effort($text_1);
$effort = effort(text=>$text_2, initial=>$effort);

you get the same results as if you had done

$effort = effort($text_1 . $text_2);

except the former scales more gracefully. The value of initial should be a hashref with keys and values similar to the result of a previous call to effort. If the hashref does not contain a key-value pair for a given metric, the initial value of that metric will be its normal default value (generally 0).

If the value of initial is not a hashref, effort proceeds as if the initial argument were not present at all. This behavior may change in the future, so don't rely upon it.

METRICS

characters

The number of recognized characters in the text. This is similar in spirit to the Unix command wc -c. Only those characters which are encoded in the internal keyboard layout will be counted. That excludes accented characters, Unicode characters and control characters but includes newlines.

presses

The number of keys pressed when typing the text. The value of this metric is the value of the characters metric plus the number of times the Shift key was pressed.

distance

The distance, in millimeters, that the fingers travelled while typing the text. This distance includes movement required for the Shift and Enter keys, but does not include the vertical movement the finger makes as the key descends during a press. Perhaps a better name for this metric would be horizontal_distance, but that's too long ;-)

The model for determining this metric is very simplistic. It assumes that a finger moves from its home position to the destination key and then returns to the home position before moving on to the next key. Of course, this is not how people actually type, but the model should result in an upper-bound for the amount of finger movement.

energy

The number of Joules of energy required to type the text. This metric is the most inclusive in that it tries to accomodate the values of both the presses and the distance metrics into a single metric. However, this metric is also the least accurate at modeling the real world. The calculations are roughly based upon the The Compendium of Physical Activities (or rather hearsay about it's contents since I don't have a copy).

The physical charactersistics of the keyboard are assumed to be roughly in line with ISO 9241-4:1998, which specifies standards for such things.

unknowns

This metric is only included in the output if the unknowns argument to effort was true.

The value is a histogram of the unrecognized characters encountered during processing. This includes any control characters, accented characters or unicode characters. Generally, anything other than the letters, numbers and punctuation found on a standard U.S. keyboard will be counted here.

If all characters were recognized, the value will be an empty hashref. If any characters were unknown, the value will be a hashref something like this:

unknowns => {
   presses => {
       'Å' => 2,
       'Ö' => 3,
   },
   distance => {
       'Å' => 2,
       'Ö' => 3,
   },
}

The key indicates the metric for which information was missing. The value is a hash indicating the character and the number of times that character occurred. There will be no entries in the hash for the characters or energy metrics as these are incidental to the other two.

This metric is only added to the result if the unknowns option was specified and true.

SEE ALSO

Tactus Keyboard article on the mechanics and standards of keyboard design - http://www.tactuskeyboard.com/keymech.htm

AUTHOR

Michael Hendricks <michael@palmcluster.org>

BUGS/TODO

Please submit suggestions and report bugs to the CPAN Bug Tracker at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-TypingEffort

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Michael Hendricks

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.

cpanm Text::TypingEffort

perl -MCPAN -e shell
install Text::TypingEffort