Merge pull request #11 from pryrt/v0.017_002_namingconvention

v0.017_002 merge: I've solidified on naming convention (#6), at least for now.  Bring it back into the trunk and then tag an alpha release

Author: pryrt

CHANGES

@@ -1,14 +1,37 @@
 Revision history for Perl module Data::IEEE754::Tools.
 
 v0.017 internal development version
-    - v0.017_001: META = adding Travis-CI, coveralls.io, automatic signatures, etc.
+    - v0.017_001_github_integrations: META = adding Travis-CI, coveralls.io,
+      automatic signatures, etc.
+    - v0.017_002_namingconvention: start changing names per the naming-
+      convention issue#6
+      - make
+        :floatingpoint, to_hex_floatingpoint(), to_dec_floatingpoint()
+        aliases to
+        :convertToString, convertToHexString(),
+        convertToDecimalString()
+      - make
+        :raw754, hexstr754_from_double(), binstr754_from_double(),
+        hexstr754_to_double(), binstr754_to_double()
+        aliases to
+        :internalString, convertToInternalHexString(),
+        convertToInternalBinaryString(), convertFromInternalHexString(),
+        convertFromInternalBinaryString()
+      - figured out a framework for issue#7's multiple bitness, but disable
+        for now
+      - improve error messages, and stop module compile on mixed-endianness
+      - add test coverage for aliases
+      - add author test coverage for import-tags
+      - change VERSION from a version.pm object to a plain old string '0.017_002',
+        which allows the Makefile.PL to properly extract the {provides}{version}
+        for META files
 
 v0.016 2016-Aug-29
     - had a bug in v0.014 Makefile which caused CPAN to not
       index; tried a couple of submissions, none of which
       really did what I wanted.  Will try to move up to next
       public release version number (v0.016), and ask PAUSE
-      to forget the incorrect v0.14001.0 release, and hopefully
+      to forget the incorrect v0.14003.0 release, and hopefully
       re-index to this release.
 
 v0.014 2016-Aug-29

MANIFEST

@@ -4,9 +4,10 @@ Makefile.PL
 MANIFEST			This list of files
 lib/Data/IEEE754/Tools.pm
 README
+RELEASE.md
 t/00-load.t
-t/01-raw754.t
-t/02-floatingpoint.t
+t/01-internalstring.t
+t/02-converttostr.t
 t/03-ulp.t
 t/04-nextupdown.t
 t/05-nextafter.t
@@ -15,5 +16,7 @@ t/07-info.t
 t/08-totalorder.t
 t/09-signbit.t
 t/10-copysign.t
+t/11-aliases.t
 xt/00-sign.t
+xt/11-tags.t
 TODO

MANIFEST.SKIP

@@ -10,5 +10,4 @@
 pod.css
 ^.svn/
 ^MYMETA
-.travis.yml$
-^RELEASE.md$
+.travis.yml$

Makefile.PL

@@ -13,6 +13,7 @@ use 5.006;
         'warnings'      => 0,
         'strict'        => 0,
         'Carp'          => 0,
+        'Config'        => 0,
     },
 );
 
@@ -42,10 +43,16 @@ use 5.006;
         },
         # automatically determine the versions for 'provides'; MM->parse_version exists as of MM v6.31, so not a problem with >= 6.46
         #   => this comes out right when printed... but MYMETA.* shows values that look wrong
+            #my $vstr = MM->parse_version( $mm_args{VERSION_FROM} );
+            #print STDERR $vstr, $/;
+            #my $qstr = "'$vstr'";
+            #print STDERR $qstr, $/;
+            #(my $novstr = $qstr) =~ s/v//;
+            #print STDERR $novstr, $/;
         $mm_args{META_MERGE}{provides} = {
             $mm_args{NAME} => {
                 file => $mm_args{VERSION_FROM},
-                version => ''.MM->parse_version( $mm_args{VERSION_FROM} ),
+                version => MM->parse_version( $mm_args{VERSION_FROM} ),
             }
         };
     }
