From ab7b83abbbbce19fe465077d0bdd5a610271564a Mon Sep 17 00:00:00 2001 From: wagesj45 Date: Tue, 7 Jul 2026 01:31:52 -0500 Subject: [PATCH] Improve developer documentation --- ...Kit.Attributes.EnumerationAttribute-1.html | 16 +-- ...butes.EnumerationDescriptionAttribute.html | 16 +-- ...pyKit.Attributes.ValueFormatAttribute.html | 16 +-- Docs/_site/api/CapyKit.Attributes.html | 16 +-- Docs/_site/api/CapyKit.CapyEventArgs.html | 16 +-- Docs/_site/api/CapyKit.CapyEventHandler.html | 16 +-- Docs/_site/api/CapyKit.CapyEventReporter.html | 16 +-- Docs/_site/api/CapyKit.Color.html | 16 +-- Docs/_site/api/CapyKit.EncryptedValue-1.html | 16 +-- ...apyKit.Enumerations.MeasurementSystem.html | 16 +-- Docs/_site/api/CapyKit.Enumerations.html | 16 +-- Docs/_site/api/CapyKit.EventLevel.html | 16 +-- ...yKit.Extensions.EnumerationExtensions.html | 16 +-- .../CapyKit.Extensions.LINQExtensions.html | 16 +-- .../CapyKit.Extensions.ObjectExtensions.html | 16 +-- .../CapyKit.Extensions.StringExtensions.html | 16 +-- Docs/_site/api/CapyKit.Extensions.html | 16 +-- .../CapyKit.Helpers.CalculationHelper.html | 16 +-- .../CapyKit.Helpers.CompressionHelper.html | 16 +-- .../api/CapyKit.Helpers.EncryptionHelper.html | 16 +-- .../CapyKit.Helpers.IEncryptionAlgorithm.html | 16 +-- Docs/_site/api/CapyKit.Helpers.KeyHelper.html | 16 +-- .../api/CapyKit.Helpers.LanguageHelper.html | 16 +-- .../api/CapyKit.Helpers.SecurityHelper.html | 16 +-- .../CapyKit.Helpers.SerializationHelper.html | 16 +-- .../api/CapyKit.Helpers.SettingsHelper.html | 16 +-- ...yKit.Helpers.ValidCharacterCollection.html | 16 +-- Docs/_site/api/CapyKit.Helpers.html | 16 +-- .../_site/api/CapyKit.IPasswordAlgorithm.html | 16 +-- Docs/_site/api/CapyKit.NamedColor.html | 16 +-- Docs/_site/api/CapyKit.Password.html | 16 +-- Docs/_site/api/CapyKit.Pbkdf2Algorithm.html | 16 +-- Docs/_site/api/CapyKit.Pool-1.html | 16 +-- Docs/_site/api/CapyKit.PoolItem-1.html | 16 +-- .../_site/api/CapyKit.PropertyComparer-2.html | 16 +-- Docs/_site/api/CapyKit.html | 16 +-- Docs/_site/api/toc.json | 2 +- Docs/_site/getting-started.html | 88 ++++++++++++ Docs/_site/index.html | 61 ++++++-- Docs/_site/index.json | 8 +- Docs/_site/introduction.html | 35 +++++ Docs/_site/toc.html | 135 ++++++++++++++++++ Docs/_site/toc.json | 2 +- Docs/getting-started.md | 133 ++++++++++++++++- Docs/index.md | 90 ++++++++++-- Docs/introduction.md | 48 ++++++- Docs/toc.yml | 10 +- README.md | 65 ++++++++- 48 files changed, 678 insertions(+), 575 deletions(-) diff --git a/Docs/_site/api/CapyKit.Attributes.EnumerationAttribute-1.html b/Docs/_site/api/CapyKit.Attributes.EnumerationAttribute-1.html index 2a8bfe4..a75c443 100644 --- a/Docs/_site/api/CapyKit.Attributes.EnumerationAttribute-1.html +++ b/Docs/_site/api/CapyKit.Attributes.EnumerationAttribute-1.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Attributes.EnumerationDescriptionAttribute.html b/Docs/_site/api/CapyKit.Attributes.EnumerationDescriptionAttribute.html index 1b8cca9..87719af 100644 --- a/Docs/_site/api/CapyKit.Attributes.EnumerationDescriptionAttribute.html +++ b/Docs/_site/api/CapyKit.Attributes.EnumerationDescriptionAttribute.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Attributes.ValueFormatAttribute.html b/Docs/_site/api/CapyKit.Attributes.ValueFormatAttribute.html index 4da69c0..5b586f3 100644 --- a/Docs/_site/api/CapyKit.Attributes.ValueFormatAttribute.html +++ b/Docs/_site/api/CapyKit.Attributes.ValueFormatAttribute.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Attributes.html b/Docs/_site/api/CapyKit.Attributes.html index 4b82f8b..fde94a0 100644 --- a/Docs/_site/api/CapyKit.Attributes.html +++ b/Docs/_site/api/CapyKit.Attributes.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.CapyEventArgs.html b/Docs/_site/api/CapyKit.CapyEventArgs.html index 0d0a600..e4a0beb 100644 --- a/Docs/_site/api/CapyKit.CapyEventArgs.html +++ b/Docs/_site/api/CapyKit.CapyEventArgs.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.CapyEventHandler.html b/Docs/_site/api/CapyKit.CapyEventHandler.html index f681b55..9dab963 100644 --- a/Docs/_site/api/CapyKit.CapyEventHandler.html +++ b/Docs/_site/api/CapyKit.CapyEventHandler.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.CapyEventReporter.html b/Docs/_site/api/CapyKit.CapyEventReporter.html index 784745f..9c38e9a 100644 --- a/Docs/_site/api/CapyKit.CapyEventReporter.html +++ b/Docs/_site/api/CapyKit.CapyEventReporter.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Color.html b/Docs/_site/api/CapyKit.Color.html index 5d54cb8..88f5e81 100644 --- a/Docs/_site/api/CapyKit.Color.html +++ b/Docs/_site/api/CapyKit.Color.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.EncryptedValue-1.html b/Docs/_site/api/CapyKit.EncryptedValue-1.html index e1bab6a..d77c6a5 100644 --- a/Docs/_site/api/CapyKit.EncryptedValue-1.html +++ b/Docs/_site/api/CapyKit.EncryptedValue-1.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Enumerations.MeasurementSystem.html b/Docs/_site/api/CapyKit.Enumerations.MeasurementSystem.html index 19db71b..b9e7c22 100644 --- a/Docs/_site/api/CapyKit.Enumerations.MeasurementSystem.html +++ b/Docs/_site/api/CapyKit.Enumerations.MeasurementSystem.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Enumerations.html b/Docs/_site/api/CapyKit.Enumerations.html index 55c986e..0452e67 100644 --- a/Docs/_site/api/CapyKit.Enumerations.html +++ b/Docs/_site/api/CapyKit.Enumerations.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.EventLevel.html b/Docs/_site/api/CapyKit.EventLevel.html index ab31307..b5af52a 100644 --- a/Docs/_site/api/CapyKit.EventLevel.html +++ b/Docs/_site/api/CapyKit.EventLevel.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Extensions.EnumerationExtensions.html b/Docs/_site/api/CapyKit.Extensions.EnumerationExtensions.html index eea6b1b..c3005bc 100644 --- a/Docs/_site/api/CapyKit.Extensions.EnumerationExtensions.html +++ b/Docs/_site/api/CapyKit.Extensions.EnumerationExtensions.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Extensions.LINQExtensions.html b/Docs/_site/api/CapyKit.Extensions.LINQExtensions.html index d97a130..d8ed5c9 100644 --- a/Docs/_site/api/CapyKit.Extensions.LINQExtensions.html +++ b/Docs/_site/api/CapyKit.Extensions.LINQExtensions.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Extensions.ObjectExtensions.html b/Docs/_site/api/CapyKit.Extensions.ObjectExtensions.html index 32f4090..fc09224 100644 --- a/Docs/_site/api/CapyKit.Extensions.ObjectExtensions.html +++ b/Docs/_site/api/CapyKit.Extensions.ObjectExtensions.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Extensions.StringExtensions.html b/Docs/_site/api/CapyKit.Extensions.StringExtensions.html index 8b24a89..92cfa1d 100644 --- a/Docs/_site/api/CapyKit.Extensions.StringExtensions.html +++ b/Docs/_site/api/CapyKit.Extensions.StringExtensions.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Extensions.html b/Docs/_site/api/CapyKit.Extensions.html index 1f88abd..a171537 100644 --- a/Docs/_site/api/CapyKit.Extensions.html +++ b/Docs/_site/api/CapyKit.Extensions.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.CalculationHelper.html b/Docs/_site/api/CapyKit.Helpers.CalculationHelper.html index ec338ae..9a1a58a 100644 --- a/Docs/_site/api/CapyKit.Helpers.CalculationHelper.html +++ b/Docs/_site/api/CapyKit.Helpers.CalculationHelper.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.CompressionHelper.html b/Docs/_site/api/CapyKit.Helpers.CompressionHelper.html index d392005..f170ed6 100644 --- a/Docs/_site/api/CapyKit.Helpers.CompressionHelper.html +++ b/Docs/_site/api/CapyKit.Helpers.CompressionHelper.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.EncryptionHelper.html b/Docs/_site/api/CapyKit.Helpers.EncryptionHelper.html index 4af679e..2d1edcf 100644 --- a/Docs/_site/api/CapyKit.Helpers.EncryptionHelper.html +++ b/Docs/_site/api/CapyKit.Helpers.EncryptionHelper.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.IEncryptionAlgorithm.html b/Docs/_site/api/CapyKit.Helpers.IEncryptionAlgorithm.html index 531f196..ee34177 100644 --- a/Docs/_site/api/CapyKit.Helpers.IEncryptionAlgorithm.html +++ b/Docs/_site/api/CapyKit.Helpers.IEncryptionAlgorithm.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.KeyHelper.html b/Docs/_site/api/CapyKit.Helpers.KeyHelper.html index 1dfa3d9..4130cf8 100644 --- a/Docs/_site/api/CapyKit.Helpers.KeyHelper.html +++ b/Docs/_site/api/CapyKit.Helpers.KeyHelper.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.LanguageHelper.html b/Docs/_site/api/CapyKit.Helpers.LanguageHelper.html index 6d84602..4f52448 100644 --- a/Docs/_site/api/CapyKit.Helpers.LanguageHelper.html +++ b/Docs/_site/api/CapyKit.Helpers.LanguageHelper.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.SecurityHelper.html b/Docs/_site/api/CapyKit.Helpers.SecurityHelper.html index d4502ec..775ed86 100644 --- a/Docs/_site/api/CapyKit.Helpers.SecurityHelper.html +++ b/Docs/_site/api/CapyKit.Helpers.SecurityHelper.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.SerializationHelper.html b/Docs/_site/api/CapyKit.Helpers.SerializationHelper.html index 7fa4ab0..b9db821 100644 --- a/Docs/_site/api/CapyKit.Helpers.SerializationHelper.html +++ b/Docs/_site/api/CapyKit.Helpers.SerializationHelper.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.SettingsHelper.html b/Docs/_site/api/CapyKit.Helpers.SettingsHelper.html index 1df2a68..6513703 100644 --- a/Docs/_site/api/CapyKit.Helpers.SettingsHelper.html +++ b/Docs/_site/api/CapyKit.Helpers.SettingsHelper.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.ValidCharacterCollection.html b/Docs/_site/api/CapyKit.Helpers.ValidCharacterCollection.html index 4bc0634..3332de0 100644 --- a/Docs/_site/api/CapyKit.Helpers.ValidCharacterCollection.html +++ b/Docs/_site/api/CapyKit.Helpers.ValidCharacterCollection.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Helpers.html b/Docs/_site/api/CapyKit.Helpers.html index 598c83a..0aacad0 100644 --- a/Docs/_site/api/CapyKit.Helpers.html +++ b/Docs/_site/api/CapyKit.Helpers.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.IPasswordAlgorithm.html b/Docs/_site/api/CapyKit.IPasswordAlgorithm.html index d84f1fa..db810cd 100644 --- a/Docs/_site/api/CapyKit.IPasswordAlgorithm.html +++ b/Docs/_site/api/CapyKit.IPasswordAlgorithm.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.NamedColor.html b/Docs/_site/api/CapyKit.NamedColor.html index 7edfc57..5287365 100644 --- a/Docs/_site/api/CapyKit.NamedColor.html +++ b/Docs/_site/api/CapyKit.NamedColor.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Password.html b/Docs/_site/api/CapyKit.Password.html index b23b0c1..823e909 100644 --- a/Docs/_site/api/CapyKit.Password.html +++ b/Docs/_site/api/CapyKit.Password.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Pbkdf2Algorithm.html b/Docs/_site/api/CapyKit.Pbkdf2Algorithm.html index 75632f3..0f3f4f1 100644 --- a/Docs/_site/api/CapyKit.Pbkdf2Algorithm.html +++ b/Docs/_site/api/CapyKit.Pbkdf2Algorithm.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.Pool-1.html b/Docs/_site/api/CapyKit.Pool-1.html index 9352ec7..30474a1 100644 --- a/Docs/_site/api/CapyKit.Pool-1.html +++ b/Docs/_site/api/CapyKit.Pool-1.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.PoolItem-1.html b/Docs/_site/api/CapyKit.PoolItem-1.html index ebd5c9c..99ca7e3 100644 --- a/Docs/_site/api/CapyKit.PoolItem-1.html +++ b/Docs/_site/api/CapyKit.PoolItem-1.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.PropertyComparer-2.html b/Docs/_site/api/CapyKit.PropertyComparer-2.html index 01dcc6c..3a8530a 100644 --- a/Docs/_site/api/CapyKit.PropertyComparer-2.html +++ b/Docs/_site/api/CapyKit.PropertyComparer-2.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/CapyKit.html b/Docs/_site/api/CapyKit.html index d1430e3..a5c5487 100644 --- a/Docs/_site/api/CapyKit.html +++ b/Docs/_site/api/CapyKit.html @@ -11,7 +11,7 @@ - + @@ -63,23 +63,9 @@
-
-
-
-
Table of Contents
- -
-
- -
-
-
-
diff --git a/Docs/_site/api/toc.json b/Docs/_site/api/toc.json index 77b73da..cf78d8e 100644 --- a/Docs/_site/api/toc.json +++ b/Docs/_site/api/toc.json @@ -1,2 +1,2 @@ -{"items":[{"name":"CapyKit","href":"CapyKit.html","topicHref":"CapyKit.html","topicUid":"CapyKit","type":"Namespace","items":[{"name":"CapyEventArgs","href":"CapyKit.CapyEventArgs.html","topicHref":"CapyKit.CapyEventArgs.html","topicUid":"CapyKit.CapyEventArgs","type":"Class"},{"name":"CapyEventHandler","href":"CapyKit.CapyEventHandler.html","topicHref":"CapyKit.CapyEventHandler.html","topicUid":"CapyKit.CapyEventHandler","type":"Delegate"},{"name":"CapyEventReporter","href":"CapyKit.CapyEventReporter.html","topicHref":"CapyKit.CapyEventReporter.html","topicUid":"CapyKit.CapyEventReporter","type":"Class"},{"name":"Color","href":"CapyKit.Color.html","topicHref":"CapyKit.Color.html","topicUid":"CapyKit.Color","type":"Class"},{"name":"EncryptedValue","href":"CapyKit.EncryptedValue-1.html","topicHref":"CapyKit.EncryptedValue-1.html","topicUid":"CapyKit.EncryptedValue`1","type":"Class"},{"name":"EventLevel","href":"CapyKit.EventLevel.html","topicHref":"CapyKit.EventLevel.html","topicUid":"CapyKit.EventLevel","type":"Enum"},{"name":"IPasswordAlgorithm","href":"CapyKit.IPasswordAlgorithm.html","topicHref":"CapyKit.IPasswordAlgorithm.html","topicUid":"CapyKit.IPasswordAlgorithm","type":"Interface"},{"name":"NamedColor","href":"CapyKit.NamedColor.html","topicHref":"CapyKit.NamedColor.html","topicUid":"CapyKit.NamedColor","type":"Enum"},{"name":"Password","href":"CapyKit.Password.html","topicHref":"CapyKit.Password.html","topicUid":"CapyKit.Password","type":"Class"},{"name":"Pbkdf2Algorithm","href":"CapyKit.Pbkdf2Algorithm.html","topicHref":"CapyKit.Pbkdf2Algorithm.html","topicUid":"CapyKit.Pbkdf2Algorithm","type":"Class"},{"name":"PoolItem","href":"CapyKit.PoolItem-1.html","topicHref":"CapyKit.PoolItem-1.html","topicUid":"CapyKit.PoolItem`1","type":"Class"},{"name":"Pool","href":"CapyKit.Pool-1.html","topicHref":"CapyKit.Pool-1.html","topicUid":"CapyKit.Pool`1","type":"Class"},{"name":"PropertyComparer","href":"CapyKit.PropertyComparer-2.html","topicHref":"CapyKit.PropertyComparer-2.html","topicUid":"CapyKit.PropertyComparer`2","type":"Class"}]},{"name":"CapyKit.Attributes","href":"CapyKit.Attributes.html","topicHref":"CapyKit.Attributes.html","topicUid":"CapyKit.Attributes","type":"Namespace","items":[{"name":"EnumerationAttribute","href":"CapyKit.Attributes.EnumerationAttribute-1.html","topicHref":"CapyKit.Attributes.EnumerationAttribute-1.html","topicUid":"CapyKit.Attributes.EnumerationAttribute`1","type":"Class"},{"name":"EnumerationDescriptionAttribute","href":"CapyKit.Attributes.EnumerationDescriptionAttribute.html","topicHref":"CapyKit.Attributes.EnumerationDescriptionAttribute.html","topicUid":"CapyKit.Attributes.EnumerationDescriptionAttribute","type":"Class"},{"name":"ValueFormatAttribute","href":"CapyKit.Attributes.ValueFormatAttribute.html","topicHref":"CapyKit.Attributes.ValueFormatAttribute.html","topicUid":"CapyKit.Attributes.ValueFormatAttribute","type":"Class"}]},{"name":"CapyKit.Enumerations","href":"CapyKit.Enumerations.html","topicHref":"CapyKit.Enumerations.html","topicUid":"CapyKit.Enumerations","type":"Namespace","items":[{"name":"MeasurementSystem","href":"CapyKit.Enumerations.MeasurementSystem.html","topicHref":"CapyKit.Enumerations.MeasurementSystem.html","topicUid":"CapyKit.Enumerations.MeasurementSystem","type":"Enum"}]},{"name":"CapyKit.Extensions","href":"CapyKit.Extensions.html","topicHref":"CapyKit.Extensions.html","topicUid":"CapyKit.Extensions","type":"Namespace","items":[{"name":"EnumerationExtensions","href":"CapyKit.Extensions.EnumerationExtensions.html","topicHref":"CapyKit.Extensions.EnumerationExtensions.html","topicUid":"CapyKit.Extensions.EnumerationExtensions","type":"Class"},{"name":"LINQExtensions","href":"CapyKit.Extensions.LINQExtensions.html","topicHref":"CapyKit.Extensions.LINQExtensions.html","topicUid":"CapyKit.Extensions.LINQExtensions","type":"Class"},{"name":"ObjectExtensions","href":"CapyKit.Extensions.ObjectExtensions.html","topicHref":"CapyKit.Extensions.ObjectExtensions.html","topicUid":"CapyKit.Extensions.ObjectExtensions","type":"Class"},{"name":"StringExtensions","href":"CapyKit.Extensions.StringExtensions.html","topicHref":"CapyKit.Extensions.StringExtensions.html","topicUid":"CapyKit.Extensions.StringExtensions","type":"Class"}]},{"name":"CapyKit.Helpers","href":"CapyKit.Helpers.html","topicHref":"CapyKit.Helpers.html","topicUid":"CapyKit.Helpers","type":"Namespace","items":[{"name":"CalculationHelper","href":"CapyKit.Helpers.CalculationHelper.html","topicHref":"CapyKit.Helpers.CalculationHelper.html","topicUid":"CapyKit.Helpers.CalculationHelper","type":"Class"},{"name":"CompressionHelper","href":"CapyKit.Helpers.CompressionHelper.html","topicHref":"CapyKit.Helpers.CompressionHelper.html","topicUid":"CapyKit.Helpers.CompressionHelper","type":"Class"},{"name":"EncryptionHelper","href":"CapyKit.Helpers.EncryptionHelper.html","topicHref":"CapyKit.Helpers.EncryptionHelper.html","topicUid":"CapyKit.Helpers.EncryptionHelper","type":"Class"},{"name":"IEncryptionAlgorithm","href":"CapyKit.Helpers.IEncryptionAlgorithm.html","topicHref":"CapyKit.Helpers.IEncryptionAlgorithm.html","topicUid":"CapyKit.Helpers.IEncryptionAlgorithm","type":"Interface"},{"name":"KeyHelper","href":"CapyKit.Helpers.KeyHelper.html","topicHref":"CapyKit.Helpers.KeyHelper.html","topicUid":"CapyKit.Helpers.KeyHelper","type":"Class"},{"name":"LanguageHelper","href":"CapyKit.Helpers.LanguageHelper.html","topicHref":"CapyKit.Helpers.LanguageHelper.html","topicUid":"CapyKit.Helpers.LanguageHelper","type":"Class"},{"name":"SecurityHelper","href":"CapyKit.Helpers.SecurityHelper.html","topicHref":"CapyKit.Helpers.SecurityHelper.html","topicUid":"CapyKit.Helpers.SecurityHelper","type":"Class"},{"name":"SerializationHelper","href":"CapyKit.Helpers.SerializationHelper.html","topicHref":"CapyKit.Helpers.SerializationHelper.html","topicUid":"CapyKit.Helpers.SerializationHelper","type":"Class"},{"name":"SettingsHelper","href":"CapyKit.Helpers.SettingsHelper.html","topicHref":"CapyKit.Helpers.SettingsHelper.html","topicUid":"CapyKit.Helpers.SettingsHelper","type":"Class"},{"name":"ValidCharacterCollection","href":"CapyKit.Helpers.ValidCharacterCollection.html","topicHref":"CapyKit.Helpers.ValidCharacterCollection.html","topicUid":"CapyKit.Helpers.ValidCharacterCollection","type":"Enum"}]}],"memberLayout":"SamePage","pdf":false} +{"order":100,"items":[{"name":"CapyKit","href":"CapyKit.html","topicHref":"CapyKit.html","topicUid":"CapyKit","type":"Namespace","items":[{"name":"CapyEventArgs","href":"CapyKit.CapyEventArgs.html","topicHref":"CapyKit.CapyEventArgs.html","topicUid":"CapyKit.CapyEventArgs","type":"Class"},{"name":"CapyEventHandler","href":"CapyKit.CapyEventHandler.html","topicHref":"CapyKit.CapyEventHandler.html","topicUid":"CapyKit.CapyEventHandler","type":"Delegate"},{"name":"CapyEventReporter","href":"CapyKit.CapyEventReporter.html","topicHref":"CapyKit.CapyEventReporter.html","topicUid":"CapyKit.CapyEventReporter","type":"Class"},{"name":"Color","href":"CapyKit.Color.html","topicHref":"CapyKit.Color.html","topicUid":"CapyKit.Color","type":"Class"},{"name":"EncryptedValue","href":"CapyKit.EncryptedValue-1.html","topicHref":"CapyKit.EncryptedValue-1.html","topicUid":"CapyKit.EncryptedValue`1","type":"Class"},{"name":"EventLevel","href":"CapyKit.EventLevel.html","topicHref":"CapyKit.EventLevel.html","topicUid":"CapyKit.EventLevel","type":"Enum"},{"name":"IPasswordAlgorithm","href":"CapyKit.IPasswordAlgorithm.html","topicHref":"CapyKit.IPasswordAlgorithm.html","topicUid":"CapyKit.IPasswordAlgorithm","type":"Interface"},{"name":"NamedColor","href":"CapyKit.NamedColor.html","topicHref":"CapyKit.NamedColor.html","topicUid":"CapyKit.NamedColor","type":"Enum"},{"name":"Password","href":"CapyKit.Password.html","topicHref":"CapyKit.Password.html","topicUid":"CapyKit.Password","type":"Class"},{"name":"Pbkdf2Algorithm","href":"CapyKit.Pbkdf2Algorithm.html","topicHref":"CapyKit.Pbkdf2Algorithm.html","topicUid":"CapyKit.Pbkdf2Algorithm","type":"Class"},{"name":"PoolItem","href":"CapyKit.PoolItem-1.html","topicHref":"CapyKit.PoolItem-1.html","topicUid":"CapyKit.PoolItem`1","type":"Class"},{"name":"Pool","href":"CapyKit.Pool-1.html","topicHref":"CapyKit.Pool-1.html","topicUid":"CapyKit.Pool`1","type":"Class"},{"name":"PropertyComparer","href":"CapyKit.PropertyComparer-2.html","topicHref":"CapyKit.PropertyComparer-2.html","topicUid":"CapyKit.PropertyComparer`2","type":"Class"}]},{"name":"CapyKit.Attributes","href":"CapyKit.Attributes.html","topicHref":"CapyKit.Attributes.html","topicUid":"CapyKit.Attributes","type":"Namespace","items":[{"name":"EnumerationAttribute","href":"CapyKit.Attributes.EnumerationAttribute-1.html","topicHref":"CapyKit.Attributes.EnumerationAttribute-1.html","topicUid":"CapyKit.Attributes.EnumerationAttribute`1","type":"Class"},{"name":"EnumerationDescriptionAttribute","href":"CapyKit.Attributes.EnumerationDescriptionAttribute.html","topicHref":"CapyKit.Attributes.EnumerationDescriptionAttribute.html","topicUid":"CapyKit.Attributes.EnumerationDescriptionAttribute","type":"Class"},{"name":"ValueFormatAttribute","href":"CapyKit.Attributes.ValueFormatAttribute.html","topicHref":"CapyKit.Attributes.ValueFormatAttribute.html","topicUid":"CapyKit.Attributes.ValueFormatAttribute","type":"Class"}]},{"name":"CapyKit.Enumerations","href":"CapyKit.Enumerations.html","topicHref":"CapyKit.Enumerations.html","topicUid":"CapyKit.Enumerations","type":"Namespace","items":[{"name":"MeasurementSystem","href":"CapyKit.Enumerations.MeasurementSystem.html","topicHref":"CapyKit.Enumerations.MeasurementSystem.html","topicUid":"CapyKit.Enumerations.MeasurementSystem","type":"Enum"}]},{"name":"CapyKit.Extensions","href":"CapyKit.Extensions.html","topicHref":"CapyKit.Extensions.html","topicUid":"CapyKit.Extensions","type":"Namespace","items":[{"name":"EnumerationExtensions","href":"CapyKit.Extensions.EnumerationExtensions.html","topicHref":"CapyKit.Extensions.EnumerationExtensions.html","topicUid":"CapyKit.Extensions.EnumerationExtensions","type":"Class"},{"name":"LINQExtensions","href":"CapyKit.Extensions.LINQExtensions.html","topicHref":"CapyKit.Extensions.LINQExtensions.html","topicUid":"CapyKit.Extensions.LINQExtensions","type":"Class"},{"name":"ObjectExtensions","href":"CapyKit.Extensions.ObjectExtensions.html","topicHref":"CapyKit.Extensions.ObjectExtensions.html","topicUid":"CapyKit.Extensions.ObjectExtensions","type":"Class"},{"name":"StringExtensions","href":"CapyKit.Extensions.StringExtensions.html","topicHref":"CapyKit.Extensions.StringExtensions.html","topicUid":"CapyKit.Extensions.StringExtensions","type":"Class"}]},{"name":"CapyKit.Helpers","href":"CapyKit.Helpers.html","topicHref":"CapyKit.Helpers.html","topicUid":"CapyKit.Helpers","type":"Namespace","items":[{"name":"CalculationHelper","href":"CapyKit.Helpers.CalculationHelper.html","topicHref":"CapyKit.Helpers.CalculationHelper.html","topicUid":"CapyKit.Helpers.CalculationHelper","type":"Class"},{"name":"CompressionHelper","href":"CapyKit.Helpers.CompressionHelper.html","topicHref":"CapyKit.Helpers.CompressionHelper.html","topicUid":"CapyKit.Helpers.CompressionHelper","type":"Class"},{"name":"EncryptionHelper","href":"CapyKit.Helpers.EncryptionHelper.html","topicHref":"CapyKit.Helpers.EncryptionHelper.html","topicUid":"CapyKit.Helpers.EncryptionHelper","type":"Class"},{"name":"IEncryptionAlgorithm","href":"CapyKit.Helpers.IEncryptionAlgorithm.html","topicHref":"CapyKit.Helpers.IEncryptionAlgorithm.html","topicUid":"CapyKit.Helpers.IEncryptionAlgorithm","type":"Interface"},{"name":"KeyHelper","href":"CapyKit.Helpers.KeyHelper.html","topicHref":"CapyKit.Helpers.KeyHelper.html","topicUid":"CapyKit.Helpers.KeyHelper","type":"Class"},{"name":"LanguageHelper","href":"CapyKit.Helpers.LanguageHelper.html","topicHref":"CapyKit.Helpers.LanguageHelper.html","topicUid":"CapyKit.Helpers.LanguageHelper","type":"Class"},{"name":"SecurityHelper","href":"CapyKit.Helpers.SecurityHelper.html","topicHref":"CapyKit.Helpers.SecurityHelper.html","topicUid":"CapyKit.Helpers.SecurityHelper","type":"Class"},{"name":"SerializationHelper","href":"CapyKit.Helpers.SerializationHelper.html","topicHref":"CapyKit.Helpers.SerializationHelper.html","topicUid":"CapyKit.Helpers.SerializationHelper","type":"Class"},{"name":"SettingsHelper","href":"CapyKit.Helpers.SettingsHelper.html","topicHref":"CapyKit.Helpers.SettingsHelper.html","topicUid":"CapyKit.Helpers.SettingsHelper","type":"Class"},{"name":"ValidCharacterCollection","href":"CapyKit.Helpers.ValidCharacterCollection.html","topicHref":"CapyKit.Helpers.ValidCharacterCollection.html","topicUid":"CapyKit.Helpers.ValidCharacterCollection","type":"Enum"}]}],"memberLayout":"SamePage","pdf":false} diff --git a/Docs/_site/getting-started.html b/Docs/_site/getting-started.html index 52bdba1..b64a0ee 100644 --- a/Docs/_site/getting-started.html +++ b/Docs/_site/getting-started.html @@ -73,6 +73,94 @@

