Adapt allomorph classes documentation for Allomorph class

- Condense the introduction and link to the Allomorph class documentation - Remove documentation for methods inherited from the Allomorph class - While here document the === operator for the allomorph classes
Raku · Jun 1, 2021 · 6bada45 · 6bada45
1 parent aa95971
commit 6bada45
Show file tree

Hide file tree

Showing 4 changed files with 76 additions and 222 deletions.
diff --git a/doc/Type/ComplexStr.pod6 b/doc/Type/ComplexStr.pod6
@@ -4,24 +4,24 @@
 
 =SUBTITLE Dual value complex number and string
 
-    class ComplexStr is Complex is Str {}
+    class ComplexStr is Allomorph is Complex {}
 
-The dual value types (often referred to as L<allomorphs|/language/glossary#Allomorph>)
-allow for the representation of a value as both a string and a numeric type. Typically
-they will be created for you when the context is "stringy" but they can be determined
-to be numbers, such as in some L<quoting constructs|/language/quoting>:
+C<ComplexStr> is a dual value type, a subclass of both
+L«C<Allomorph>|/type/Allomorph», hence L«C<Str>|/type/Str», and
+L«C<Complex>|/type/Complex».
 
-    my $f = <42+0i>; say $f.^name; # OUTPUT: «ComplexStr␤»
+See L«C<Allomorph>|/type/Allomorph» for further details.
 
-As a subclass of both L«C<Complex>|/type/Complex» and L«C<Str>|/type/Str»,
-a C<ComplexStr> will be accepted where either is expected. However,
-C<ComplexStr> does not share object identity with C<Complex>- or C<Str>-only
-variants:
+=begin code
+my $complex-str = <42+0i>;
+say $complex-str.^name;             # OUTPUT: «ComplexStr␤»
 
-    my $complex-str = < 42+0i >;
-    my Complex $complex = $complex-str; # OK!
-    my Str     $str     = $complex-str; # OK!
-    say 42+0i ∈ <42+0i  55  1>; # False; ∈ operator cares about object identity
+my Complex $complex = $complex-str; # OK!
+my Str     $str     = $complex-str; # OK!
+
+# ∈ operator cares about object identity
+say 42+0i ∈ <42+0i  55  1>;         # OUTPUT: «False␤»
+=end code
 
 =head1 Methods
 
@@ -36,17 +36,6 @@ directly the values can be whatever is required:
     say +$f; # OUTPUT: «42+0i␤»
     say ~$f; # OUTPUT: «"forty two (but complicated)"␤»
 
-=head2 method Bool
-
-Defined as:
-
-    multi method Bool(ComplexStr:D: --> Bool:D)
-
-I<This method may be provided by the parent classes and not implemented in ComplexStr directly>.
-
-Returns C<False> if the invocant is numerically C<±0±0i>, otherwise returns C<True>. String portion
-is not considered.
-
 =head2 method Capture
 
 Defined as:
@@ -85,41 +74,15 @@ coercion L<fails|/routine/fail> with C<X::Numeric::Real>.
 The C<:D> variant returns the result of that coercion. The C<:U> variant issues
 a warning about using an uninitialized value in numeric context and then returns value C<0e0>.
 
-=head2 method Str
-
-Returns the string value of the C<ComplexStr>.
-
-=head2 method ACCEPTS
-
-Defined as:
-
-    multi method ACCEPTS(ComplexStr:D: Any:D $value)
-
-If C<$value> is L<Numeric|/type/Numeric> (including another
-L<allomorph|/language/glossary#index-entry-Allomorph>), checks if invocant's
-L<Numeric|/type/Numeric> part L<ACCEPTS|/type/Numeric#method_ACCEPTS> the C<$value>.
-If C<$value> is L<Str|/type/Str>, checks if invocant's L<Str|/type/Str> part
-L<ACCEPTS|/type/Str#method_ACCEPTS> the C<$value>. If value is anything else,
-checks if both L<Numeric|/type/Numeric> and L<Str|/type/Str> parts C<ACCEPTS> the C<$value>.
-
-    say < 5+0i> ~~ "5.0"; # OUTPUT: «False␤»
-    say < 5+0i> ~~  5.0 ; # OUTPUT: «True␤»
-    say < 5+0i> ~~ <5.0>; # OUTPUT: «True␤»
-
 =head1 Operators
 
-=head2 infix cmp
-
-    multi sub infix:<cmp>(ComplexStr:D $a, ComplexStr:D $b)
+=head2 infix C«===»
 
-Compare two C<ComplexStr> objects.  The comparison is done on the C<Complex> value first and
-then on the C<Str> value. If you want to compare in a different order then you would
-coerce to the C<Complex> or C<Str> values first:
+    multi sub infix:<===>(ComplexStr:D $a, ComplexStr:D $b)
 
-    my $f = ComplexStr.new(42+0i, "smaller");
-    my $g = ComplexStr.new(43+0i, "larger");
-    say $f cmp $g;          # OUTPUT: «Less␤»
-    say $f.Str cmp $g.Str;  # OUTPUT: «More␤»
+C<ComplexStr> Value identity operator. Returns C<True> if the C<Complex>
+values of C<$a> and C<$b> are L<identical|/routine/===> and their C<Str>
+values are also L<identical|/routine/===>. Returns C<False> otherwise.
 
 =end pod
 

diff --git a/doc/Type/IntStr.pod6 b/doc/Type/IntStr.pod6
@@ -4,23 +4,24 @@
 
 =SUBTITLE Dual value integer and string
 
-    class IntStr is Int is Str { }
+    class IntStr is Allomorph is Int { }
 
-The dual value types (often referred to as L<allomorphs|/language/glossary#Allomorph>)
-allow for the representation of a value as both a string and a numeric type. Typically
-they will be created for you when the context is "stringy" but they can be determined
-to be numbers, such as in some L<quoting constructs|/language/quoting>:
+C<IntStr> is a dual value type, a subclass of both
+L«C<Allomorph>|/type/Allomorph», hence L«C<Str>|/type/Str», and
+L«C<Int>|/type/Int».
 
-    my $f = <42>; say $f.^name; # OUTPUT: «IntStr␤»
+See L«C<Allomorph>|/type/Allomorph» for further details.
 
-As a subclass of both L«C<Int>|/type/Int» and L«C<Str>|/type/Str», an C<IntStr>
-will be accepted where either is expected. However, C<IntStr> does not share
-object identity with C<Int>- or C<Str>-only variants:
+=begin code
+my $int-str = <42>;
+say $int-str.^name;     # OUTPUT: «IntStr␤»
 
-    my $int-str = <42>;
-    my Int $int = $int-str; # OK!
-    my Str $str = $int-str; # OK!
-    say 42 ∈ <42  55  1>;   # False; ∈ operator cares about object identity
+my Int $int = $int-str; # OK!
+my Str $str = $int-str; # OK!
+
+# ∈ operator cares about object identity
+say 42 ∈ <42  55  1>;   # OUTPUT: «False␤»
+=end code
 
 =head1 Methods
 
@@ -35,17 +36,6 @@ directly the values can be whatever is required:
     say +$f; # OUTPUT: «42␤»
     say ~$f; # OUTPUT: «"forty two"␤»
 
-=head2 method Bool
-
-Defined as:
-
-    multi method Bool(IntStr:D: --> Bool:D)
-
-I<This method may be provided by the parent classes and not implemented in IntStr directly>.
-
-Returns C<False> if the invocant is numerically C<0>, otherwise returns C<True>. String portion
-is not considered.
-
 =head2 method Int
 
     method Int
@@ -72,41 +62,15 @@ Defined as:
 The C<:D> variant returns the numeric portion of the invocant. The C<:U> variant issues
 a warning about using an uninitialized value in numeric context and then returns value C<0>.
 
-=head2 method Str
-
-Returns the string value of the C<IntStr>.
-
-=head2 method ACCEPTS
-
-Defined as:
-
-    multi method ACCEPTS(IntStr:D: Any:D $value)
-
-If C<$value> is L<Numeric|/type/Numeric> (including another
-L<allomorph|/language/glossary#index-entry-Allomorph>), checks if invocant's
-L<Numeric|/type/Numeric> part L<ACCEPTS|/type/Numeric#method_ACCEPTS> the C<$value>. If
-C<$value> is L<Str|/type/Str>, checks if invocant's L<Str|/type/Str> part
-L<ACCEPTS|/type/Str#method_ACCEPTS> the C<$value>. If value is anything else,
-checks if both L<Numeric|/type/Numeric> and L<Str|/type/Str> parts C<ACCEPTS> the C<$value>.
-
-    say <5> ~~ "5.0"; # OUTPUT: «False␤»
-    say <5> ~~  5.0 ; # OUTPUT: «True␤»
-    say <5> ~~ <5.0>; # OUTPUT: «True␤»
-
 =head1 Operators
 
-=head2 infix cmp
-
-    multi sub infix:<cmp>(IntStr:D $a, IntStr:D $b)
+=head2 infix C«===»
 
-Compare two C<IntStr> objects.  The comparison is done on the C<Int> value first and
-then on the C<Str> value. If you want to compare in a different order then you would
-coerce to an C<Int> or C<Str> value first:
+    multi sub infix:<===>(IntStr:D $a, IntStr:D $b)
 
-    my $f = IntStr.new(42, "smaller");
-    my $g = IntStr.new(43, "larger");
-    say $f cmp $g;          # OUTPUT: «Less␤»
-    say $f.Str cmp $g.Str;  # OUTPUT: «More␤»
+C<IntStr> Value identity operator. Returns C<True> if the C<Int>
+values of C<$a> and C<$b> are L<identical|/routine/===> and their C<Str>
+values are also L<identical|/routine/===>. Returns C<False> otherwise.
 
 =end pod
 

diff --git a/doc/Type/NumStr.pod6 b/doc/Type/NumStr.pod6
@@ -4,23 +4,24 @@
 
 =SUBTITLE Dual value floating-point number and string
 
-    class NumStr is Num is Str { }
+    class NumStr is Allomorph is Num { }
 
-The dual value types (often referred to as L<allomorphs|/language/glossary#Allomorph>)
-allow for the representation of a value as both a string and a numeric type. Typically
-they will be created for you when the context is "stringy" but they can be determined
-to be numbers, such as in some L<quoting constructs|/language/quoting>:
+C<NumStr> is a dual value type, a subclass of both
+L«C<Allomorph>|/type/Allomorph», hence L«C<Str>|/type/Str», and
+L«C<Num>|/type/Num».
 
-    my $f = <42.1e0>; say $f.^name; # OUTPUT: «NumStr␤»
+See L«C<Allomorph>|/type/Allomorph» for further details.
 
-As a subclass of both L«C<Num>|/type/Num» and L«C<Str>|/type/Str», a C<NumStr>
-will be accepted where either is expected. However, C<NumStr> does not share
-object identity with C<Num>- or C<Str>-only variants:
+=begin code
+my $num-str = <42.1e0>;
+say $num-str.^name;         # OUTPUT: «NumStr␤»
 
-    my $num-str = <42e10>;
-    my Num $num = $num-str; # OK!
-    my Str $str = $num-str; # OK!
-    say 42e10 ∈ <42e10  55  1>; # False; ∈ operator cares about object identity
+my Num $num = $num-str;     # OK!
+my Str $str = $num-str;     # OK!
+
+# ∈ operator cares about object identity
+say 42e10 ∈ <42e10  55  1>; # OUTPUT: «False␤»
+=end code
 
 =head1 Methods
 
@@ -35,17 +36,6 @@ directly the values can be whatever is required:
     say +$f; # OUTPUT: «42.1␤»
     say ~$f; # OUTPUT: «"forty two and a bit"␤»
 
-=head2 method Bool
-
-Defined as:
-
-    multi method Bool(NumStr:D: --> Bool:D)
-
-I<This method may be provided by the parent classes and not implemented in NumStr directly>.
-
-Returns C<False> if the invocant is numerically C<±0e0>, otherwise returns C<True>. String portion
-is not considered.
-
 =head2 method Num
 
     method Num
@@ -72,41 +62,15 @@ Defined as:
 The C<:D> variant returns the numeric portion of the invocant. The C<:U> variant issues
 a warning about using an uninitialized value in numeric context and then returns value C<0e0>.
 
-=head2 method Str
-
-Returns the string value of the C<NumStr>.
-
-=head2 method ACCEPTS
-
-Defined as:
-
-    multi method ACCEPTS(NumStr:D: Any:D $value)
-
-If C<$value> is L<Numeric|/type/Numeric> (including another
-L<allomorph|/language/glossary#index-entry-Allomorph>), checks if invocant's
-L<Numeric|/type/Numeric> part L<ACCEPTS|/type/Numeric#method_ACCEPTS> the C<$value>. If
-C<$value> is L<Str|/type/Str>, checks if invocant's L<Str|/type/Str> part
-L<ACCEPTS|/type/Str#method_ACCEPTS> the C<$value>. If value is anything else,
-checks if both L<Numeric|/type/Numeric> and L<Str|/type/Str> parts C<ACCEPTS> the C<$value>.
-
-    say <5e0> ~~ "5.0"; # OUTPUT: «False␤»
-    say <5e0> ~~  5.0 ; # OUTPUT: «True␤»
-    say <5e0> ~~ <5.0>; # OUTPUT: «True␤»
-
 =head1 Operators
 
-=head2 infix cmp
-
-    multi sub infix:<cmp>(NumStr:D $a, NumStr:D $b)
+=head2 infix C«===»
 
-Compare two C<NumStr> objects.  The comparison is done on the C<Num> value first and
-then on the C<Str> value. If you want to compare in a different order then you would
-coerce to a C<Num> or C<Str> value first:
+    multi sub infix:<===>(NumStr:D $a, NumStr:D $b)
 
-    my $f = NumStr.new(42.1e0, "smaller");
-    my $g = NumStr.new(43.1e0, "larger");
-    say $f cmp $g;          # OUTPUT: «Less␤»
-    say $f.Str cmp $g.Str;  # OUTPUT: «More␤»
+C<NumStr> Value identity operator. Returns C<True> if the C<Num>
+values of C<$a> and C<$b> are L<identical|/routine/===> and their C<Str>
+values are also L<identical|/routine/===>. Returns C<False> otherwise.
 
 =end pod