File Coverage

bin/units

Criterion	Covered	Total	%
statement	259	363	71.3
branch	97	174	55.7
condition	7	27	25.9
subroutine	38	46	82.6
pod			n/a
total	401	610	65.7

#!/usr/bin/perl
package PerlPowerTools::units;

use strict;
use warnings;
use open qw(:std :utf8);

=begin metadata

Name: units
Description: conversion program
Author: Mark-Jason Dominus, [e-mail]
License: gpl

=end metadata

=cut

use Config;

# Usage:
# units [-f unittab]
our $VERSION = '1.02';

BEGIN {
    require Data::Dumper;
	sub dumper { Data::Dumper->new([@_])->Indent(1)->Sortkeys(1)->Terse(1)->Useqq(1)->Deparse(1)->Dump }

	foreach my $letter ( qw( d p o l t ) ) {
	  no strict 'refs';
	  my $env_var = uc( "UNITS_DEBUG_$letter" );
	  my( $debugging ) = grep { defined and length } ( $ENV{$env_var}, $ENV{UNITS_DEBUG}, 0 );
	  *{"debug_$letter"} = ! $debugging ? sub {} : sub {
		my $indent;
		my $m = join '', @_;
		$indent = $1 if $m =~ s/\A(\s*)//;
		print "$indent$letter>>> $m\n";
	  }
	}
}

our %unittab;            # Definitions loaded here

# Metric prefixes.  These must be powers of ten or change the
# token_value subroutine
our %PREF;
our $PREF;
our $PARSE_ERROR;

BEGIN {
  %PREF = (
    yotta => -24,
    zetta => -21,
    atto  => -18,
    femto => -15,
    pico  => -12,
    nano  => - 9,
    micro => - 6,
    milli => - 3,
    centi => - 2,
    deci  => - 1,
    deca  =>   1,
    deka  =>   1,
    hecto =>   2,
    hect  =>   2,
    kilo  =>   3,
    myria =>   4,
    mega  =>   6,
    giga  =>   9,
    tera  =>  12,
    zepto =>  15,
    yocto =>  18,
  );
  $PREF = join '|', sort {$PREF{$a} <=> $PREF{$b}} (keys %PREF);
}

# run if called directly, indirectly, directly par-packed, undirectly par-packed
__PACKAGE__->run(@ARGV) if !caller() || caller(0) =~ /^(PerlPowerTools::Packed|PAR)$/ || caller(1) eq 'PAR'; # modulino

sub run {
  my( $class, @args ) = @_; local @ARGV;

  my $args = $class->process_args( @args );

  $class->read_unittab( $args->{unittabs}[0] );

  if (@{ $args->{args} }) {
    my ($have, $want) = @{ $args->{args} };
    my $have_hr = $class->unit_have($have);
    my $want_hr = $class->unit_want($want);
    my %r = $class->unit_convert($have_hr, $want_hr);
    print_result(%r);
  } else {
    while (1) {
      print "You have: ";
      my $have = <>;
      exit 0 unless defined($have) && $have =~ /\S/;
      my $have_hr = $class->unit_have($have);
      next if is_Zero($have_hr->{hu});

      print "You want: ";
      my $want = <>;
      exit 0 unless defined($want) && $want =~ /\S/;
      my $want_hr = $class->unit_want($want);
      next if is_Zero($want_hr->{wu});

      my %r = $class->unit_convert($have_hr, $want_hr);
      print_result(%r);
    }
  }

  exit 0;
}

sub test {
    my ($class, $have, $want) = @_;

    $class->read_unittab();
    my $have_hr = $class->unit_have($have);
    my $want_hr = $class->unit_want($want);
    my %r = $class->unit_convert($have_hr, $want_hr);
    return %r;
}

sub default_unittabs {
  grep { -e } qw(/usr/lib/unittab);
}

sub env_unittabs {
  no warnings 'uninitialized';
  split /$Config{path_sep}/, $ENV{UNITTAB};
}