@@ -88,7 +95,7 @@ sub MY::postamble {
 TEST_D = $(ABSPERLRUN) -MExtUtils::Command -e test_d --
 
 # run a test coverage report
-testcover :: lib/Math/PRBS.pm
+testcover ::
 	$(NOECHO) cover -test -report html
 
 # run author-tests on the original

README

@@ -1,64 +1,61 @@
 NAME
-
-Data::IEEE754::Tools - Various tools for understanding and manipulating the underlying IEEE-754 representation of floating point values
+    Data::IEEE754::Tools - Various tools for understanding and manipulating
+    the underlying IEEE-754 representation of floating point values
 
 DESCRIPTION
-
-These tools give access to the underlying IEEE 754 floating-point 64bit
-representation used by many instances of Perl (see perlguts). They
-include functions for converting from the 64bit internal representation
-to a string that shows those bits (either as hexadecimal or binary) and
-back, functions for converting that encoded value into a more
-human-readable format to give insight into the meaning of the encoded
-values, and functions to manipulate the smallest possible change for a
-given floating-point value (which is the ULP
-<https://en.wikipedia.org/wiki/Unit_in_the_last_place> or "Unit in the
-Last Place").
-
-COMPATIBILITY
-
-Data::IEEE754::Tools works with 64bit floating-point representations.
-
-If you have a Perl setup which uses a larger representation (for
-example, "use Config; print $Config{nvsize}; # 16 => 128bit"), values
-reported by this module will be reduced in precision to fit the 64bit
-representation.
-
-If you have a Perl setup which uses a smaller representation (for
-example, "use Config; print $Config{nvsize}; # 4 => 32bit"), the
-installation will likely fail, because the unit tests were not set up
-for lower precision inputs. However, forcing the installation *might*
-still allow coercion from the smaller Perl NV into a true IEEE 754
-double (64bit) floating-point, but there is no guarantee it will work.
+    These tools give access to the underlying IEEE 754 floating-point 64bit
+    representation used by many instances of Perl (see perlguts). They
+    include functions for converting from the 64bit internal representation
+    to a string that shows those bits (either as hexadecimal or binary) and
+    back, functions for converting that encoded value into a more
+    human-readable format to give insight into the meaning of the encoded
+    values, and functions to manipulate the smallest possible change for a
+    given floating-point value (which is the ULP
+    <https://en.wikipedia.org/wiki/Unit_in_the_last_place> or "Unit in the
+    Last Place").
+
+  Compatibility
+    Data::IEEE754::Tools works with 64bit floating-point representations.
+
+    If you have a Perl setup which uses a larger representation (for
+    example, "use Config; print $Config{nvsize}; # 16 => 128bit"), values
+    reported by this module will be reduced in precision to fit the 64bit
+    representation.
+
+    If you have a Perl setup which uses a smaller representation (for
+    example, "use Config; print $Config{nvsize}; # 4 => 32bit"), the
+    installation will likely fail, because the unit tests were not set up
+    for lower precision inputs. However, forcing the installation *might*
+    still allow coercion from the smaller Perl NV into a true IEEE 754
+    double (64bit) floating-point, but there is no guarantee it will work.
 
 INSTALLATION
+    To install this module, use your favorite CPAN client.
 
-To install this module, use your favorite CPAN client.
-
-For a manual install, type the following:
+    For a manual install, type the following:
 
-    perl Makefile.PL
-    make
-    make test
-    make install
+        perl Makefile.PL
+        make
+        make test
+        make install
 
-(On Windows machines, you may need to use "dmake" instead of "make".)
+    (On Windows machines, you may need to use "dmake" instead of "make".)
 
 AUTHOR
+    Peter C. Jones "<petercj AT cpan DOT org>"
 
-Peter C. Jones <petercj AT cpan DOT org>
-
-Please report any bugs or feature requests emailing <bug-Data-IEEE754-Tools AT rt.cpan.org>
-or thru the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-IEEE754-Tools>
+    Please report any bugs or feature requests emailing
+    "<bug-Data-IEEE754-Tools AT rt.cpan.org>" or thru the web interface at
+    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-IEEE754-Tools>, or
+    thru the repository's interface at
+    <https://github.com/pryrt/Data-IEEE754-Tools/issues>.
 
 COPYRIGHT
+    Copyright (C) 2016 Peter C. Jones
 
-Copyright (C) 2016 Peter C. Jones
-
-LICENCE
-
-This program is free software; you can redistribute it and/or modify it
-under the terms of either: the GNU General Public License as published
-by the Free Software Foundation; or the Artistic License.
+LICENSE
+    This program is free software; you can redistribute it and/or modify it
+    under the terms of either: the GNU General Public License as published
+    by the Free Software Foundation; or the Artistic License.
 
-See <http://dev.perl.org/licenses/> for more information.
+    See <http://dev.perl.org/licenses/> for more information.

RELEASE.md

@@ -28,6 +28,9 @@ I use a local svn client to checkout the GitHub repo.  All these things can be d
     * **Verify Documentation:**
         * make sure versioning is correct
         * verify POD and README
+            * `pod2text lib/Data/IEEE754/Tools.pm README`, then edit so that only
+            NAME, DESCRIPTION, COMPATIBILITY, INSTALLATION, AUTHOR, COPYRIGHT, LICENSE
+            remain
         * verify HISTORY
 
     * **Build Distribution**

TODO

@@ -3,19 +3,24 @@ TODO
       + IEEE754 5.4.2 => 5.12
         <format>-convertFormat
         <format>-convertFromDecimalCharacter
-        <format>-convertToDecimalCharacter
+            # converts a string decimal number (ie, output of to_dec_floatingpoint)
+            #   into a <format>-floating point value
+        <format>-convertToDecimalCharacter(source, conversionSpecification)
             # alias for to_dec_floatingpoint()
             # conversionSpecification is supposed to indicate formatting
             #       might want to use an optional integer which indicates how many places
-            #       after the fractional-point to display (default to 16 => %16.16s for to_dec_floatingpoint)
+            #       after the fractional-point to display (default to 16 => %.16f for to_dec_floatingpoint)
       + IEEE754 5.4.3 => 5.12
         <format>-convertFromHexCharacter
+            # converts a string hexadecimal number (ie, output of to_hex_floatingpoint)
+            #   into a <format>-floating point value
         <format>-convertToHexCharacter(source, conversionSpecification)
             # alias for to_hex_floatingpoint()
             #       I originally thought these were aliases for my rawhex754 functions... but no
             # conversionSpecification is supposed to indicate formatting
             #       might want to use an optional integer which indicates how many places
-            #       after the fractional-point to display (default to 16 => %16.16s for to_dec_floatingpoint)
+            #       after the fractional-point to display (default to 13 => %13.13s for to_hex_floatingpoint)
+      + valid <format> = qw(binary32 binary64 binary128)
 
     - long-term: add in _32bit and _128bit versions
       - what's official name of 128bit long-double?  quad?  something else?  check IEEE754