Merge pull request #34 from Stravaig-Projects/#33-render-pattern

#33 Make the short code render in to a pattern

Author: colinangusmackay

README.md

@@ -52,6 +52,10 @@ ShortCode.GenerateSequentialShortCode();
 
 // To generate sequential short code of the given length
 ShortCode.GenerateSequentialShortCode(int length);
+
+// To generate a patterned short code
+// by default in the format XXX-XXX-XXX
+ShortCode.GeneratePatternedShortCode();
 ```
 
 There are some configuration methods you can call during your app's startup:
@@ -63,6 +67,15 @@ There are some configuration methods you can call during your app's startup:
   - `GuidCodeGenerator`: The code is a hashed form of a GUID
   - `RandomCodeGenerator`: The code is generated from the `Random` class.
   - `CrytographicallyRandomCodeGenerator`: The code is generated using a cryptographic strength random number generator.
+* `ShortCode.SetPattern(IEnumerable<PatternPart> parts)`: Sets the pattern using the given parts. (See below)
+
+## Pattern Parts
+
+If you are using patterned short codes then you can define the pattern with a collection of `PatternPart`. There are two types of pattern part, a `Fixed` part, which consists of a fixed string; and, a `EncodeIntoCharacterSpace` type, which is part of the encoded short code.
+
+To create the encoding part: `new PatternPart(string characterSpace, int length)`. The character space is a string containing the valid characters that a code can contain. It must be made up of unique characters. The `length` is the length of the encoded sequence.
+
+To create the fixed part: `new PatternPart(string fixedChars)`. Where `fixedChars` is the fixed string that is used to separate parts of the code.
 
 ## Setting up Short Codes with Microsoft's Dependency Injection
 
@@ -143,9 +156,37 @@ In the appsettings.json file:
 }
 ```
 
+If you prefer to use a patterned short code generator the appsettings.json will look something like this:
+
+```json
+{
+  "Stravaig": {
+    "ShortCode": {
+      "Pattern":[{
+        "Type": "EncodeIntoCharacterSpace",
+        "CharacterSpace": "0123456789QWERTYPLKJHGFDSAZXCVBNM",
+        "Length": 4
+      },{
+        "Type": "Fixed",
+        "FixedString": "-"
+      },{
+        "Type": "EncodeIntoCharacterSpace",
+        "CharacterSpace": "0123456789QWERTYPLKJHGFDSAZXCVBNM",
+        "Length": 4
+      }],
+      "Generator": {
+        "Seed": 12345
+      }
+    }
+  }
+}
+```
+
+Note, that when the configuration contains a pattern it overrides any general specification.
+
 ## Using the IShortCodeFactory
 
 To get a short code, the `IShortCodeFactory` interface exposes two methods for to create short codes.
 
 * `GetNextCode()` will simply get the next code.
-* `GetCodes(int)` will return the number of codes specified as an `IEnumerable<string>`
+* `GetCodes(int number)` will return the `number` of codes specified as an `IEnumerable<string>`

release-notes/wip-release-notes.md

@@ -8,8 +8,13 @@ Date: ???
 
 ### Features
 
+- #33: Have patterned codes.
+
 ### Miscellaneous
 
 ### Dependabot
 
+- Bump Microsoft.Extensions.DependencyInjection.Abstractions from 3.1.11 to 3.1.12
+- Bump Microsoft.NET.Test.Sdk from 16.8.3 to 16.9.1- Bump NUnit from 3.13.0 to 3.13.1
+- Bump Stravaig.Extensions.Logging.Diagnostics from 0.3.1 to 0.3.2
 

src/.idea/.idea.Stravaig.ShortCode/.idea/riderModule.iml

@@ -14,6 +14,16 @@ static void Main()
 
             ServiceCollection services = new ServiceCollection();
             services.AddShortCodeGenerator<SequentialCodeGenerator>(config);
+            // Alternative - Build the options in code.
+            // services.AddShortCodeGenerator<SequentialCodeGenerator>(options =>
+            // {
+            //     options.Pattern = new[]
+            //     {
+            //         new PatternOptions(NamedCharacterSpaces.UpperLatinLetters, 3),
+            //         new PatternOptions("-"),
+            //         new PatternOptions(NamedCharacterSpaces.Digits, 3),
+            //     };
+            // });
 
             ServiceProvider provider = services.BuildServiceProvider();
             var factory = provider.GetRequiredService<IShortCodeFactory>();

src/Example/Program.cs