Getting Started

+

This guide shows the common setup and first-use patterns for consuming CapyKit from a .NET 8 project.

+

Install

+

Add CapyKit to your project from NuGet:

+
dotnet add package CapyKit
+
+

If you are working from a local checkout instead, reference the project directly:

+
dotnet add reference ../CapyKit/CapyKit.csproj
+
+

Add Namespaces

+

Most APIs live in one of three namespaces:

+
using CapyKit;
+using CapyKit.Extensions;
+using CapyKit.Helpers;
+
+

Use CapyKit for core types such as Password, Pool<T>, and CapyEventReporter. Use CapyKit.Extensions for extension methods. Use CapyKit.Helpers for serialization, compression, security, keys, language, and calculation helpers.

+

Work With Strings

+
using CapyKit.Extensions;
+
+string? suppliedName = "";
+string name = suppliedName.IfNullOrWhiteSpace("Guest");
+
+

IfNullOrEmpty and IfNullOrWhiteSpace return the original value when it is usable and return your replacement value when it is not.

+

Page And Filter Collections

+
using CapyKit.Extensions;
+
+var activeUsers = users.Filter(user => user.Disabled);
+var secondPage = activeUsers.Page(pageNumber: 2, pageSize: 25);
+int pageCount = activeUsers.PageCount(pageSize: 25);
+
+

