Merge pull request #10 from tbrowder/next-ver

Next version

.github/workflows/linux.yml

@@ -0,0 +1,30 @@
+name: Linux
+
+on:
+  push:
+    branches:
+      - '*'
+    tags-ignore:
+      - '*'
+  pull_request:
+
+jobs:
+  raku:
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+        raku-version:
+          - 'latest'
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: Raku/setup-raku@v1
+        with:
+          raku-version: ${{ matrix.raku-version }}
+      - name: Install Dependencies
+        run: |
+          zef install --/test --deps-only .
+          zef install --/test App::Prove6
+      - name: Run Tests
+        run: prove6 -l t

.github/workflows/macos.yml

@@ -0,0 +1,30 @@
+name: MacOS
+
+on:
+  push:
+    branches:
+      - '*'
+    tags-ignore:
+      - '*'
+  pull_request:
+
+jobs:
+  raku:
+    strategy:
+      matrix:
+        os:
+          - macos-latest
+        raku-version:
+          - 'latest'
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: Raku/setup-raku@v1
+        with:
+          raku-version: ${{ matrix.raku-version }}
+      - name: Install Dependencies
+        run: |
+          zef install --/test --deps-only .
+          zef install --/test App::Prove6
+      - name: Run Tests
+        run: prove6 -l t

.github/workflows/windows.yml

@@ -0,0 +1,28 @@
+name: Win64
+
+on:
+  push:
+    branches:
+      - '*'
+    tags-ignore:
+      - '*'
+  pull_request:
+
+jobs:
+  raku:
+    strategy:
+      matrix:
+        os:
+          - windows-latest
+        raku-version:
+          - 'latest'
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: Raku/setup-raku@v1
+        with:
+          raku-version: ${{ matrix.raku-version }}
+      - name: Install Dependencies
+        run: zef install --/test --test-depends --deps-only .
+      - name: Run Tests
+        run: zef --debug --/prove --/tap-harness test .

Changes

@@ -1,4 +1,31 @@
 {{$NEXT}}
+    - Make the default output for a single word be a 
+      suitable word for an arg regex selection, e.g.,
+        abbrev "Args" => "A|Ar|Arg|Args"
+        + Add info in the README
+    - Separate tests into one for each arg
+    - Add t/Utils/Subs.rakumod with a 'test-junction' routine
+
+2.1.0  2023-06-14T16:05:14-05:00
+    - Removed the unneeded 'is export' trait from sub 'abbreviations'.
+    - Improved sorting routines for consistency and expected results
+      by using an updated 'sort-list' function to clarify the
+      type and order of the various sorting types
+      defined.
+      + Added an enum Sort-type to define the sort types
+      + Made the default sort type LS (length first,
+        then by string order).
+      + Added an option to reverse the output
+      + Added tests
+    - Updated the README for improved grammar and better
+      coverage of details.
+    - Added a :$min-length parameter for abbreviations.
+    - Created a new output format: HA (Hash Abbrev)
+      consisting of the word as key and its shortest
+      abbreviation as its value.
+      + added tests for it
+    - Made the default output the HA type.
+    - Use the three-OS test workflow.
 
 2.0.0  2022-07-23T17:49:28-05:00
     - Remove the auto-abbreviate sub and rewrite the get-abbrevs sub

META6.json

@@ -25,5 +25,5 @@
   ],
   "test-depends": [
   ],
-  "version": "2.0.0"
+  "version": "2.1.0"
 }

README.md