sub process_args {
    my( $class, @args ) = @_;

    my @unittabs;
    while (@args and $args[0] =~ /^-/) {
      my $flag = shift @args;
      if ($flag =~ s/\A\-f//) {
        my $file = $flag;
        $file = shift @args if (length($file) == 0);
        $class->usage() unless defined $file;
        push @unittabs, $file;
      } elsif ($flag eq '--') {
        last;
      } elsif ($flag =~ /^--version$/) {
        print "perl units version $VERSION.\n";
        exit 0;
      } else {
        warn "Unknown flag: $flag.\n";
        $class->usage();
      }
    }

    $class->usage() if @args == 1 || @args > 2;

    @unittabs = $class->env_unittabs unless @unittabs;
    @unittabs = $class->default_unittabs unless @unittabs;

    { unittabs => \@unittabs, args => \@args }
}

sub read_unittab {
  my( $class, $file ) = @_;

  my $fh;
  if (defined $file) {
    unless (-d $file) {
      open $fh, '<:encoding(UTF-8)', $file or do {
        die "Could not open <$file>: $!\n";
      };
      $class->read_defs($file, $fh);
      return;
    }
  }
  debug_d('Reading from DATA');
  open $fh, '<:encoding(UTF-8)', __FILE__ or die;
  while (<$fh>) {
    last if /\A__(?:DATA|END)__/;
  }
  $class->read_defs('DATA', $fh);
}

sub unit_have {
  my ($class, $have) = @_;

  trim($have);

  my $is_negative = 0;
  if ($have =~ /^[-]/) {
    $is_negative = 1;
    $have =~ s/^[-]//;  # remove minus sign
  }

  my $is_quantified = $have =~ /^[\d.]+/;

  if ($have =~ s/^\s*\#\s*//) {
    if ($class->definition_line($have)) {
      print "Defined.\n";
    } else {
      print "Error: $PARSE_ERROR.\n";
    }
    return;
  }
  return unless $have =~ /\S/;

  my $hu = $class->parse_unit($have);

  if (is_Zero($hu)) {
    print $PARSE_ERROR, "\n";
    return;
  }

  return { have => $have, hu => $hu, neg => $is_negative, quan => $is_quantified };
}

sub unit_want {
    my ($class, $want) = @_;

    trim($want);
    return unless $want =~ /\S/;

    my $wu = $class->parse_unit($want);

    if (is_Zero($wu)) {
      print $PARSE_ERROR, "\n";
    }
    return { want => $want, wu => $wu };
}

sub unit_convert {
    my ($class, $have_hr, $want_hr ) = @_;

    my $have = $have_hr->{have};
    my $hu = $have_hr->{hu};
    my $is_negative = $have_hr->{neg};
    my $is_quantified = $have_hr->{quan};

    my $want = $want_hr->{want};
    my $wu = $want_hr->{wu};

    debug_t('have unit', dumper($hu));
    debug_t('want unit', dumper($wu));

    my $is_temperature = 0;
    $is_temperature++ if $hu->{Temperature};
    $is_temperature++ if $wu->{Temperature};

    my $quot
        = $is_temperature == 2
        ? undef
        : unit_divide($hu, $wu);

    my %retval;

    if ($is_temperature == 2) {
        # we have temperature units
        $have =~ s/^[-]?[\d.]*\s*//;
        my $v = $hu->{'_'};
        $v *= -1 if $is_negative;
        $v  =  0 if not $is_quantified;
        my $k
            = exists $hu->{hof}
            ? $hu->{hof}->{to}->($v)
            : $v;
        my $t
            = exists $wu->{hof}
            ? $wu->{hof}->{from}->($k)
            : $k;
        %retval = ( type => 'temperature', v => $v, have => $have, t => $t, want => $want );
    }
    elsif (is_dimensionless($quot)) {
      my $q = $quot->{_};
      my $p = 1/$q;
      %retval = ( type => 'dimless', q => $q, p => $p);
    }
    else {
      %retval = ( type=> 'error', msg =>
        "conformability (Not the same dimension)\n" .
        "\t" . $have . " is " . text_unit($hu) . "\n" .
        "\t" . $want . " is " . text_unit($wu) . "\n"
        );
    }

    return %retval;
}