Filter removes items that match the predicate. Page uses natural page numbering, so the first page is 1.

+

Serialize And Compress Data

+
using CapyKit.Helpers;
+
+var json = SerializationHelper.SerializeToString(order);
+var copy = SerializationHelper.Deserialize<Order>(json);
+
+var compressed = CompressionHelper.CompressToString(order);
+var restored = CompressionHelper.Decompress<Order>(compressed);
+
+

Serialization uses System.Text.Json. Compression stores the serialized JSON payload using gzip; CompressToString returns a Base64 representation for easier storage or transport.

+

Hash And Verify Passwords

+
using CapyKit;
+using CapyKit.Helpers;
+
+Password storedPassword = SecurityHelper.Pbkdf2("correct horse battery staple");
+
+bool passwordMatches = SecurityHelper.CompareHashedPassword(
+    storedPassword,
+    "correct horse battery staple",
+    storedPassword.Salt,
+    Password.Pbkdf2Algorithm);
+
+

SecurityHelper.Pbkdf2 creates a Password with a random salt. Store the hash, salt, and algorithm information required by your application, then compare future password attempts using the same salt and algorithm.

+

Generate Random Values

+
using CapyKit.Helpers;
+
+string token = SecurityHelper.GetRandomString(32);
+string password = SecurityHelper.GetRandomPassword(
+    20,
+    ValidCharacterCollection.Lowercase,
+    ValidCharacterCollection.Uppercase,
+    ValidCharacterCollection.Numbers,
+    ValidCharacterCollection.Special);
+
+