@@ -8,6 +8,18 @@
     },
     "Stravaig": {
         "ShortCode": {
+            "Pattern":[{
+                    "Type": "EncodeIntoCharacterSpace",
+                    "CharacterSpace": "0123456789QWERTYUIOPLKJHGFDSAZXCVBNM",
+                    "Length": 4
+                },{
+                "Type": "Fixed",
+                "FixedString": "-"
+            },{
+                "Type": "EncodeIntoCharacterSpace",
+                "CharacterSpace": "0123456789QWERTYUIOPLKJHGFDSAZXCVBNM",
+                "Length": 4
+            }],
             "CharacterSpace": "0123456789QWERTYUIOPLKJHGFDSAZXCVBNM",
             "FixedLength": 7,
             "Generator": {

src/Example/appsettings.json

@@ -29,11 +29,6 @@ public string Convert(ulong fullCode, int? fixedChars = null, int maxChars = int
             return result.ToString();
         }
 
-        public ulong RangeRequired(int numChars)
-        {
-            return (ulong)Math.Pow(_characterSpace.Length, numChars);
-        }
-
         public int MaxLength()
         {
             return (int)(Math.Log(ulong.MaxValue) / Math.Log(_characterSpace.Length));

src/Stravaig.ShortCode.Benchmarks/Variants/Encoder1.cs

@@ -28,11 +28,6 @@ public string Convert(ulong fullCode, int? fixedChars = null, int maxChars = 64)
             return new String(resultChars, 0, index);
         }
 
-        public ulong RangeRequired(int numChars)
-        {
-            return (ulong)Math.Pow(_characterSpace.Length, numChars);
-        }
-
         public int MaxLength()
         {
             return (int)(Math.Log(ulong.MaxValue) / Math.Log(_characterSpace.Length));

src/Stravaig.ShortCode.Benchmarks/Variants/Encoder2.cs

@@ -0,0 +1,12 @@
+namespace Stravaig.ShortCode.DependencyInjection
+{
+    internal static class PatternOptionsExtensions
+    {
+        public static PatternPart ToPatternPart(this PatternOptions options)
+        {
+            if (options.Type == PatternType.Fixed)
+                return new PatternPart(options.FixedString);
+            return new PatternPart(options.CharacterSpace, options.Length);
+        }
+    }
+}

src/Stravaig.ShortCode.DependencyInjection/PatternOptionsExtensions.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Linq;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
@@ -39,7 +40,10 @@ private static void AddCommonParts<TGenerator>(this IServiceCollection services)
             services.AddSingleton<IEncoder>(p =>
             {
                 var options = p.GetRequiredService<IOptions<ShortCodeOptions>>();
-                return new Encoder(options.Value.CharacterSpace);
+                if (options.Value.Pattern.Length == 0)
+                    return new Encoder(options.Value.CharacterSpace);
+                return new PatternedEncoder(options.Value.Pattern
+                    .Select(pat => pat.ToPatternPart()));
             });
             services.AddSingleton<IShortCodeGenerator, TGenerator>();
             services.AddSingleton<IShortCodeFactory, ShortCodeFactory>();

src/Stravaig.ShortCode.DependencyInjection/ServiceProviderExtensions.cs

@@ -25,19 +25,6 @@ public void Ctor_WithSingleCharacter()
             ex.Message.ShouldStartWith("Value cannot have a single character.");
         }
 
-        [TestCase(1, NamedCharacterSpaces.Digits, ExpectedResult = (ulong)10)]
-        [TestCase(2, NamedCharacterSpaces.Digits, ExpectedResult = (ulong)100)]
-        [TestCase(1, NamedCharacterSpaces.LowerLatinLetters, ExpectedResult = (ulong)26)]
-        [TestCase(2, NamedCharacterSpaces.LowerLatinLetters, ExpectedResult = (ulong)676)]
-        [TestCase(3, NamedCharacterSpaces.LatinLetters, ExpectedResult = (ulong)140608)]
-        [TestCase(4, NamedCharacterSpaces.LettersAndDigits, ExpectedResult = (ulong)14776336)]
-        [TestCase(5, NamedCharacterSpaces.LettersAndDigits, ExpectedResult = (ulong)916132832)]
-        public ulong RangeRequiredReturnsGoodValueForCharacterSpace(int numChars, string charSpace)
-        {
-            var characterSpace = new Encoder(charSpace);
-            return characterSpace.RangeRequired(numChars);
-        }
-
         [TestCase(NamedCharacterSpaces.LettersAndDigits, ExpectedResult = 10)]
         [TestCase(NamedCharacterSpaces.Digits, ExpectedResult = 19)]
         public int MaxLengthTests(string charSpace)