@@ -1,26 +1,73 @@
+[![Actions Status](https://github.com/tbrowder/Abbreviations/actions/workflows/linux.yml/badge.svg)](https://github.com/tbrowder/Abbreviations/actions) [![Actions Status](https://github.com/tbrowder/Abbreviations/actions/workflows/macos.yml/badge.svg)](https://github.com/tbrowder/Abbreviations/actions) [![Actions Status](https://github.com/tbrowder/Abbreviations/actions/workflows/windows.yml/badge.svg)](https://github.com/tbrowder/Abbreviations/actions)
+
 NAME
 ====
 
-**Abbreviations** - Provides abbreviations for an input set of one or more words
+Abbreviations - Provides abbreviations for an input set of one or more words
 
 SYNOPSIS
 ========
 
 ```raku
 use Abbreviations;
 my $words = 'A ab Abcde';
-# The exported routine:
+# The main exported routine:
 my %abbrevs = abbreviations $words;
+say %abbrevs.gist;
+# OUTPUT: «{A => A, Abcde => Ab, ab => a}␤»
 ```
 
-There are two shorter routine name abbreviations one can use that are always exported:
+DESCRIPTION
+===========
+
+**Abbreviations** is a module with one automatically exported subroutine, `abbreviations`, which takes as input a set of words and returns the original set with added unique abbreviations for the set. (Note the input words are also abbreviations in the context of this module.)
+
+Its signature:
+
+    sub abbreviations($word-set,      #= Str, List, or Hash (Set)
+                     :$out-type = HA, #= the default, HashAbbrev
+                     :$lower-case,    #= convert the word st to lowercase
+                     :$min-length,    #= minimum abbreviation length
+                     ) is export {...}
+
+A *word* satisfies the Raku regex `$word ~~ /\S+/` which is quite loose. Using programs can of course further restrict that if need be. For example, for use with module **Opt::Handler** words must satisfy this regex: `$word ~~ /<ident>/`.
+
+A natural consequence of generating all the abbreviations for a set of one word is this: the output provides a regex alternation which matches any partial length of the target word. For example, given a target word 'Args':
+
+    use Abbreviations;
+    use Test;
+    my $target = "Args";
+    my $regex = abbrev $target; # OUTPUT: «"A|Ar|Arg|Args"␤»;
+    my $res = False;
+    my @w = $regex.split('|');
+    for @w {
+        when /<$regex>/ {
+            $res = True
+        }
+        default {
+            $res = False
+        }
+    }
+    is $res, True; # OUTPUT: «ok 1␤»
+
+As shown in the example above, limiting the input set to one word results in the output of a regex alternation string. The rest of this description applies to sets of two or more words. The input word set can be in one of three forms: (1) a list (recommended), (2) a string containing the words separated by spaces, or (3) as a hash (or set) with the words being keys of the hash (set members). Duplicate words will be automatically and quietly eliminated.
+
+Note the input word set will not be modified unless the `:lower-case` option is used. In that case, all characters will be transformed to lower-case and any new duplicate words deleted.
+
+If the user wishes, he or she can restrict the minimum length of the generated abbreviations by using the `:$min-length` parameter.
+
+One will normally get the result as a hash with the input words as keys with their shortest abbreviation as values (return type HA), but the return type can be specified via `enum Out-type` if desired by selecting one of the `:$output-type` options. For example:
+
+    my %abbrevs = abbrevs @words, :output-type(AH);
+
+There are two shorter alias names for `sub abbreviations` one can use that are always exported:
 
 ```raku
  abbrevs
  abbrev
 ```
 
-In the sprit of the module, one can `use Abbreviations :ALL;` and have these additional short forms available:
+In the sprit of the module, one can `use Abbreviations :ALL;` and have these additional shorter alias names available:
 
 ```raku
  abbre
@@ -30,33 +77,26 @@ In the sprit of the module, one can `use Abbreviations :ALL;` and have these add
  a
 ```
 
-Each of those is individually available by adding its name as an adverb, e.g.:
+Each of those is individually available by adding its name as an adverb, for example:
 
 ```raku
 use Abbreviations :abb;
 my %abb = abb $words;
 ```
 
-DESCRIPTION
-===========
-
-**Abbreviations** is a module with one automatically exported subroutine, `abbreviations`, which takes as input a set of words and returns the original set with added unique abbreviations for the set. (Note the input words are also abbreviations in the context of this module.)
-
-A *word* satisfies the Raku regex `$word ~~ /\S+/` which is quite loose. Using programs can of course further restrict that if need be. For example, for use with module **Opt::Handler** words must satisfy this regex: `$word ~~ /<ident>/`. (**CAUTION**: Words containing other than letters have not been tested and results are unknown. The author is willing to investigate those words if any user is so interested and files an issue indicating such.)
-
-The input word set can be in one of two forms: a list or a string containing the words separated by spaces. Duplicate words will be automatically and quietly eliminated. An empty word set will cause an exception.
+### `enum Out-type`
 
-Note the input word set will not be modified unless the `:lower-case` option is used. In that case, all characters will be transformed to lower-case.
+    enum Out-type is export <HA H AH AL L S >;
 
-One will normally get the result as a hash, but the return type can be specified via an `enum` if desired by selecting one of the `:out-type` options: `AH` (AbbrevHash), `AL` (AbbrevList), `H` (Hash), `L` (List), or `S` (String). For example,
+The *enum* `Out-type` is exported automatically as it is required for using `sub abbreviations`. It has the following types:
 
-    my %abbrevs = abbrevs @words, :out-type(AH);
+  * `HA` (HashAbbrev)
 
-### Output types by `enum Out-type`
+The default *HashAbbrev* (`HA`) returned will have input words as keys whose value will be the shortest valid abbreviation.
 
   * `H` (Hash)
 
-The default *Hash* (`H`) returned will have input words as keys whose value will be a sorted list of one or more valid abbreviations (sorted by length, shortest first).
+A variant of `HA`, the *Hash* (`H`) returned will have input words as keys whose value will be a sorted list of its valid abbreviations (sorted by length, shortest first, then by `Str` order).
 
   * `AH` (AbbrevHash)
 
@@ -67,20 +107,25 @@ An *AbbrevHash* (`AH`) is keyed by all of the valid abbreviations for the input
 An *AbbrevList* (`AL`) is special in that the returned list is the one, shortest abbreviation for each of the input words in input order. For example,
 
     my @w = <Monday Tuesday Wednesday Thursday Friday Saturday Sunday>;
-    my @abb = abbrevs @w, :lower-case, :out-type(AL);
-    say @abb; # OUTPUT: «[m tu w th f sa su]␤»
+    my @abb = abbrevs @w, :output-type(AL);
+    say @abb; # OUTPUT: «M Tu W Th F Sa Su␤»
+
+Note that a hash (or set) input type will not reliably provide this output as expected since the keys are not stored in order. Instead, the ouput will be based on a list of the hash's keys. In effect, entering `%out = abbreviations %in` is the same as:
+
+    my @inputlist = %in.keys.sort({.chars, .Str}';
+    my %out = abbreviations @inputlist;
 
   * `L` (List)
 
-A *List* (`L`) contains all of the valid abbreviations for the input word list, including the words themselves, sorted first by the default Raku sort and then by length (shortest first).
+A *List* (`L`) contains all of the valid abbreviations for the input word list, including the words themselves, sorted by length, then character order.
 
   * `S` (String)
 
 A *String* (`S`) is the string formed by joining the *List* by a single space between words.
 
 ### Improved abbreviation search
 
-The abbreviation algorithm has been improved in the following way: The input word set is formed into subgroups comprised of each input word. Abbreviations are created for each word, abbreviations shared by two or words are eliminated, then all those abbreviations are combined into one set. The result will be the largest possible set of unique abbreviations for a given input word set.
+The abbreviation algorithm has been improved from the original (as found on [https://rosettacode.org](https://rosettacode.org)) in the following way: The input word set is formed into subgroups comprised of each input word. Abbreviations are created for each word, abbreviations shared by two or words are eliminated, then all those abbreviations are combined into one set. The result will be the largest possible set of unique abbreviations for a given input word set.
 
 For example, given an input set consisting of the words `A ab Abcde`, the default output hash of abbreviations (with the original words as keys) contains a total of seven abbreviations:
 
@@ -99,18 +144,35 @@ The result is
         ab    => ['ab],
         abcde => ['abc', 'abcd', 'abcde'],
 
+Notice the input word **ab** now has only one abbreviation and **abcde** has only three.
+
 Other exported symbols
 ----------------------
 
 ### `sub sort-list`
 
-    sub sort-list(@list, :longest-first --> List) is export(:sort) {...}
+    sub sort-list(@list, :$type = SL, :$reverse --> List) is export(:sort)
+    {...}
 
-This routine sorts the input list first by the default Raku sort and then by word length. The order by length is by shortest abbreviation first unless the `:longest-first` option is used. This is the routine used for all the lists produced as output in this module *except* for the *AbbrevList* (`AL`) which keeps the original word set order.
+By default, this routine sorts all lists by word length, then by Str order. The order by length is by the shortest abbreviation first unless the `:$reverse` option is used. This is the routine used for all the output types produced by this module *except* the *AbbrevList* (`AL`) which keeps the original word set order.
 
-### `enum Out-type`
+The routine's output can be modified for other uses by entering the `:$type` parameter to choose another of the <enum Sort-type>s.
+
+### `enum Sort-type`
+
+    enum Sort-type is export(:sort) < SL LS SS LL N>;
+
+The `Sort-type`s are:
+
+  * SL - order by Str, then order by Length
+
+  * LS - order by Length, then order by Str
+
+  * SS - Str order only
+
+  * LL - Length order only
 
-The *enum* `Out-type` is exported automatically as it is required for use of `sub abbreviations`.
+  * N - Numerical order only (falls back to SS if any words are not numbers)
 
 AUTHOR
 ======
@@ -129,7 +191,7 @@ CREDITS
 COPYRIGHT and LICENSE
 =====================
 
-Copyright © 2020-2022 Tom Browder
+Copyright © 2020-2023 Tom Browder
 
 This library is free software; you may redistribute or modify it under the Artistic License 2.0.