Random string and password generation use .NET cryptographic random number generation.

+

Create And Validate Keys

+
using System.Text;
+using CapyKit.Helpers;
+
+var keyHelper = new KeyHelper();
+keyHelper.SetMasterKeyAccessor(() => Encoding.UTF8.GetBytes("replace-with-your-master-key"));
+keyHelper.SetSaltSizeAccessor(() => 8);
+keyHelper.SetNumPartsAccessor(() => 4);
+
+string key = keyHelper.GenerateKey();
+bool valid = keyHelper.ValidateKey(key);
+
+

KeyHelper uses an application-provided master key to sign generated key material. Keep the master key secret and stable for keys that must remain valid over time.

+

Subscribe To CapyKit Events

+
using CapyKit;
+
+CapyEventReporter.Subscribe(
+    e => Console.WriteLine($"[{e.Level}] {e.MethodName}: {e.Message}"),
+    EventLevel.Warning);
+
+

CapyKit does not require a logging framework. Subscribe to events and forward them to whatever logging or telemetry system your application already uses.

+

Browse The API

+

For the full list of namespaces, types, overloads, and member signatures, open the generated API Reference.

diff --git a/Docs/_site/index.html b/Docs/_site/index.html index d6a093e..ce25b59 100644 --- a/Docs/_site/index.html +++ b/Docs/_site/index.html @@ -2,9 +2,9 @@ - This is the HOMEPAGE. | CapyKit Documentation + CapyKit Documentation | CapyKit Documentation - + @@ -71,13 +71,58 @@
-

This is the HOMEPAGE.

+

CapyKit Documentation

-

Refer to Markdown for how to write markdown files.

-

Quick Start Notes:

-
    -
  1. Add images to the images folder if the file is referencing an image.
    2. -
+

CapyKit is a small .NET utility library for the code you end up writing repeatedly: collection helpers, string and enum extensions, JSON serialization, gzip compression, password hashing, random token generation, simple key validation, distance calculations, and lightweight event reporting.

+

The library targets .NET 8 and keeps its public surface intentionally direct. Most features are static helpers or extension methods, so consuming projects can adopt one piece at a time without taking on a framework or application model.

+

Start Here

+
    +
  • Introduction explains what CapyKit includes and how the namespaces are organized.
    • +
  • Getting Started shows installation, imports, and common usage examples.
    • +
  • API Reference contains the generated DocFX reference for every public type and member.
    • +
