From f8765525efabb5fdcf82f9ee1c37d014e0c64e14 Mon Sep 17 00:00:00 2001 From: Elizabeth Mattijsen Date: Mon, 5 Aug 2024 14:34:38 +0200 Subject: [PATCH] Separate documentation into a separate file And update test runner --- Changes | 1 + dist.ini | 2 +- doc/String-Utils.rakudoc | 421 +++++++++++++++++++++++++++++++++++++++ lib/String/Utils.rakumod | 420 -------------------------------------- run-tests | 10 +- 5 files changed, 428 insertions(+), 426 deletions(-) create mode 100644 doc/String-Utils.rakudoc diff --git a/Changes b/Changes index e02d100..805b5ac 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,7 @@ Revision history for String-Utils {{$NEXT}} + - Separate documentation into a separate file 0.0.24 2024-07-29T15:44:22+02:00 - Add separate CI badges for each OS diff --git a/dist.ini b/dist.ini index a58275d..281edb5 100644 --- a/dist.ini +++ b/dist.ini @@ -2,7 +2,7 @@ name = String-Utils [ReadmeFromPod] ; enable = false -filename = lib/String/Utils.rakumod +filename = doc/String-Utils.rakudoc [UploadToZef] diff --git a/doc/String-Utils.rakudoc b/doc/String-Utils.rakudoc new file mode 100644 index 0000000..e43cf1d --- /dev/null +++ b/doc/String-Utils.rakudoc @@ -0,0 +1,421 @@ +=begin pod + +=head1 NAME + +String::Utils - Provide some optimized string functions + +=head1 SYNOPSIS + +=begin code :lang + +use String::Utils; + +say before("foobar","bar"); # foo + +say between("foobarbaz","foo","baz"); # bar + +say between-included("foobarbaz","oo","baz"); # oobarbaz + +say around("foobarbaz", "ob", "rb"); # foaz + +say after("foobar","foo"); # bar + +say chomp-needle("foobarbaz", "baz"); # foobar + +say root ; # ab + +say leaf ; # .txt + +say is-sha1 "foo bar baz"; # False + +say stem "foo.tar.gz"; # foo +say stem "foo.tar.gz", 1; # foo.tar + +say ngram "foobar", 3; # foo oob oba bar + +say non-word "foobar"; # False +say non-word "foo/bar"; # True + +say letters("//foo:bar"); # foobar + +say nomark("élève"); # eleve + +say has-marks("foo👩🏽‍💻bar"); # False +say has-marks("fóöbar"); # True + +dd leading-whitespace(" \t foo"); # " \t " +dd trailing-whitespace("bar \t "); # " \t " +say is-whitespace("\t \n"); # True +say is-whitespace("\ta\n"); # False +say is-whitespace(""); # True + +say is-uppercase("FOOBAR"); # True +say is-uppercase("FooBar"); # False +say is-uppercase(""); # True + +say is-lowercase("foobar"); # True +say is-lowercase("FooBar"); # False +say is-lowercase(""); # True + +say consists-of("aaabbcc", "abc"); # True +say consists-of("aaadbcc", "abc"); # False +say consists-of("", "abc"); # True + +say all-same("aaaaaa"); # "a" +say all-same("aaaaba"); # Nil +say all-same(""); # Nil + +use String::Utils ; # only import "before" and "after" + +=end code + +=head1 DESCRIPTION + +String::Utils provides some simple string functions that are not (yet) +provided by the core Raku Programming Language. + +These functions are implemented B using regexes for speed. + +=head1 SELECTIVE IMPORTING + +=begin code :lang + +use String::Utils ; # only import "before" and "after" + +=end code + +By default all utility functions are exported. But you can limit this to +the functions you actually need by specifying the names in the C +statement. + +To prevent name collisions and/or import any subroutine with a more +memorable name, one can use the "original-name:known-as" syntax. A +semi-colon in a specified string indicates the name by which the subroutine +is known in this distribution, followed by the name with which it will be +known in the lexical context in which the C command is executed. + +=begin code :lang + +use String::Utils ; # import "root" as "common-start" + +say common-start ; # ab + +=end code + +=head1 SUBROUTINES + +=head2 after + +=begin code :lang + +say after("foobar","foo"); # bar + +say "foobar".&after("foo"); # bar + +say after("foobar","goo"); # Nil + +=end code + +Return the string B a given string, or C if the given string could +not be found. The equivalent of the stringification of C .* />. + +=head2 around + +=begin code :lang + +say around("foobarbaz","ob","rb"); # foaz + +say "foobarbaz".&around("ob","rb"); # foaz + +say around("foobarbaz","goo","baz"); # foobarbaz + +=end code + +Return the string B two given strings, or the string itself if either +of the bounding strings could not be found. The equivalent of +C<.subst: / .*? />. + +=head2 before + +=begin code :lang + +say before("foobar","bar"); # foo + +say "foobar".&before("bar"); # foo + +say before("foobar","baz"); # Nil + +=end code + +Return the string B a given string, or C if the given string could +not be found. The equivalent of the stringification of +C />. + +=head2 between + +=begin code :lang + +say between("foobarbaz","foo","baz"); # bar + +say "foobarbaz".&between("foo","baz"); # bar + +say between("foobarbaz","goo","baz"); # Nil + +=end code + +Return the string B two given strings, or C if either of the +bounding strings could not be found. The equivalent of the stringification of +C .*? />. + +=head2 between-included + +=begin code :lang + +say between-included("foobarbaz","oo","baz"); # oobarbaz + +say "foobarbaz".&between-included("oo","baz"); # oobarbaz + +say between-included("foobarbaz","goo","baz"); # Nil + +=end code + +Return the string B two given strings B the given strings, +or C if either of the bounding strings could not be found. The equivalent +of the stringification of C. + +=head2 chomp-needle + +=begin code :lang + +say chomp-needle("foobarbaz","baz"); # foobar + +say "foobarbaz".&chomp-needle("baz"); # foobar + +say chomp-needle("foobarbaz","bar"); # foobarbaz + +=end code + +Return the string without the given target string at the end, or the string +itself if the target string is not at the end. The equivalent of +C<.subst(/ baz $/)>. + +=head2 root + +=begin code :lang + +say root ; # ab + +=end code + +Return the common B of the given strings, or the empty string if +no common string could be found. See also C. + +=head2 leaf + +=begin code :lang + +say leaf ; # .txt + +=end code + +Return the common B of the given strings, or the empty string if no +common string could be found. See also C. + +=head2 is-sha1 + +=begin code :lang + +say is-sha1 "abcd abce abde"; # False +say is-sha1 "356A192B7913B04C54574D18C28D46E6395428AB"; # True + +=end code + +Return a C indicating whether the given string is a SHA1 string +(40 chars and only containing 0123456789ABCDEF). + +=head2 stem + +=begin code :lang + +say stem "foo.tar.gz"; # foo +say stem "foo.tar.gz", 1; # foo.tar +say stem "foo.tar.gz", *; # foo + +=end code + +Return the stem of a string with all of its extensions removed. +Optionally accepts a second argument indicating the number of extensions +to be removed. This may be C<*> (aka C) to indicate to +remove all extensions. + +=head2 ngram + +=begin code :lang + +say ngram "foobar", 3; # foo oob oba bar + +say ngram "foobar", 4, :partial; # foob ooba obar bar ar r + +=end code + +Return a sequence of substrings of the given size, while only moving up +one position at a time in the original string. Optionally takes a +C<:partial> flag to also produce incomplete substrings at the end of +the sequence. + +=head2 non-word + +=begin code :lang + +say non-word "foobar"; # False + +say non-word "foo/bar"; # True + +=end code + +Returns a C indicating whether the string contained B +non-word characters. + +=head2 letters + +=begin code :lang + +say letters("//foo:bar"); # foobar + +=end code + +Returns all of the alphanumeric characters in the given string as a +string. + +=head2 nomark + +=begin code :lang + +say nomark("élève"); # eleve + +=end code + +Returns the given string with any diacritcs removed. + +=head2 has-marks + +=begin code :lang + +say has-marks("foo👩🏽‍💻bar"); # False +say has-marks("fóöbar"); # True + +=end code + +Returns a C indicating whether the given string contains any +alphanumeric characters with marks (accents). + +=head2 leading-whitespace + +=begin code :lang + +dd leading-whitespace("foo"); # "" +dd leading-whitespace(" \t foo"); # " \t " +dd leading-whitespace(" \t "); # " \t " + +=end code + +Returns a C containing any leading whitespace of the given string. + +=head2 trailing-whitespace + +=begin code :lang + +dd trailing-whitespace("bar"); # "" +dd trailing-whitespace("bar \t "); # " \t " +dd trailing-whitespace(" \t "); # " \t " + +=end code + +Returns a C containing any trailing whitespace of the given string. + +=head2 is-whitespace + +=begin code :lang + +say is-whitespace("\t \n"); # True +say is-whitespace("\ta\n"); # False +say is-whitespace(""); # True + +=end code + +Returns a C indicating whether the string consists of just +whitespace characters, or is empty. + +=head2 is-uppercase + +=begin code :lang + +say is-uppercase("FOOBAR"); # True +say is-uppercase("FooBar"); # False +say is-uppercase(""); # True + +=end code + +Returns a C indicating whether the string consists of just +uppercase characters, or is empty. + +=head2 is-lowercase + +=begin code :lang + +say is-lowercase("foobar"); # True +say is-lowercase("FooBar"); # False +say is-lowercase(""); # True + +=end code + +Returns a C indicating whether the string consists of just +lowercase characters, or is empty. + +=head2 consists-of + +=begin code :lang + +say consists-of("aaabbcc", "abc"); # True +say consists-of("aaadbcc", "abc"); # False +say consists-of("", "abc"); # True + +=end code + +Returns a C indicating whether the string given as the first +positional argument only consists of characters given as the second +positional argument, or is empty. + +=head2 all-same + +=begin code :lang + +say all-same("aaaaaa"); # "a" +say all-same("aaaaba"); # Nil +say all-same(""); # Nil + +=end code + +If the given string consists of a single character, returns that +character. Else returns C. + +=head1 AUTHOR + +Elizabeth Mattijsen + +Source can be located at: https://github.com/lizmat/String-Utils . Comments and +Pull Requests are welcome. + +If you like this module, or what I’m doing more generally, committing to a +L would mean a great +deal to me! + +=head1 COPYRIGHT AND LICENSE + +Copyright 2022, 2023, 2024 Elizabeth Mattijsen + +This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0. + +=end pod + +# vim: expandtab shiftwidth=4 diff --git a/lib/String/Utils.rakumod b/lib/String/Utils.rakumod index 9dac874..a4a9ea9 100644 --- a/lib/String/Utils.rakumod +++ b/lib/String/Utils.rakumod @@ -413,424 +413,4 @@ my sub EXPORT(*@names) { } } -=begin pod - -=head1 NAME - -String::Utils - Provide some optimized string functions - -=head1 SYNOPSIS - -=begin code :lang - -use String::Utils; - -say before("foobar","bar"); # foo - -say between("foobarbaz","foo","baz"); # bar - -say between-included("foobarbaz","oo","baz"); # oobarbaz - -say around("foobarbaz", "ob", "rb"); # foaz - -say after("foobar","foo"); # bar - -say chomp-needle("foobarbaz", "baz"); # foobar - -say root ; # ab - -say leaf ; # .txt - -say is-sha1 "foo bar baz"; # False - -say stem "foo.tar.gz"; # foo -say stem "foo.tar.gz", 1; # foo.tar - -say ngram "foobar", 3; # foo oob oba bar - -say non-word "foobar"; # False -say non-word "foo/bar"; # True - -say letters("//foo:bar"); # foobar - -say nomark("élève"); # eleve - -say has-marks("foo👩🏽‍💻bar"); # False -say has-marks("fóöbar"); # True - -dd leading-whitespace(" \t foo"); # " \t " -dd trailing-whitespace("bar \t "); # " \t " -say is-whitespace("\t \n"); # True -say is-whitespace("\ta\n"); # False -say is-whitespace(""); # True - -say is-uppercase("FOOBAR"); # True -say is-uppercase("FooBar"); # False -say is-uppercase(""); # True - -say is-lowercase("foobar"); # True -say is-lowercase("FooBar"); # False -say is-lowercase(""); # True - -say consists-of("aaabbcc", "abc"); # True -say consists-of("aaadbcc", "abc"); # False -say consists-of("", "abc"); # True - -say all-same("aaaaaa"); # "a" -say all-same("aaaaba"); # Nil -say all-same(""); # Nil - -use String::Utils ; # only import "before" and "after" - -=end code - -=head1 DESCRIPTION - -String::Utils provides some simple string functions that are not (yet) -provided by the core Raku Programming Language. - -These functions are implemented B using regexes for speed. - -=head1 SELECTIVE IMPORTING - -=begin code :lang - -use String::Utils ; # only import "before" and "after" - -=end code - -By default all utility functions are exported. But you can limit this to -the functions you actually need by specifying the names in the C -statement. - -To prevent name collisions and/or import any subroutine with a more -memorable name, one can use the "original-name:known-as" syntax. A -semi-colon in a specified string indicates the name by which the subroutine -is known in this distribution, followed by the name with which it will be -known in the lexical context in which the C command is executed. - -=begin code :lang - -use String::Utils ; # import "root" as "common-start" - -say common-start ; # ab - -=end code - -=head1 SUBROUTINES - -=head2 after - -=begin code :lang - -say after("foobar","foo"); # bar - -say "foobar".&after("foo"); # bar - -say after("foobar","goo"); # Nil - -=end code - -Return the string B a given string, or C if the given string could -not be found. The equivalent of the stringification of C .* />. - -=head2 around - -=begin code :lang - -say around("foobarbaz","ob","rb"); # foaz - -say "foobarbaz".&around("ob","rb"); # foaz - -say around("foobarbaz","goo","baz"); # foobarbaz - -=end code - -Return the string B two given strings, or the string itself if either -of the bounding strings could not be found. The equivalent of -C<.subst: / .*? />. - -=head2 before - -=begin code :lang - -say before("foobar","bar"); # foo - -say "foobar".&before("bar"); # foo - -say before("foobar","baz"); # Nil - -=end code - -Return the string B a given string, or C if the given string could -not be found. The equivalent of the stringification of -C />. - -=head2 between - -=begin code :lang - -say between("foobarbaz","foo","baz"); # bar - -say "foobarbaz".&between("foo","baz"); # bar - -say between("foobarbaz","goo","baz"); # Nil - -=end code - -Return the string B two given strings, or C if either of the -bounding strings could not be found. The equivalent of the stringification of -C .*? />. - -=head2 between-included - -=begin code :lang - -say between-included("foobarbaz","oo","baz"); # oobarbaz - -say "foobarbaz".&between-included("oo","baz"); # oobarbaz - -say between-included("foobarbaz","goo","baz"); # Nil - -=end code - -Return the string B two given strings B the given strings, -or C if either of the bounding strings could not be found. The equivalent -of the stringification of C. - -=head2 chomp-needle - -=begin code :lang - -say chomp-needle("foobarbaz","baz"); # foobar - -say "foobarbaz".&chomp-needle("baz"); # foobar - -say chomp-needle("foobarbaz","bar"); # foobarbaz - -=end code - -Return the string without the given target string at the end, or the string -itself if the target string is not at the end. The equivalent of -C<.subst(/ baz $/)>. - -=head2 root - -=begin code :lang - -say root ; # ab - -=end code - -Return the common B of the given strings, or the empty string if -no common string could be found. See also C. - -=head2 leaf - -=begin code :lang - -say leaf ; # .txt - -=end code - -Return the common B of the given strings, or the empty string if no -common string could be found. See also C. - -=head2 is-sha1 - -=begin code :lang - -say is-sha1 "abcd abce abde"; # False -say is-sha1 "356A192B7913B04C54574D18C28D46E6395428AB"; # True - -=end code - -Return a C indicating whether the given string is a SHA1 string -(40 chars and only containing 0123456789ABCDEF). - -=head2 stem - -=begin code :lang - -say stem "foo.tar.gz"; # foo -say stem "foo.tar.gz", 1; # foo.tar -say stem "foo.tar.gz", *; # foo - -=end code - -Return the stem of a string with all of its extensions removed. -Optionally accepts a second argument indicating the number of extensions -to be removed. This may be C<*> (aka C) to indicate to -remove all extensions. - -=head2 ngram - -=begin code :lang - -say ngram "foobar", 3; # foo oob oba bar - -say ngram "foobar", 4, :partial; # foob ooba obar bar ar r - -=end code - -Return a sequence of substrings of the given size, while only moving up -one position at a time in the original string. Optionally takes a -C<:partial> flag to also produce incomplete substrings at the end of -the sequence. - -=head2 non-word - -=begin code :lang - -say non-word "foobar"; # False - -say non-word "foo/bar"; # True - -=end code - -Returns a C indicating whether the string contained B -non-word characters. - -=head2 letters - -=begin code :lang - -say letters("//foo:bar"); # foobar - -=end code - -Returns all of the alphanumeric characters in the given string as a -string. - -=head2 nomark - -=begin code :lang - -say nomark("élève"); # eleve - -=end code - -Returns the given string with any diacritcs removed. - -=head2 has-marks - -=begin code :lang - -say has-marks("foo👩🏽‍💻bar"); # False -say has-marks("fóöbar"); # True - -=end code - -Returns a C indicating whether the given string contains any -alphanumeric characters with marks (accents). - -=head2 leading-whitespace - -=begin code :lang - -dd leading-whitespace("foo"); # "" -dd leading-whitespace(" \t foo"); # " \t " -dd leading-whitespace(" \t "); # " \t " - -=end code - -Returns a C containing any leading whitespace of the given string. - -=head2 trailing-whitespace - -=begin code :lang - -dd trailing-whitespace("bar"); # "" -dd trailing-whitespace("bar \t "); # " \t " -dd trailing-whitespace(" \t "); # " \t " - -=end code - -Returns a C containing any trailing whitespace of the given string. - -=head2 is-whitespace - -=begin code :lang - -say is-whitespace("\t \n"); # True -say is-whitespace("\ta\n"); # False -say is-whitespace(""); # True - -=end code - -Returns a C indicating whether the string consists of just -whitespace characters, or is empty. - -=head2 is-uppercase - -=begin code :lang - -say is-uppercase("FOOBAR"); # True -say is-uppercase("FooBar"); # False -say is-uppercase(""); # True - -=end code - -Returns a C indicating whether the string consists of just -uppercase characters, or is empty. - -=head2 is-lowercase - -=begin code :lang - -say is-lowercase("foobar"); # True -say is-lowercase("FooBar"); # False -say is-lowercase(""); # True - -=end code - -Returns a C indicating whether the string consists of just -lowercase characters, or is empty. - -=head2 consists-of - -=begin code :lang - -say consists-of("aaabbcc", "abc"); # True -say consists-of("aaadbcc", "abc"); # False -say consists-of("", "abc"); # True - -=end code - -Returns a C indicating whether the string given as the first -positional argument only consists of characters given as the second -positional argument, or is empty. - -=head2 all-same - -=begin code :lang - -say all-same("aaaaaa"); # "a" -say all-same("aaaaba"); # Nil -say all-same(""); # Nil - -=end code - -If the given string consists of a single character, returns that -character. Else returns C. - -=head1 AUTHOR - -Elizabeth Mattijsen - -Source can be located at: https://github.com/lizmat/String-Utils . Comments and -Pull Requests are welcome. - -If you like this module, or what I’m doing more generally, committing to a -L would mean a great -deal to me! - -=head1 COPYRIGHT AND LICENSE - -Copyright 2022, 2023, 2024 Elizabeth Mattijsen - -This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0. - -=end pod - # vim: expandtab shiftwidth=4 diff --git a/run-tests b/run-tests index 7ac0c9c..a833103 100644 --- a/run-tests +++ b/run-tests @@ -12,12 +12,12 @@ say "Testing { my @failed; my $done = 0; -sub process($proc) { +sub process($proc, $filename) { if $proc { $proc.out.slurp; } else { - @failed.push($_); + @failed.push($filename); if $proc.out.slurp -> $stdout { my @lines = $stdout.lines; with @lines.first( @@ -38,14 +38,14 @@ sub process($proc) { sub install() { my $zef := $*DISTRO.is-win ?? 'zef.bat' !! 'zef'; my $proc := run $zef, "install", ".", "--verbose", "--/test", :out,:err,:merge; - process($proc); + process($proc, "*installation*"); } sub test-dir($dir) { for $dir.IO.dir(:test(*.ends-with: '.t' | '.rakutest')).map(*.Str).sort { say "=== $_"; my $proc := run "raku", "--ll-exception", "-I.", $_, :out,:err,:merge; - process($proc); + process($proc, $_); $done++; } } @@ -55,7 +55,7 @@ test-dir("xt") if $author && "xt".IO.e; install if $install; if @failed { - say "FAILED: {+@failed} of $done:"; + say "\nFAILED: {+@failed} of $done:"; say " $_" for @failed; exit +@failed; }