sub print_result {
    my (%r) = @_;
    printf "\t%.6g %s is %.6g %s\n", $r{v}, $r{have}, $r{t}, $r{want}
        if $r{type} eq 'temperature';
    printf "\t* %.6g\n\t/ %.6g\n", $r{q}, $r{p}
        if $r{type} eq 'dimless';
    print $r{msg} if $r{type} eq 'error';
}

################################################################

sub usage {
  my( $class ) = @_;
  require Pod::Usage;
  Pod::Usage::pod2usage({ -exitval => 1, -verbose => 0 });
}

sub read_defs {
  my ($class, $filename, $fh) = @_;
  while (<$fh>) {
  	next if m|\A/|;  # comment line
    trim($_);
    next unless /\S/;

    debug_d( "$_" );
    my $hash = $class->definition_line($_);
    foreach my $key ( keys %$hash ) {
      $unittab{$key} = $hash->{$key};
    }
  }
}

sub definition_line {
  my ($class, $line) = @_;
  my ($name, $data) = split /\s+/, $line, 2;
  my $value = $class->parse_unit($data);
  debug_t("$name => $data") if $data =~ /^\{\s/;
  my $rc = do {
    if ($data =~ /^\{\s/) {
        my $hof = eval $data;   # hash of functions
        +{ $name => { _ => 1, hof => $hof, Temperature => 1 } }
    }
    elsif (is_Zero($value))        { undef                              }
    elsif (is_fundamental($value)) { +{ $name => {_ => 1, $name => 1} } }
    else                           { +{ $name => $value               } }
  };

  unless( defined $rc ) {
    $line =~ s/\s+/ => /;
    warn "Parse error: $PARSE_ERROR in $line.  Skipping.\n";
    $rc = {};
  }

  return $rc;
}

sub trim {              # note that trim() is a L-value sub
  $_[0] =~ s/\#.*$//;;
  $_[0] =~ s/\s+$//;
  $_[0] =~ s/^\s+//;
}

sub Zero () { +{ _ => 0 } }

# here we guard the zero test by first checking to see
# if we're dealing with a temperature
sub is_Zero { !$_[0]{Temperature} && !$_[0]{_} }

sub unit_lookup {
  my ($name) = @_;
  debug_l( "Looking up unit '$name'" );
  return $unittab{$name} if exists $unittab{$name};
  if ($name =~ /s$/) {
    my $shortname = $name;
    $shortname =~ s/s$//;
    return $unittab{$shortname} if exists $unittab{$shortname};
  }
  my ($prefix, $rest) = ($name =~ /^($PREF-?)(.*)/o);
  unless ($prefix) {
    $PARSE_ERROR = "Unknown unit '$name'";
    return Zero;
  }
  my $base_unit = unit_lookup($rest); # Recursive
  con_multiply($base_unit, 10**$PREF{$prefix});
}

sub unit_multiply {
  my ($a, $b) = @_;
  debug_o( "Multiplying @{[%$a]} by @{[%$b]}: " );
  my $r = {%$a};
  $r->{_} *= $b->{_};
  for my $u (keys %$b) {
    next if $u eq '_';
    $r->{$u} += $b->{$u};
  }
  debug_o( "\tResult: @{[%$r]}" );
  $r;
}

sub unit_divide {
  my ($a, $b) = @_;
  my $r = {%$a};
  die "Division by zero error" if $b->{_} == 0;
  $r->{_} /= $b->{_};
  for my $u (keys %$b) {
    next if $u eq '_';
    $r->{$u} -= $b->{$u};
  }
  $r;
}

sub unit_power {
  my ($p, $u) = @_;
  debug_o( "Raising unit @{[%$u]} to power $p." );
  my $r = {%$u};
  $r->{_} **= $p;
  for my $d (keys %$r) {
    next if $d eq '_';
    $r->{$d} *= $p;
  }
  debug_o( "\tResult: @{[%$r]}" );
  $r;
}

sub unit_dimensionless {
  debug_o( "Turning $_[0] into a dimensionless unit." );
  return +{_ => $_[0]};
}

sub con_multiply {
  my ($u, $c) = @_;
  debug_o( "Multiplying unit @{[%$u]} by constant $c." );
  my $r = {%$u};
  $r->{_} *= $c;
  debug_o( "\tResult: @{[%$r]}" );
  $r;
}

sub is_dimensionless {
  my ($r) = @_;
  for my $u (keys %$r) {
    next if $u eq '_';
    return if $r->{$u} != 0;
  }
  return 1;
}

# Generate bogus unit value that signals that a new fundamental unit
# is being defined
sub new_fundamental_unit {
  return +{__ => 'new', _ => 1};
}

# Recognize this bogus value when it appears again.
sub is_fundamental {
  exists $_[0]{__};
}

sub text_unit {
  my ($u) = @_;
  my (@pos, @neg);
  my $c = $u->{_};
  for my $k (sort keys %$u) {
    next if $k eq '_' or $k eq 'hof';
    push @pos, $k if $u->{$k} > 0;
    push @neg, $k if $u->{$k} < 0;
  }
  my $text = ($c == 1 ? '' : $c);
  for my $d (@pos) {
    my $e = $u->{$d};
    $text .= " $d";
    $text .= "^$e" if $e > 1;
  }

  $text .= ' per' if @neg;
  for my $d (@neg) {
    my $e = - $u->{$d};
    $text .= " $d";
    $text .= "^$e" if $e > 1;
  }

  $text;
}
################################################################
#
# I'm the parser
#

our @actions;
BEGIN {
  sub sh { ['shift', $_[0]]  };
  sub go { ['goto', $_[0]] };

  my $eof_state = 98;

  @actions =
    (
     # Initial state
     {
     PREFIX      => sh(1),
     NUMBER      => sh(2),
     NAME        => sh(3),
     FUNDAMENTAL => sh(4),
     FRACTION    => sh(5),
     POWER       => sh(17),
     '('         => sh(6),
     'unit'      => go(7),
     'topunit'   => go($eof_state),
     'constant'  => go(8),
     },

     # State 1:   constant -> PREFIX .
     { _ => ['reduce', 1, 'constant']},

     # State 2:   constant -> NUMBER .
     { _ => ['reduce', 1, 'constant']},

     # State 3:   unit -> NAME .
     { _ => ['reduce', 1, 'unit', \&unit_lookup ]},

     # State 4:   unit -> FUNDAMENTAL .
     { _ => ['reduce', 1, 'unit', \&new_fundamental_unit ]},

     # State 5:   constant -> FRACTION .
     { _ => ['reduce', 1, 'constant']},

     # State 6:   unit -> '(' . unit ')'
     {PREFIX      => sh(1),
      NUMBER      => sh(2),
      NAME        => sh(3),
      FUNDAMENTAL => sh(4),
      FRACTION    => sh(5),
      '('         => sh(6),
      'unit'      => go(9),
      'constant'  => go(8),
     },

     # State 7:   topunit -> unit .
     #            unit  ->  unit . TIMES unit
     #            unit  ->  unit . DIVIDE unit
     #            unit  ->  unit . NUMBER
     {NUMBER => sh(10),
      TIMES  => sh(11),
      DIVIDE => sh(12),
      POWER  => sh(17),
      _      =>  ['reduce', 1, 'topunit'],
     },

     # State 8:   unit -> constant . unit
     #            unit -> constant .
     {PREFIX      => sh(1),
      NUMBER      => sh(2), # Shift-reduce conflict resolved in favor of shift
      NAME        => sh(3),
      FUNDAMENTAL => sh(4),
      FRACTION    => sh(5),
      '('         => sh(6),
      _           => ['reduce', 1, 'unit', \&unit_dimensionless],
      'unit'      => go(13),
      'constant'  => go(8),
     },

     # State 9:   unit -> unit . TIMES unit
     #            unit -> unit . DIVIDE unit
     #            unit -> '(' unit . ')'
     #            unit -> unit . NUMBER
     {NUMBER => sh(10),
      TIMES  => sh(11),
      DIVIDE => sh(12),
      POWER  => sh(17),
      ')'    => sh(14),
     },

     # State 10:  unit -> unit NUMBER .
     { _ => ['reduce', 2, 'unit',
         sub {
           unless (int($_[1]) == $_[1]) {
             ABORT("Nonintegral power $_[1]");
             return Zero;
           }
           unit_power(@_);
         }
        ],
     },

     # State 11:  unit -> unit TIMES . unit
     {PREFIX      => sh(1),
      NUMBER      => sh(2),
      NAME        => sh(3),
      FUNDAMENTAL => sh(4),
      FRACTION    => sh(5),
      '('         => sh(6),
      'unit'      => go(15),
      'constant'  => go(8),
     },

     # State 12:  unit -> unit DIVIDE . unit
     {PREFIX      => sh(1),
      NUMBER      => sh(2),
      NAME        => sh(3),
      FUNDAMENTAL => sh(4),
      FRACTION    => sh(5),
      '('         => sh(6),
      'unit'      => go(16),
      'constant'  => go(8),
     },

     # State 13:  unit -> unit . TIMES unit
     #            unit -> unit . DIVIDE unit
     #            unit -> constant unit .
     #            unit -> unit . NUMBER
     {NUMBER => sh(10),  # Shift-reduce conflict resolved in favor of shift
      TIMES  => sh(11),  # Shift-reduce conflict resolved in favor of shift
      DIVIDE => sh(12),  # Shift-reduce conflict resolved in favor of shift
      POWER  => sh(17),
      _      => ['reduce', 2, 'unit', \&con_multiply],
     },

     # State 14: unit => '(' unit ')' .
     { _ => ['reduce', 3, 'unit', sub {$_[1]}] },

     # State 15: unit  ->  unit . TIMES unit
     #           unit  ->  unit TIMES unit .
     #           unit  ->  unit . DIVIDE unit
     #           unit  ->  unit . NUMBER
     {NUMBER => sh(10), # Shift-reduce conflict resolved in favor of shift
      _ => ['reduce', 3, 'unit', sub {unit_multiply($_[0], $_[2])}],
     },

     # State 16: unit  ->  unit . TIMES unit
     #           unit  ->  unit DIVIDE unit .
     #           unit  ->  unit . DIVIDE unit
     #           unit  ->  unit . NUMBER
     {NUMBER => sh(10), # Shift-reduce conflict resolved in favor of shift
      _ => ['reduce', 3, 'unit', sub{unit_divide($_[2], $_[0])}],
     },

     # State 17:  unit -> unit POWER . unit
     {
      NUMBER      => sh(2),
      'constant'  => go(18),
     },

     # State 18: unit -> unit POWER
     {
     NUMBER => sh(2),
     _ => ['reduce', 3, 'unit', sub{ unit_power($_[0], $_[2])}],
     },

    );

    $actions[98] = {EOF => go($eof_state + 1),};
    $actions[99] = {_   => ['accept']};
}

sub ABORT {
  $PARSE_ERROR = shift;
}

sub parse_unit {
  my ($class, $s) = @_;
  my $tokens = lex($s);
  my $STATE = 0;
  my (@state_st, @val_st);

  $PARSE_ERROR = undef;

  debug_p(  '-' x 50 . "\n" );
  # Now let's run the parser
  for (;;) {
    return Zero if $PARSE_ERROR;

    debug_p( "Tokens: " . join( ' ', map { "<$_>" } @$tokens ) );
    my $la = @$tokens ? token_type($tokens->[0]) : 'EOF';
    debug_p( "Now in state $STATE.  Lookahead type is $la." );
    debug_p( "State stack is (@state_st)." );
    my $actiontab = $actions[$STATE];
    my $action = $actiontab->{$la} || $actiontab->{_};
    unless ($action) {
      $PARSE_ERROR = 'Syntax error';
      return Zero;
    }

    my ($primary, @actargs) = @$action;
    debug_p( "Next thing: $primary (@actargs)" );
    if ($primary eq 'accept') {
      return $val_st[0];    # Success!
    } elsif ($primary eq 'shift') {
      my $token = shift @$tokens;
      my $val = token_value($token);
      debug_p( "shift: token: <$token> val: <$val>" );
      push @val_st, $val;
      push @state_st, $STATE;
      $STATE = $actargs[0];
      debug_p( "shift: state: <$STATE>" );
    } elsif ($primary eq 'goto') {
      $STATE = $actargs[0];
    } elsif ($primary eq 'reduce') {
      my ($n_args, $result_type, $semantic) = @actargs;
      my @arglist;
      while ($n_args--) {
        push @arglist, pop @val_st;
        $STATE = pop @state_st;
      }
      my $result = $semantic ? &$semantic(@arglist) : $arglist[0];
      push @val_st, $result;
      push @state_st, $STATE;
    debug_p( "reduce: Value stack is " . dumper( \@val_st ) );

      debug_p( "Post-reduction state is $STATE." );

      # Now look for 'goto' actions
      my $goto = $actions[$STATE]{$result_type};
      unless ($goto && $goto->[0] eq 'goto') {
        die "No post-reduction goto in state $STATE for $result_type.\n";
      }
      debug_p( "goto $goto->[1]" );
      $STATE = $goto->[1];
    } else {
      die "Bad primary $primary";
    }
  }
}


sub lex {
  my ($s) = @_;
  my $N = '(?:\d+\.\d+|\d+|\.\d+)(?:[eE][-+]?\d+)?';

  my @t = split /(
                   (?: \*.\* | !.! ) # Special 'new unit' symbol
                |  [()*-]                    # Symbol
                |  \s*(?:\/|\bper\b)\s*      # Division
                |  (?:$N\|$N)                # Fraction
                |  $N                        # Decimal number
                |  \d+                       # Integer
                |  [A-Za-z_][A-Za-z_.]*      # identifier
                |  \s+                       # White space
                )/ox, $s;
  @t = grep {defined and $_ ne ''} @t;  # Discard empty and all-white tokens
  debug_p( "Input: $s Tokens: @t" );
  \@t;
}

sub token_type {
  my ($token) = @_;
  return $token->[0]   if ref $token;
  return $token        if $token =~ /[()]/;
  return 'TIMES'       if $token =~ /^\s+$/;
  return 'FUNDAMENTAL' if $token =~ m/\A(!.!|\*.\*)\z/;
  return 'DIVIDE'      if $token =~ /^\s*(\/|\bper\b)\s*$/;
  return 'TIMES'       if $token eq '*' || $token eq '-';
  return 'FRACTION'    if $token =~ /^\d+\|\d+$/;
  return 'NUMBER'      if $token =~ /^[.\d]/;
  return 'POWER'       if $token eq '^';
  return 'NAME';
}

sub token_value {
  my ($token) = @_;
  debug_p( "TOKEN VALUE: <$token>" );

  my $rc = do {
       if( $token =~ /^([()*\/-]|\s*\bper\b\s*)$/ ) { $token }
    elsif( $token =~ /(\d+)\|(\d+)/ ) {
      if( $2 == 0 ) {
        ABORT("Zero denominator in fraction '$token'");
        return 0;
      }
      $1/$2;
    }
    else { $token }
  };

  return $rc;        # Perl takes care of the others.
}

=encoding utf8

=head1 NAME

units - conversion program

=head1 SYNOPSIS

    % units
	You have: in
	You want: cm
		* 2.54
		/ 0.393701

    % units [-f /path/to/unittab] [want_unit have_unit]

=head1 OPTIONS

    -f           Use specified definition file
    --version    Display version information

=head1 DESCRIPTION

NOTE: This does not handle the Gnu units format (https://www.gnu.org/software/units/).

The units program converts quantities expressed in various scales to their
equivalents in other scales.  The units program can only handle multiplicative
or affine scale changes (except for temperature).  It works in one of
two ways.  If given two units as command line arguments, it reports
the conversion.  Otherwise, it operates interactively by prompting the user
for inputs:

    % units
    You have: meters
    You want: feet
        * 3.2808399
        / 0.3048

    You have: cm3
    You want: gallons
        * 0.00026417205
        / 3785.4118

    You have: meters/s
    You want: furlongs/fortnight
        * 6012.8848
        / 0.00016630952

    You have: 1|2 inch
    You want: cm
        * 1.27
        / 0.78740157

    You have: 98.6 F
    You want: C
        98.6 F is 37 C

    You have: -40 C
    You want: F
        -40 C is -40 F

Powers of units can be specified using the '^' character as shown in the
example, or by simple concatenation: 'cm3' is equivalent to 'cm^3'.

Multiplication of units can be specified by using spaces, a dash or an asterisk.

Division of units is indicated by the slash ('/').  Note that multiplication has
a higher precedence than division, so 'm/s/s' is the same as 'm/s^2' or 'm/s s'.
Division of numbers must be indicated using the vertical bar ('|').  To convert
half a meter, you would write '1|2 meter'.  If you write '1/2 meter' then the
units program would interpret that as equivalent to '0.5/meter'.

If you enter incompatible unit types, the units program will print a message
indicating that the units are not conformable and it will display the reduced
form for each unit:

    You have: ergs/hour
    You want: fathoms kg^2 / day
    conformability error
         2.7777778e-11 kg m^2 / sec^3
         2.1166667e-05 kg^2 m / sec

The conversion information is read from a units data file.  The default file
includes definitions for most familiar units, abbreviations and metric
prefixes.  Some constants of nature included are:

    pi         ratio of circumference to diameter
    c          speed of light
    e          charge on an electron
    g          acceleration of gravity
    force      same as g
    mole       Avogadro's number
    water      pressure per unit height of water
    mercury    pressure per unit height of mercury
    au         astronomical unit

The unit 'pound' is a unit of mass.  Compound names are run together so 'pound
force' is a unit of force.  The unit 'ounce' is also a unit of mass.  The fluid
ounce is 'floz'.  British units that differ from their US counterparts are
prefixed with 'br', and currency is prefixed with its country name:
'belgiumfranc', 'britainpound'.  When searching for a unit, if the specified
string does not appear exactly as a unit name, then units will try to remove a
trailing 's' or a trailing 'es' and check again for a match.

To find out what units are available read the standard units file.  If you want
to add your own units you can supply your own file.  If no standard file
exists and you do not supply your own file, this program uses internal
data.

A unit is specified on a single line by giving its name and an equivalence.  Be
careful to define new units in terms of old ones so that reductions leads to
primitive units.  Primitive (a.k.a. fundamental) units are defined
with a string of three characters which begin and end with '*' or '!'.
Note that the units program will not detect infinite loops that could be
caused by careless unit definitions.

Comments in the unit definition file begin with a '/' or '#' character at
the beginning of a line.  Once the parser has successfully parsed a
unit name and it's definition, the remainder of the line is ignored.
This makes it safe to include in-line comments.

Prefixes are defined in the same way as standard units, but with a
trailing dash at the end of the prefix name.  If a unit is not found even
after removing trailing 's' or 'es', then it will be checked against the
list of prefixes.  Prefixes will be removed until a legal base unit is
identified.

Here is an example of a short units file that defines some basic units.

    m           !a!
    sec         ***
    Temperature ***
    micro-      1e-6
    minute      60 sec
    hour        60 min
    inch        0.0254 m
    ft          12 inches
    mile        5280 ft

If a "Temperature" dimension is defined in the units table, then
you can define various temperature scales as units by specifying
the code needed to convert the unit to or from Kelvin.
The built-in units table has definitions for Kelvin (K), Celsius (C),
Fahrenheit (F) and Rankine (R).

The code consists of a perl hash containing the keys 'to' and 'from'.
The values are the subroutine definitions necessary to convert a
value from Kelvin to the specified unit, or to Kelvin from the the
specified unit.  See the built-in unit table for examples.

A temperature unit entered at "You have" without any constant
preceding it will default to zero units.  This is in contrast to
non-temperature units, where a bare unit name is assumed to mean 1
unit.  Also, for temperatures only, negative constants are allowed.
This enables, for example, a conversation between -40C and F.

=head1 AUTHOR

Mark-Jason Dominus, C<<  >>

Temperature support by Gary Puckering, C<<  >>

Currently maintained in https://github.com/briandfoy/PerlPowerTools

=head1 BUGS

=head1 COPYRIGHT and LICENSE

This program is copyright (c) M-J. Dominus (1996, 1999).

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version, or under Perl's 'Artistic License'.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

=cut

no warnings qw(void);
__PACKAGE__;

__END__