+

Common Tasks

+

Work with strings and collections

+

Use CapyKit.Extensions for small quality-of-life helpers such as null fallback values, pagination, inverted filtering, left outer joins, enum display names, and property copying.

+
using CapyKit.Extensions;
+
+var displayName = user.Name.IfNullOrWhiteSpace("Guest");
+var page = users.Page(pageNumber: 2, pageSize: 25);
+
+

Serialize, compress, and restore values

+

Use CapyKit.Helpers.SerializationHelper and CapyKit.Helpers.CompressionHelper when you need straightforward JSON serialization or gzip compression around serializable values.

+
using CapyKit.Helpers;
+
+var payload = SerializationHelper.SerializeToString(order);
+var compressed = CompressionHelper.CompressToString(order);
+var restored = CompressionHelper.Decompress<Order>(compressed);
+
+

Hash passwords and generate tokens

+

Use SecurityHelper for PBKDF2 password hashes, salts, and random values backed by .NET cryptographic random number generation.

+
using CapyKit;
+using CapyKit.Helpers;
+
+Password password = SecurityHelper.Pbkdf2("correct horse battery staple");
+bool matches = SecurityHelper.CompareHashedPassword(
+    password,
+    "correct horse battery staple",
+    password.Salt,
+    Password.Pbkdf2Algorithm);
+
+

Listen to CapyKit events

+

CapyKit reports warnings and errors through CapyEventReporter instead of choosing a logging framework for you. Subscribe at the level your application cares about and route events into your own logging pipeline.

+
using CapyKit;
+
+CapyEventReporter.Subscribe(
+    e => logger.LogWarning("{Method}: {Message}", e.MethodName, e.Message),
+    EventLevel.Warning);
+
+

Build The Docs Locally

+

The documentation is generated with DocFX from the Markdown files in this folder and the XML comments in the CapyKit project.

+
dotnet tool install -g docfx
+docfx Docs/docfx.json --serve
+
+

DocFX writes the generated site to Docs/_site.

diff --git a/Docs/_site/index.json b/Docs/_site/index.json index c834f71..b9afbd7 100644 --- a/Docs/_site/index.json +++ b/Docs/_site/index.json @@ -182,16 +182,16 @@ "getting-started.html": { "href": "getting-started.html", "title": "Getting Started | CapyKit Documentation", - "summary": "Getting Started" + "summary": "Getting Started This guide shows the common setup and first-use patterns for consuming CapyKit from a .NET 8 project. Install Add CapyKit to your project from NuGet: dotnet add package CapyKit If you are working from a local checkout instead, reference the project directly: dotnet add reference ../CapyKit/CapyKit.csproj Add Namespaces Most APIs live in one of three namespaces: using CapyKit; using CapyKit.Extensions; using CapyKit.Helpers; Use CapyKit for core types such as Password, Pool, and CapyEventReporter. Use CapyKit.Extensions for extension methods. Use CapyKit.Helpers for serialization, compression, security, keys, language, and calculation helpers. Work With Strings using CapyKit.Extensions; string? suppliedName = \"\"; string name = suppliedName.IfNullOrWhiteSpace(\"Guest\"); IfNullOrEmpty and IfNullOrWhiteSpace return the original value when it is usable and return your replacement value when it is not. Page And Filter Collections using CapyKit.Extensions; var activeUsers = users.Filter(user => user.Disabled); var secondPage = activeUsers.Page(pageNumber: 2, pageSize: 25); int pageCount = activeUsers.PageCount(pageSize: 25); Filter removes items that match the predicate. Page uses natural page numbering, so the first page is 1. Serialize And Compress Data using CapyKit.Helpers; var json = SerializationHelper.SerializeToString(order); var copy = SerializationHelper.Deserialize(json); var compressed = CompressionHelper.CompressToString(order); var restored = CompressionHelper.Decompress(compressed); Serialization uses System.Text.Json. Compression stores the serialized JSON payload using gzip; CompressToString returns a Base64 representation for easier storage or transport. Hash And Verify Passwords using CapyKit; using CapyKit.Helpers; Password storedPassword = SecurityHelper.Pbkdf2(\"correct horse battery staple\"); bool passwordMatches = SecurityHelper.CompareHashedPassword( storedPassword, \"correct horse battery staple\", storedPassword.Salt, Password.Pbkdf2Algorithm); SecurityHelper.Pbkdf2 creates a Password with a random salt. Store the hash, salt, and algorithm information required by your application, then compare future password attempts using the same salt and algorithm. Generate Random Values using CapyKit.Helpers; string token = SecurityHelper.GetRandomString(32); string password = SecurityHelper.GetRandomPassword( 20, ValidCharacterCollection.Lowercase, ValidCharacterCollection.Uppercase, ValidCharacterCollection.Numbers, ValidCharacterCollection.Special); Random string and password generation use .NET cryptographic random number generation. Create And Validate Keys using System.Text; using CapyKit.Helpers; var keyHelper = new KeyHelper(); keyHelper.SetMasterKeyAccessor(() => Encoding.UTF8.GetBytes(\"replace-with-your-master-key\")); keyHelper.SetSaltSizeAccessor(() => 8); keyHelper.SetNumPartsAccessor(() => 4); string key = keyHelper.GenerateKey(); bool valid = keyHelper.ValidateKey(key); KeyHelper uses an application-provided master key to sign generated key material. Keep the master key secret and stable for keys that must remain valid over time. Subscribe To CapyKit Events using CapyKit; CapyEventReporter.Subscribe( e => Console.WriteLine($\"[{e.Level}] {e.MethodName}: {e.Message}\"), EventLevel.Warning); CapyKit does not require a logging framework. Subscribe to events and forward them to whatever logging or telemetry system your application already uses. Browse The API For the full list of namespaces, types, overloads, and member signatures, open the generated API Reference." }, "index.html": { "href": "index.html", - "title": "This is the HOMEPAGE. | CapyKit Documentation", - "summary": "This is the HOMEPAGE. Refer to Markdown for how to write markdown files. Quick Start Notes: Add images to the images folder if the file is referencing an image." + "title": "CapyKit Documentation | CapyKit Documentation", + "summary": "CapyKit Documentation CapyKit is a small .NET utility library for the code you end up writing repeatedly: collection helpers, string and enum extensions, JSON serialization, gzip compression, password hashing, random token generation, simple key validation, distance calculations, and lightweight event reporting. The library targets .NET 8 and keeps its public surface intentionally direct. Most features are static helpers or extension methods, so consuming projects can adopt one piece at a time without taking on a framework or application model. Start Here Introduction explains what CapyKit includes and how the namespaces are organized. Getting Started shows installation, imports, and common usage examples. API Reference contains the generated DocFX reference for every public type and member. Common Tasks Work with strings and collections Use CapyKit.Extensions for small quality-of-life helpers such as null fallback values, pagination, inverted filtering, left outer joins, enum display names, and property copying. using CapyKit.Extensions; var displayName = user.Name.IfNullOrWhiteSpace(\"Guest\"); var page = users.Page(pageNumber: 2, pageSize: 25); Serialize, compress, and restore values Use CapyKit.Helpers.SerializationHelper and CapyKit.Helpers.CompressionHelper when you need straightforward JSON serialization or gzip compression around serializable values. using CapyKit.Helpers; var payload = SerializationHelper.SerializeToString(order); var compressed = CompressionHelper.CompressToString(order); var restored = CompressionHelper.Decompress(compressed); Hash passwords and generate tokens Use SecurityHelper for PBKDF2 password hashes, salts, and random values backed by .NET cryptographic random number generation. using CapyKit; using CapyKit.Helpers; Password password = SecurityHelper.Pbkdf2(\"correct horse battery staple\"); bool matches = SecurityHelper.CompareHashedPassword( password, \"correct horse battery staple\", password.Salt, Password.Pbkdf2Algorithm); Listen to CapyKit events CapyKit reports warnings and errors through CapyEventReporter instead of choosing a logging framework for you. Subscribe at the level your application cares about and route events into your own logging pipeline. using CapyKit; CapyEventReporter.Subscribe( e => logger.LogWarning(\"{Method}: {Message}\", e.MethodName, e.Message), EventLevel.Warning); Build The Docs Locally The documentation is generated with DocFX from the Markdown files in this folder and the XML comments in the CapyKit project. dotnet tool install -g docfx docfx Docs/docfx.json --serve DocFX writes the generated site to Docs/_site." }, "introduction.html": { "href": "introduction.html", "title": "Introduction | CapyKit Documentation", - "summary": "Introduction" + "summary": "Introduction CapyKit is a practical toolkit for .NET applications. It collects common helpers and extension methods into one package so application code can stay focused on business behavior instead of re-implementing the same plumbing in every project. The project began as shared infrastructure for HappyCapy and is now available as a standalone library. It currently targets .NET 8. What CapyKit Provides Extension Methods The CapyKit.Extensions namespace contains helpers for common language and LINQ tasks: StringExtensions provides fallback helpers such as IfNullOrEmpty and IfNullOrWhiteSpace. LINQExtensions adds pagination, page counts, inverted filtering, and left outer join helpers for enumerable and queryable collections. EnumerationExtensions makes enum names, numeric values, descriptions, and human-readable names easier to retrieve. ObjectExtensions copies matching writable properties from one object to another. Helper Classes The CapyKit.Helpers namespace contains focused utility classes: SerializationHelper serializes and deserializes values with System.Text.Json. CompressionHelper compresses serialized values with gzip and can represent compressed data as Base64. SecurityHelper creates PBKDF2 password hashes, salts, random strings, and random passwords. KeyHelper creates and validates formatted HMAC-backed keys using a caller-provided master key. CalculationHelper includes distance calculations, unit conversion, angle conversion, and quick non-cryptographic hash helpers. LanguageHelper converts camel case identifiers into human-readable text. Core Utility Types The root CapyKit namespace includes small types that support the helpers: Password, IPasswordAlgorithm, and Pbkdf2Algorithm model password hashing. Pool and PoolItem provide a simple resource pool abstraction. PropertyComparer compares objects by a selected property. CapyEventReporter, CapyEventArgs, and EventLevel expose library diagnostics without requiring a specific logging package. NamedColor provides a large named color enumeration based on the XKCD color survey palette. Design Approach CapyKit favors explicit, discoverable APIs. Most helpers are static methods or extension methods and can be adopted independently. You can use only the namespaces you need, and the library does not impose dependency injection, hosting, logging, or configuration conventions on the consuming application. Where CapyKit needs to communicate warnings or errors internally, it uses CapyEventReporter. Applications can subscribe to these events and map them into their preferred logging, telemetry, or diagnostics system. API Reference The generated API reference is available through the DocFX navigation and starts at API Reference. Use it for exact signatures, overloads, return types, exceptions, and XML comment details." } } \ No newline at end of file diff --git a/Docs/_site/introduction.html b/Docs/_site/introduction.html index 4181363..dd0bd49 100644 --- a/Docs/_site/introduction.html +++ b/Docs/_site/introduction.html @@ -73,6 +73,41 @@

