changes for new release and API

Author: tbrowder

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [v2.0.0] - 2019-12-18
+- add multi version of strip-comment routine
+- update API to 2
+- deprecate the original signature;
+  it will be removed in version 3.0.0.
+- improve robustness of strip-comment to multi-char comment marks
+- add tests for it 
+
 ## [v1.0.0] - 2019-12-17
 - started a renamed version of module Text::More (which is now deprecated)
 - improved routine 'strip-comment' to allow returning the comment as well

META6.json

@@ -1,8 +1,8 @@
 {
     "perl"        : "6.*",
     "name"        : "Text::Utils",
-    "version"     : "1.0.0",
-    "api"         : "1",
+    "version"     : "2.0.0",
+    "api"         : "2",
     "description" : "Provides some additional text functions (replaces module Text::More)",
     "auth"        : "github:tbrowder",
     "author"      : "github:tbrowder",

README.md

@@ -5,18 +5,62 @@
 This model provides some miscellaneous text processing routines not
 provided by core Raku. (Note it replaces the now-deprecated `Text::More` module.)
 
+Note this is version 2.0.0 which introduces a new API 2 for
+the 'strip-comment' routine. See the examples below for its use.
+The old signature is still usable, but it is deprecated
+and will be removed in version 3.0.0.
+
 ## Synopsis
 
-```Raku
+```raku
 use Text::More :ALL;
 ```
 Note that individual subroutines
 may also be exported:
 
-```Raku
+```raku
 use Text::More :strip-comment;
+# the '#' is the default comment character 
+my $line = " some  text # a comment"; 
+$line = strip-comment $line;
+say $line # output: << some  text >>
+```
+If you want to be fancier:
+
+```raku
+# define your own comment character(s)
+# save the comment and normalize the returned strings
+my ($line, $comm) = strip-comment $line, :mark<%%>, :save-comment, :normalize;
+say $line # output: <<some text>>
+say $comm # output: <<a comment>>
+```
+
+The default behavior is to find the first comment character in the input
+string, but you may choose to start the search from the end of the
+input string:
+
+```raku
+my $line = "text 1 # text 2 # comment";
+$line = strip-comment $line, :reverse;
+say $line # output: <<text 1 # text 2 >>
+```
+
+Note that the routine is line oriented, so embedded newlines
+may give unexpected results:
+
+```raku
+my $line = q:to/HERE/;
+text 1 # comment 1
+text 2 # comment 2
+HERE
+$line = strip-comment $line
+say $line # output: <<text 1 >>
 ```
 
+
+
+
+
 ## Installation
 
 ``` Raku
@@ -38,7 +82,7 @@ p6doc Text::Utils
 - `Text::Emotion`
 - `Text::Levenshtein::Damerau`
 - `Text::MiscUtils`
-- `Text::More (deprecated)`
+- `Text::More` (deprecated)
 - `Text::Table::List`
 - `Text::Table::Simple`
 - `Text::Tabs`

lib/Text/Utils.pm6

@@ -31,20 +31,62 @@ sub count-substrs(Str:D $ip, Str:D $substr --> UInt) is export(:count-substrs) {
 #| Purpose : Strip comments from an input text line, save comment if
 #|             requested, normalize returned text if requested
 #| Params  : String of text, comment char ('#' is default),
+#|             option to return the comment, option to normalize
+#|             the returned strings, option to use the last comment char
+#|             instead of the first
 #| Returns : String of text with any comment stripped off. Note that the
 #|             designated char will trigger the strip even though it is
 #|             escaped or included in quotes.
 #|             Also returns the comment if requested.
 #|             All returned text is normalized if requested.
-sub strip-comment($line is copy,       #= string of text with possible comment
-                  $comment-char = '#', #= desired comment char indicator
-                  :$save-comment,      #= if true, return the comment
-                  :$normalize,         #= if true, normalize returned strings
-                 ) is export(:strip-comment) {
+multi strip-comment($line is copy,       #= string of text with possible comment
+                    :$mark = '#',        #= desired comment char indicator
+                    :$save-comment,      #= if true, return the comment
+                    :$normalize,         #= if true, normalize returned strings
+                    :$last,              #= if true, use the last instead of first comment char
+                   ) is export(:strip-comment) {
+    # failure condition:
+    if $line eq $mark {
+        die "FATAL: The input line is the same as the comment char: '$line'";
+    }
+    my $comment = '';
+    my $clen    = $mark.chars;
+    my $idx     = $last ?? rindex $line, $mark
+                        !! index  $line, $mark;
+    if $idx.defined {
+        $comment = substr $line, $idx+$clen; #= don't want the comment char
+	$line = substr $line, 0, $idx;
+    }
+    if $normalize {
+        $line    = normalize-string $line;
+        $comment = normalize-string $comment;
+    }
+    if $save-comment {
+        return $line, $comment;
+    }
+    $line;
+}
+
+#| NOTE THE FOLLOWING SIGNATURE IS DEPRECATED
+multi strip-comment($line is copy,       #= string of text with possible comment
+                    $comment-char = '#', #= desired comment char indicator
+                    :$save-comment,      #= if true, return the comment
+                    :$normalize,         #= if true, normalize returned strings
+                    :$last,              #= if true, use the last instead of first comment char
+                   ) is export(:strip-comment) {
+    # failure condition:
+    if $line eq $comment-char {
+        note "FATAL: The input line is the same as the comment char: '$line'";
+        note "       This signature is deprecated.";
+        note "       Use the ':mark<$line>' named param for the comment char.";
+        die  "DEPRECATED SIGNATURE--USE THE MARK NOTATION IN THE FUTURE";
+    }
     my $comment = '';
-    my $idx = index $line, $comment-char;
+    my $clen    = $comment-char.chars;
+    my $idx     = $last ?? rindex $line, $comment-char
+                        !! index  $line, $comment-char;
     if $idx.defined {
-        $comment = substr $line, $idx+1; #= don't want the comment char
+        $comment = substr $line, $idx+$clen; #= don't want the comment char
 	$line = substr $line, 0, $idx;
     }
     if $normalize {

t/020-strip-comment.t

@@ -3,7 +3,7 @@ use Test;
 
 use Text::Utils :ALL;
 
-plan 12;
+plan 30;
 
 my (@s, @stripped);
 # comment char is default '#'
@@ -21,7 +21,6 @@ my (@s, @stripped);
 'more text'
 );
 
-
 # return the stripped strings
 for 0..^+@s -> $i {
     my $line = strip-comment(@s[$i]);
@@ -62,4 +61,59 @@ is $comm, ' some  comment';
 is $text, 'some text';
 is $comm, 'some comment';
 
+# test empty comment
+$tstr = ' some  text ';
+($text, $comm) = strip-comment $tstr, :save-comment;
+is $text, ' some  text ';
+is $comm, '';
+
+($text, $comm) = strip-comment $tstr, :save-comment, :normalize;
+is $text, 'some text';
+is $comm, '';
+
+# default is to take the first comment char found
+# note multi-char comment char is allowed
+$tstr = ' some  text %%  text %% some  comment ';
+($text, $comm) = strip-comment $tstr, '%%', :save-comment;
+is $text, ' some  text ';
+is $comm, '  text %% some  comment ';
+
+#===== ORIGINAL SIGNATURE IS DEPRECATED =====
+# testing the original signature which is now deprecated
+# and will be removed in version 3.0.0
+($text, $comm) = strip-comment $tstr, '%%', :save-comment, :normalize;
+is $text, 'some text';
+is $comm, 'text %% some comment';
+
+$text = strip-comment $tstr, '%%', :last;
+is $text, ' some  text %%  text ';
+
+($text, $comm) = strip-comment $tstr, '%%', :last, :save-comment;
+is $text, ' some  text %%  text ';
+is $comm, ' some  comment ';
+
+($text, $comm) = strip-comment $tstr, '%%', :last, :save-comment, :normalize;
+is $text, 'some text %% text';
+is $comm, 'some comment';
+
+# bad input by user
+dies-ok { $text = strip-comment '#'; }, 'dies when line is same as comment char';
+
+#===== END OF ORIGINAL SIGNATURE IS DEPRECATED =====
+
+# test the new signature
+
+# bad input by user
+dies-ok { $text = strip-comment '%', :mark<%>; }, 'dies when line is same as comment (:mark) char';
+
+($text, $comm) = strip-comment $tstr, :mark<%%>, :last, :save-comment, :normalize;
+is $text, 'some text %% text';
+is $comm, 'some comment';
 
+# watch out for embedded newlines
+my $s = q:to/HERE/;
+text 1 # comment 1
+text 2 # comment 2
+HERE
+$s = strip-comment $s;
+is $s, 'text 1 ';