=head1 TITLE

Dominant Value Expressions

=head1 VERSION

  Maintainer: Glenn Linderman <glenn@linderman.com>
  Date: 29 Sep 2000
  Last Modified: 30 Sep 2000
  Mailing List: perl6-language@perl.org
  Number: 356
  Version: 2
  Status: Frozen

=head1 ABSTRACT

An aid to determining if an input  value has an impact on the result of
an expression whole program.  Can also be used for Perl poetry.

=head1 CHANGES

Version 2 adds output function, examples, and freezes.

=head1 DESCRIPTION

This  is an  optional  feature; to  turn  it on,  "use domination;"  is
suggested.

When use domination  is in scope, two new  functions are available, and
new rules for expression evaluation obtain.  Each of these is described
in a subsection below.

=head2 Domination pragma

The "use domination 'output-function-name';" pragma enables the rest of
the  functionality.  It  should be  scoped, affecting  the  current and
nested blocks.  domination;", but allows user specification of a method
to  use  to  convert  dominant  values  to  output  strings.   This  is
implicitly  called only  when an  output  stream is  passed a  dominant
value.   If   an  output-function-name   is  not  supplied   with  "use
domination;", the following function is implied:

  sub output-dominant-value {
    return sprintf "DOMINANT(%g)", dominant_weight($_[0]);
  }

The  "no  domination;"  pragma  would  turn  off  the  effect  of  "use
domination;" for the current and nested blocks.  If a dominant value is
encountered  while "no  domination;" is  in  effect, it  is treated  as
"undef" by all scalar operators.


=head2 Dominant operation

The dominant operation takes a  scalar argument, which is considered to
be a weight parameter.  The scalar argument is converted to numeric, if
possible,  with the  resultant  positive weight  parameter producing  a
dominant value with  that given weight.  A scalar  argument that cannot
be automatically converted  to numeric, or that produces  a negative or
zero numeric value produces undef as a result.

   dominant 47    # produces a dominant value of weight 47
   dominant 0     # produces undef
   dominant -47   # produces undef
   dominant "ab"  # produces undef
   dominant "14"  # produces a dominant value of weight 14
   dominant undef # produces undef (and a warning if "use warnings")

=head2 Dominant_weight operation

The dominant_weight  operation takes a scalar argument.   If the scalar
argument  is a  dominant value,  it returns  its weight  as  a positive
number.  If the scalar argument is  not a dominant value, the return of
the dominant_weight operation is zero.

   dominant_weight dominant 47   # produces 47
   dominant_weight dominant 0    # produces 0
   dominant_weight dominant -47  # produces 0
   dominant_weight dominant "ab" # produces 0
   dominant_weight dominant "14" # produces 14
   dominant_weight 47            # produces 0
   dominant_weight 0           # produces 0
   dominant_weight "ab"      # produces 0
   dominant_weight "14"    # produces 0
   dominant_weight undef # produces 0 (and a warning if "use warnings")

=head2 Expressions involving dominant values

All scalar operations are affected  by the presence of dominant values.
If a scalar operation other than the dominant_weight operation involves
one  or  more dominant  values,  the result  of  the  operation is  the
heaviest (by weight) dominant value among the operands.  If no dominant
values are  supplied to the operation,  the result of  the operation is
the  same as  it would  be  according to  the usual  definition of  the
operation.

   use domination;
   $w = dominant 3;
   $x = dominant 47;
   $y = 33;
   $z = "abc";

   $x + $y                # produces dominant 47
   $w . $z                # produces dominant 3
   $w - $x                # produces dominant 47
   "$z $x"                # produces dominant 47
   $z =~ m/$w/;           # produces dominant 3
   $x =~ m/$z/;           # produces dominant 47
   defined $w             # produces dominant 3
   $x == $x               # produces dominant 47
   $w eq $w               # produces dominant 3
   $w > 17                # produces dominant 3
   $x > 17                # produces dominant 47
   print "Show me: $w\n"  # same result as: print "DOMINANT(3)"

   if ( $w )                       # considered false
   if ( dominant_weight $w > 17 )  # false
   if ( dominant_weight $x > 17 )  # true

=head1 COMPATIBILITY

New functionality, no compatibility issues.  The new functionality only
obtains if the "use domination;" pragma is in effect.

=head1 IMPLEMENTATION

The impact  of dominant value  expressions is pervasive,  affecting all
builtin scalar operators  in a minor way.  Any  operators doing item by
item operations  on each scalar  of a list  or hash would  be similarly
affected (various RFCs exist for extending scalar operations to work on
lists of values in "corresponding item" fashion).

=head1 REFERENCES

RFC 263: Add null() keyword and fundamental data type