Introduction

+

CapyKit is a practical toolkit for .NET applications. It collects common helpers and extension methods into one package so application code can stay focused on business behavior instead of re-implementing the same plumbing in every project.

+

The project began as shared infrastructure for HappyCapy and is now available as a standalone library. It currently targets .NET 8.

+

What CapyKit Provides

+

Extension Methods

+

The CapyKit.Extensions namespace contains helpers for common language and LINQ tasks:

+
    +
  • StringExtensions provides fallback helpers such as IfNullOrEmpty and IfNullOrWhiteSpace.
    • +
  • LINQExtensions adds pagination, page counts, inverted filtering, and left outer join helpers for enumerable and queryable collections.
    • +
  • EnumerationExtensions makes enum names, numeric values, descriptions, and human-readable names easier to retrieve.
    • +
  • ObjectExtensions copies matching writable properties from one object to another.
    • +
+

Helper Classes

+

The CapyKit.Helpers namespace contains focused utility classes:

+
    +
  • SerializationHelper serializes and deserializes values with System.Text.Json.
    • +
  • CompressionHelper compresses serialized values with gzip and can represent compressed data as Base64.
    • +
  • SecurityHelper creates PBKDF2 password hashes, salts, random strings, and random passwords.
    • +
  • KeyHelper creates and validates formatted HMAC-backed keys using a caller-provided master key.
    • +
  • CalculationHelper includes distance calculations, unit conversion, angle conversion, and quick non-cryptographic hash helpers.
    • +
  • LanguageHelper converts camel case identifiers into human-readable text.
    • +
+

Core Utility Types

+

The root CapyKit namespace includes small types that support the helpers:

+
    +
  • Password, IPasswordAlgorithm, and Pbkdf2Algorithm model password hashing.
    • +
  • Pool<T> and PoolItem<T> provide a simple resource pool abstraction.
    • +
  • PropertyComparer<T, U> compares objects by a selected property.
    • +
  • CapyEventReporter, CapyEventArgs, and EventLevel expose library diagnostics without requiring a specific logging package.
    • +
  • NamedColor provides a large named color enumeration based on the XKCD color survey palette.
    • +
+

Design Approach

+

CapyKit favors explicit, discoverable APIs. Most helpers are static methods or extension methods and can be adopted independently. You can use only the namespaces you need, and the library does not impose dependency injection, hosting, logging, or configuration conventions on the consuming application.

+

Where CapyKit needs to communicate warnings or errors internally, it uses CapyEventReporter. Applications can subscribe to these events and map them into their preferred logging, telemetry, or diagnostics system.

+

API Reference

+

The generated API reference is available through the DocFX navigation and starts at API Reference. Use it for exact signatures, overloads, return types, exceptions, and XML comment details.

diff --git a/Docs/_site/toc.html b/Docs/_site/toc.html index 52ec442..e4ddde1 100644 --- a/Docs/_site/toc.html +++ b/Docs/_site/toc.html @@ -18,6 +18,141 @@
  • Getting Started
    • +
  • + + API Reference + + +
    • diff --git a/Docs/_site/toc.json b/Docs/_site/toc.json index 2ca7b19..f58945e 100644 --- a/Docs/_site/toc.json +++ b/Docs/_site/toc.json @@ -1,2 +1,2 @@ -{"items":[{"name":"Introduction","href":"introduction.html","topicHref":"introduction.html"},{"name":"Getting Started","href":"getting-started.html","topicHref":"getting-started.html"}],"pdf":false} +{"items":[{"name":"Introduction","href":"introduction.html","topicHref":"introduction.html"},{"name":"Getting Started","href":"getting-started.html","topicHref":"getting-started.html"},{"name":"API Reference","includedFrom":"~/api/toc.yml","items":[{"name":"CapyKit","href":"api/CapyKit.html","topicHref":"api/CapyKit.html","topicUid":"CapyKit","type":"Namespace","items":[{"name":"CapyEventArgs","href":"api/CapyKit.CapyEventArgs.html","topicHref":"api/CapyKit.CapyEventArgs.html","topicUid":"CapyKit.CapyEventArgs","type":"Class"},{"name":"CapyEventHandler","href":"api/CapyKit.CapyEventHandler.html","topicHref":"api/CapyKit.CapyEventHandler.html","topicUid":"CapyKit.CapyEventHandler","type":"Delegate"},{"name":"CapyEventReporter","href":"api/CapyKit.CapyEventReporter.html","topicHref":"api/CapyKit.CapyEventReporter.html","topicUid":"CapyKit.CapyEventReporter","type":"Class"},{"name":"Color","href":"api/CapyKit.Color.html","topicHref":"api/CapyKit.Color.html","topicUid":"CapyKit.Color","type":"Class"},{"name":"EncryptedValue","href":"api/CapyKit.EncryptedValue-1.html","topicHref":"api/CapyKit.EncryptedValue-1.html","topicUid":"CapyKit.EncryptedValue`1","type":"Class"},{"name":"EventLevel","href":"api/CapyKit.EventLevel.html","topicHref":"api/CapyKit.EventLevel.html","topicUid":"CapyKit.EventLevel","type":"Enum"},{"name":"IPasswordAlgorithm","href":"api/CapyKit.IPasswordAlgorithm.html","topicHref":"api/CapyKit.IPasswordAlgorithm.html","topicUid":"CapyKit.IPasswordAlgorithm","type":"Interface"},{"name":"NamedColor","href":"api/CapyKit.NamedColor.html","topicHref":"api/CapyKit.NamedColor.html","topicUid":"CapyKit.NamedColor","type":"Enum"},{"name":"Password","href":"api/CapyKit.Password.html","topicHref":"api/CapyKit.Password.html","topicUid":"CapyKit.Password","type":"Class"},{"name":"Pbkdf2Algorithm","href":"api/CapyKit.Pbkdf2Algorithm.html","topicHref":"api/CapyKit.Pbkdf2Algorithm.html","topicUid":"CapyKit.Pbkdf2Algorithm","type":"Class"},{"name":"PoolItem","href":"api/CapyKit.PoolItem-1.html","topicHref":"api/CapyKit.PoolItem-1.html","topicUid":"CapyKit.PoolItem`1","type":"Class"},{"name":"Pool","href":"api/CapyKit.Pool-1.html","topicHref":"api/CapyKit.Pool-1.html","topicUid":"CapyKit.Pool`1","type":"Class"},{"name":"PropertyComparer","href":"api/CapyKit.PropertyComparer-2.html","topicHref":"api/CapyKit.PropertyComparer-2.html","topicUid":"CapyKit.PropertyComparer`2","type":"Class"}]},{"name":"CapyKit.Attributes","href":"api/CapyKit.Attributes.html","topicHref":"api/CapyKit.Attributes.html","topicUid":"CapyKit.Attributes","type":"Namespace","items":[{"name":"EnumerationAttribute","href":"api/CapyKit.Attributes.EnumerationAttribute-1.html","topicHref":"api/CapyKit.Attributes.EnumerationAttribute-1.html","topicUid":"CapyKit.Attributes.EnumerationAttribute`1","type":"Class"},{"name":"EnumerationDescriptionAttribute","href":"api/CapyKit.Attributes.EnumerationDescriptionAttribute.html","topicHref":"api/CapyKit.Attributes.EnumerationDescriptionAttribute.html","topicUid":"CapyKit.Attributes.EnumerationDescriptionAttribute","type":"Class"},{"name":"ValueFormatAttribute","href":"api/CapyKit.Attributes.ValueFormatAttribute.html","topicHref":"api/CapyKit.Attributes.ValueFormatAttribute.html","topicUid":"CapyKit.Attributes.ValueFormatAttribute","type":"Class"}]},{"name":"CapyKit.Enumerations","href":"api/CapyKit.Enumerations.html","topicHref":"api/CapyKit.Enumerations.html","topicUid":"CapyKit.Enumerations","type":"Namespace","items":[{"name":"MeasurementSystem","href":"api/CapyKit.Enumerations.MeasurementSystem.html","topicHref":"api/CapyKit.Enumerations.MeasurementSystem.html","topicUid":"CapyKit.Enumerations.MeasurementSystem","type":"Enum"}]},{"name":"CapyKit.Extensions","href":"api/CapyKit.Extensions.html","topicHref":"api/CapyKit.Extensions.html","topicUid":"CapyKit.Extensions","type":"Namespace","items":[{"name":"EnumerationExtensions","href":"api/CapyKit.Extensions.EnumerationExtensions.html","topicHref":"api/CapyKit.Extensions.EnumerationExtensions.html","topicUid":"CapyKit.Extensions.EnumerationExtensions","type":"Class"},{"name":"LINQExtensions","href":"api/CapyKit.Extensions.LINQExtensions.html","topicHref":"api/CapyKit.Extensions.LINQExtensions.html","topicUid":"CapyKit.Extensions.LINQExtensions","type":"Class"},{"name":"ObjectExtensions","href":"api/CapyKit.Extensions.ObjectExtensions.html","topicHref":"api/CapyKit.Extensions.ObjectExtensions.html","topicUid":"CapyKit.Extensions.ObjectExtensions","type":"Class"},{"name":"StringExtensions","href":"api/CapyKit.Extensions.StringExtensions.html","topicHref":"api/CapyKit.Extensions.StringExtensions.html","topicUid":"CapyKit.Extensions.StringExtensions","type":"Class"}]},{"name":"CapyKit.Helpers","href":"api/CapyKit.Helpers.html","topicHref":"api/CapyKit.Helpers.html","topicUid":"CapyKit.Helpers","type":"Namespace","items":[{"name":"CalculationHelper","href":"api/CapyKit.Helpers.CalculationHelper.html","topicHref":"api/CapyKit.Helpers.CalculationHelper.html","topicUid":"CapyKit.Helpers.CalculationHelper","type":"Class"},{"name":"CompressionHelper","href":"api/CapyKit.Helpers.CompressionHelper.html","topicHref":"api/CapyKit.Helpers.CompressionHelper.html","topicUid":"CapyKit.Helpers.CompressionHelper","type":"Class"},{"name":"EncryptionHelper","href":"api/CapyKit.Helpers.EncryptionHelper.html","topicHref":"api/CapyKit.Helpers.EncryptionHelper.html","topicUid":"CapyKit.Helpers.EncryptionHelper","type":"Class"},{"name":"IEncryptionAlgorithm","href":"api/CapyKit.Helpers.IEncryptionAlgorithm.html","topicHref":"api/CapyKit.Helpers.IEncryptionAlgorithm.html","topicUid":"CapyKit.Helpers.IEncryptionAlgorithm","type":"Interface"},{"name":"KeyHelper","href":"api/CapyKit.Helpers.KeyHelper.html","topicHref":"api/CapyKit.Helpers.KeyHelper.html","topicUid":"CapyKit.Helpers.KeyHelper","type":"Class"},{"name":"LanguageHelper","href":"api/CapyKit.Helpers.LanguageHelper.html","topicHref":"api/CapyKit.Helpers.LanguageHelper.html","topicUid":"CapyKit.Helpers.LanguageHelper","type":"Class"},{"name":"SecurityHelper","href":"api/CapyKit.Helpers.SecurityHelper.html","topicHref":"api/CapyKit.Helpers.SecurityHelper.html","topicUid":"CapyKit.Helpers.SecurityHelper","type":"Class"},{"name":"SerializationHelper","href":"api/CapyKit.Helpers.SerializationHelper.html","topicHref":"api/CapyKit.Helpers.SerializationHelper.html","topicUid":"CapyKit.Helpers.SerializationHelper","type":"Class"},{"name":"SettingsHelper","href":"api/CapyKit.Helpers.SettingsHelper.html","topicHref":"api/CapyKit.Helpers.SettingsHelper.html","topicUid":"CapyKit.Helpers.SettingsHelper","type":"Class"},{"name":"ValidCharacterCollection","href":"api/CapyKit.Helpers.ValidCharacterCollection.html","topicHref":"api/CapyKit.Helpers.ValidCharacterCollection.html","topicUid":"CapyKit.Helpers.ValidCharacterCollection","type":"Enum"}]}]}],"pdf":false} diff --git a/Docs/getting-started.md b/Docs/getting-started.md index 8b3a794..8b6ab0c 100644 --- a/Docs/getting-started.md +++ b/Docs/getting-started.md @@ -1 +1,132 @@ -# Getting Started \ No newline at end of file +# Getting Started + +This guide shows the common setup and first-use patterns for consuming CapyKit from a .NET 8 project. + +## Install + +Add CapyKit to your project from NuGet: + +```bash +dotnet add package CapyKit +``` + +If you are working from a local checkout instead, reference the project directly: + +```bash +dotnet add reference ../CapyKit/CapyKit.csproj +``` + +## Add Namespaces + +Most APIs live in one of three namespaces: + +```csharp +using CapyKit; +using CapyKit.Extensions; +using CapyKit.Helpers; +``` + +Use `CapyKit` for core types such as `Password`, `Pool`, and `CapyEventReporter`. Use `CapyKit.Extensions` for extension methods. Use `CapyKit.Helpers` for serialization, compression, security, keys, language, and calculation helpers. + +## Work With Strings + +```csharp +using CapyKit.Extensions; + +string? suppliedName = ""; +string name = suppliedName.IfNullOrWhiteSpace("Guest"); +``` + +`IfNullOrEmpty` and `IfNullOrWhiteSpace` return the original value when it is usable and return your replacement value when it is not. + +## Page And Filter Collections + +```csharp +using CapyKit.Extensions; + +var activeUsers = users.Filter(user => user.Disabled); +var secondPage = activeUsers.Page(pageNumber: 2, pageSize: 25); +int pageCount = activeUsers.PageCount(pageSize: 25); +``` + +`Filter` removes items that match the predicate. `Page` uses natural page numbering, so the first page is `1`. + +## Serialize And Compress Data + +```csharp +using CapyKit.Helpers; + +var json = SerializationHelper.SerializeToString(order); +var copy = SerializationHelper.Deserialize(json); + +var compressed = CompressionHelper.CompressToString(order); +var restored = CompressionHelper.Decompress(compressed); +``` + +Serialization uses `System.Text.Json`. Compression stores the serialized JSON payload using gzip; `CompressToString` returns a Base64 representation for easier storage or transport. + +## Hash And Verify Passwords + +```csharp +using CapyKit; +using CapyKit.Helpers; + +Password storedPassword = SecurityHelper.Pbkdf2("correct horse battery staple"); + +bool passwordMatches = SecurityHelper.CompareHashedPassword( + storedPassword, + "correct horse battery staple", + storedPassword.Salt, + Password.Pbkdf2Algorithm); +``` + +`SecurityHelper.Pbkdf2` creates a `Password` with a random salt. Store the hash, salt, and algorithm information required by your application, then compare future password attempts using the same salt and algorithm. + +## Generate Random Values + +```csharp +using CapyKit.Helpers; + +string token = SecurityHelper.GetRandomString(32); +string password = SecurityHelper.GetRandomPassword( + 20, + ValidCharacterCollection.Lowercase, + ValidCharacterCollection.Uppercase, + ValidCharacterCollection.Numbers, + ValidCharacterCollection.Special); +``` + +Random string and password generation use .NET cryptographic random number generation. + +## Create And Validate Keys + +```csharp +using System.Text; +using CapyKit.Helpers; + +var keyHelper = new KeyHelper(); +keyHelper.SetMasterKeyAccessor(() => Encoding.UTF8.GetBytes("replace-with-your-master-key")); +keyHelper.SetSaltSizeAccessor(() => 8); +keyHelper.SetNumPartsAccessor(() => 4); + +string key = keyHelper.GenerateKey(); +bool valid = keyHelper.ValidateKey(key); +``` + +`KeyHelper` uses an application-provided master key to sign generated key material. Keep the master key secret and stable for keys that must remain valid over time. + +## Subscribe To CapyKit Events + +```csharp +using CapyKit; + +CapyEventReporter.Subscribe( + e => Console.WriteLine($"[{e.Level}] {e.MethodName}: {e.Message}"), + EventLevel.Warning); +``` + +CapyKit does not require a logging framework. Subscribe to events and forward them to whatever logging or telemetry system your application already uses. + +## Browse The API + +For the full list of namespaces, types, overloads, and member signatures, open the generated [API Reference](api/toc.yml). diff --git a/Docs/index.md b/Docs/index.md index 6023cdd..95cace9 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -1,11 +1,79 @@ ---- -_layout: landing ---- - -# This is the **HOMEPAGE**. - -Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files. - -## Quick Start Notes: - -1. Add images to the *images* folder if the file is referencing an image. \ No newline at end of file +--- +_layout: landing +--- + +# CapyKit Documentation + +CapyKit is a small .NET utility library for the code you end up writing repeatedly: collection helpers, string and enum extensions, JSON serialization, gzip compression, password hashing, random token generation, simple key validation, distance calculations, and lightweight event reporting. + +The library targets .NET 8 and keeps its public surface intentionally direct. Most features are static helpers or extension methods, so consuming projects can adopt one piece at a time without taking on a framework or application model. + +## Start Here + +- [Introduction](introduction.md) explains what CapyKit includes and how the namespaces are organized. +- [Getting Started](getting-started.md) shows installation, imports, and common usage examples. +- [API Reference](api/toc.yml) contains the generated DocFX reference for every public type and member. + +## Common Tasks + +### Work with strings and collections + +Use `CapyKit.Extensions` for small quality-of-life helpers such as null fallback values, pagination, inverted filtering, left outer joins, enum display names, and property copying. + +```csharp +using CapyKit.Extensions; + +var displayName = user.Name.IfNullOrWhiteSpace("Guest"); +var page = users.Page(pageNumber: 2, pageSize: 25); +``` + +### Serialize, compress, and restore values + +Use `CapyKit.Helpers.SerializationHelper` and `CapyKit.Helpers.CompressionHelper` when you need straightforward JSON serialization or gzip compression around serializable values. + +```csharp +using CapyKit.Helpers; + +var payload = SerializationHelper.SerializeToString(order); +var compressed = CompressionHelper.CompressToString(order); +var restored = CompressionHelper.Decompress(compressed); +``` + +### Hash passwords and generate tokens + +Use `SecurityHelper` for PBKDF2 password hashes, salts, and random values backed by .NET cryptographic random number generation. + +```csharp +using CapyKit; +using CapyKit.Helpers; + +Password password = SecurityHelper.Pbkdf2("correct horse battery staple"); +bool matches = SecurityHelper.CompareHashedPassword( + password, + "correct horse battery staple", + password.Salt, + Password.Pbkdf2Algorithm); +``` + +### Listen to CapyKit events + +CapyKit reports warnings and errors through `CapyEventReporter` instead of choosing a logging framework for you. Subscribe at the level your application cares about and route events into your own logging pipeline. + +```csharp +using CapyKit; + +CapyEventReporter.Subscribe( + e => logger.LogWarning("{Method}: {Message}", e.MethodName, e.Message), + EventLevel.Warning); +``` + +## Build The Docs Locally + +The documentation is generated with DocFX from the Markdown files in this folder and the XML comments in the `CapyKit` project. + +```bash +dotnet tool install -g docfx +docfx Docs/docfx.json --serve +``` + +DocFX writes the generated site to `Docs/_site`. diff --git a/Docs/introduction.md b/Docs/introduction.md index f6ecaa6..9b1cf72 100644 --- a/Docs/introduction.md +++ b/Docs/introduction.md @@ -1 +1,47 @@ -# Introduction \ No newline at end of file +# Introduction + +CapyKit is a practical toolkit for .NET applications. It collects common helpers and extension methods into one package so application code can stay focused on business behavior instead of re-implementing the same plumbing in every project. + +The project began as shared infrastructure for HappyCapy and is now available as a standalone library. It currently targets .NET 8. + +## What CapyKit Provides + +### Extension Methods + +The `CapyKit.Extensions` namespace contains helpers for common language and LINQ tasks: + +- `StringExtensions` provides fallback helpers such as `IfNullOrEmpty` and `IfNullOrWhiteSpace`. +- `LINQExtensions` adds pagination, page counts, inverted filtering, and left outer join helpers for enumerable and queryable collections. +- `EnumerationExtensions` makes enum names, numeric values, descriptions, and human-readable names easier to retrieve. +- `ObjectExtensions` copies matching writable properties from one object to another. + +### Helper Classes + +The `CapyKit.Helpers` namespace contains focused utility classes: + +- `SerializationHelper` serializes and deserializes values with `System.Text.Json`. +- `CompressionHelper` compresses serialized values with gzip and can represent compressed data as Base64. +- `SecurityHelper` creates PBKDF2 password hashes, salts, random strings, and random passwords. +- `KeyHelper` creates and validates formatted HMAC-backed keys using a caller-provided master key. +- `CalculationHelper` includes distance calculations, unit conversion, angle conversion, and quick non-cryptographic hash helpers. +- `LanguageHelper` converts camel case identifiers into human-readable text. + +### Core Utility Types + +The root `CapyKit` namespace includes small types that support the helpers: + +- `Password`, `IPasswordAlgorithm`, and `Pbkdf2Algorithm` model password hashing. +- `Pool` and `PoolItem` provide a simple resource pool abstraction. +- `PropertyComparer` compares objects by a selected property. +- `CapyEventReporter`, `CapyEventArgs`, and `EventLevel` expose library diagnostics without requiring a specific logging package. +- `NamedColor` provides a large named color enumeration based on the XKCD color survey palette. + +## Design Approach + +CapyKit favors explicit, discoverable APIs. Most helpers are static methods or extension methods and can be adopted independently. You can use only the namespaces you need, and the library does not impose dependency injection, hosting, logging, or configuration conventions on the consuming application. + +Where CapyKit needs to communicate warnings or errors internally, it uses `CapyEventReporter`. Applications can subscribe to these events and map them into their preferred logging, telemetry, or diagnostics system. + +## API Reference + +The generated API reference is available through the DocFX navigation and starts at [API Reference](api/toc.yml). Use it for exact signatures, overloads, return types, exceptions, and XML comment details. diff --git a/Docs/toc.yml b/Docs/toc.yml index d3663b9..099d393 100644 --- a/Docs/toc.yml +++ b/Docs/toc.yml @@ -1,4 +1,6 @@ -- name: Introduction - href: introduction.md -- name: Getting Started - href: getting-started.md \ No newline at end of file +- name: Introduction + href: introduction.md +- name: Getting Started + href: getting-started.md +- name: API Reference + href: api/toc.yml diff --git a/README.md b/README.md index 42e3fad..4326fea 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,67 @@ # CapyKit -A versatile collection of C# utilities and extensions designed to supercharge any .NET project. Born from the HappyCapy project, now open for the community. + +CapyKit is a practical .NET utility library for the small pieces of application code that tend to get rewritten from project to project. It includes focused helpers for strings, collections, serialization, compression, password hashing, random value generation, key validation, calculations, resource pooling, and lightweight library diagnostics. + +The project started as shared infrastructure for HappyCapy and is now packaged as a standalone toolkit for .NET 8 applications. + +## What Is Included + +- Extension methods for strings, enums, objects, and LINQ collections. +- JSON serialization and gzip compression helpers. +- PBKDF2 password hashing, salt generation, and random token/password generation. +- HMAC-backed formatted key generation and validation. +- Distance, unit conversion, angle conversion, and quick hash helpers. +- A simple resource pool abstraction. +- `CapyEventReporter` for routing CapyKit warnings and errors into your own logging system. +- A generated DocFX API reference for the public surface area. + +## Install + +```bash +dotnet add package CapyKit +``` + +For local development from this repository: + +```bash +dotnet add reference ./CapyKit/CapyKit.csproj +``` + +## Quick Example + +```csharp +using CapyKit; +using CapyKit.Extensions; +using CapyKit.Helpers; + +var name = incomingName.IfNullOrWhiteSpace("Guest"); +var page = users.Page(pageNumber: 1, pageSize: 25); + +Password password = SecurityHelper.Pbkdf2("correct horse battery staple"); +bool matches = SecurityHelper.CompareHashedPassword( + password, + "correct horse battery staple", + password.Salt, + Password.Pbkdf2Algorithm); +``` ## Documentation -You can find an early version of the automatically generated documentation [here](./Documentation/Help/Home.md). +The in-repository documentation starts at [Docs/index.md](Docs/index.md). It includes an introduction, getting-started guide, and links into the generated DocFX API reference. -## TODO +To build and serve the documentation locally: -Obviously this repository is in pretty rough shape right now while I make the full transition from the private repository to this one. Please bear with me. :) +```bash +dotnet tool install -g docfx +docfx Docs/docfx.json --serve +``` + +DocFX writes the generated site to `Docs/_site`. + +## Project Status + +CapyKit is a growing utility library. Some APIs are mature and covered by tests, while others are still being rounded out as the project transitions from private shared code into a public package. Review the generated API reference and tests when adopting a helper in production code. + +## License + +This project is licensed under the terms in [LICENSE](LICENSE).