Skip to content

Commit 4e19ee5

Browse files
committed
docs: Distinguished better between input handlers and validators
1 parent 03d9a01 commit 4e19ee5

45 files changed

Lines changed: 440 additions & 457 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

README.md

Lines changed: 18 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
99
[![.NET](https://img.shields.io/badge/.NET-9.0%20%7C%2010.0-512BD4)](https://dotnet.microsoft.com)
1010

11-
A fluent, type-safe user input validation library for .NET with platform-specific implementations for Console, WinForms, WPF, Avalonia, MAUI, and Blazor.
11+
A fluent, type-safe user input handler and validation library for .NET with platform-specific implementations for Console, WinForms, WPF, Avalonia, MAUI, and Blazor.
1212

1313
</div>
1414

@@ -31,10 +31,10 @@ A fluent, type-safe user input validation library for .NET with platform-specifi
3131

3232
## 🚀 Features
3333

34-
- **Type-Safe Validation** - Built-in validators for all common C# types
35-
- **Composable Rules** - Chain validation rules fluently, similar to LINQ
34+
- **Type-Safe Validation** - Built-in input handlers + validators for all common C# types
35+
- **Composable Rules** - Chain validation rules, similarly to LINQ
3636
- **Async Support** - Full async/await support with cancellation tokens
37-
- **Extensible** - Add custom validators and rules with ease
37+
- **Extensible** - Add custom handlers and rules with ease
3838
- **Multi-Platform** - Dedicated implementations for Console, WinForms, WPF, Avalonia, MAUI, and Blazor
3939

4040
---
@@ -88,12 +88,10 @@ dotnet add reference path/to/TypeGuard.Console/TypeGuard.Console.csproj # or yo
8888
```csharp
8989
using TypeGuard.Console;
9090

91-
// Simple integer input
92-
int age = await Guard.Int("Enter your age")
91+
int age = Guard.Int("Enter your age")
9392
.WithRange(1, 120)
9493
.GetAsync();
9594

96-
// String with validation rules
9795
string name = await Guard.String("Enter your name")
9896
.WithNoDigits()
9997
.WithLengthRange(2, 50)
@@ -124,28 +122,23 @@ private async void submitButton_Click(object sender, EventArgs e)
124122

125123
## 📚 Usage Guide
126124

127-
### Simple Validation
125+
### Simple Input Handling
128126

129127
```csharp
130-
// Integer
131128
int count = await Guard.Int("How many items?").GetAsync();
132129

133-
// String
134130
string username = await Guard.String("Enter username").GetAsync();
135131

136-
// DateTime
137132
DateTime date = await Guard.DateTime("Enter a date", "dd/MM/yyyy").GetAsync();
138133
```
139134

140-
### Validation with Rules
135+
### Adding Rules
141136

142137
```csharp
143-
// Age: must be between 18 and 120
144138
int age = await Guard.Int("Enter your age")
145139
.WithRange(18, 120)
146140
.GetAsync();
147141

148-
// Username: 3–20 characters, letters only
149142
string username = await Guard.String("Choose a username")
150143
.WithLengthRange(3, 20)
151144
.WithNoDigits()
@@ -155,7 +148,6 @@ string username = await Guard.String("Choose a username")
155148
### Custom Validation Rules
156149

157150
```csharp
158-
// Password strength
159151
string password = await Guard.String("Create a password")
160152
.WithLengthRange(8, null)
161153
.WithRegex(@"[A-Z]", "Must contain at least one uppercase letter")
@@ -167,22 +159,19 @@ string password = await Guard.String("Create a password")
167159
.GetAsync();
168160
```
169161

170-
### DateTime Validation
162+
### DateTime Handling
171163

172164
```csharp
173-
// Strict format
174165
DateTime appointment = await Guard.DateTime("Enter appointment date", "dd/MM/yyyy")
175166
.WithRange(DateTime.Today, DateTime.Today.AddMonths(6))
176167
.GetAsync();
177168

178-
// Flexible parsing
179169
DateTime birthday = await Guard.DateTime("Enter birthday")
180170
.WithCustomRule(
181171
d => DateTime.Today.Year - d.Year >= 18,
182172
"Must be 18 or older")
183173
.GetAsync();
184174

185-
// Weekdays only
186175
DateTime meeting = await Guard.DateTime("Select meeting date", "yyyy-MM-dd")
187176
.WithWeekday()
188177
.GetAsync();
@@ -308,9 +297,9 @@ int age = await _guard.Int("Enter your age")
308297
## 🏗️ Architecture
309298

310299
```
311-
TypeGuard.Core → Platform-agnostic validation logic
300+
TypeGuard.Core → Platform-agnostic logic
312301
├── Abstractions → Interfaces
313-
├── Validators → Type-specific validators
302+
├── Handlers → Type-specific handlers
314303
├── Rules → Validation rules
315304
└── Builders → Fluent API builders
316305
@@ -320,8 +309,8 @@ TypeGuard.Console → Console implementation
320309
└── Guard → Main entry point
321310
322311
TypeGuard.Winforms → WinForms implementation (TextBox, TextBlock)
323-
├── WinformsInput → Reads from Control.Text
324-
├── WinformsOutput → Writes prompts and errors
312+
├── WinformsInput → Reads from Control.Text
313+
├── WinformsOutput → Writes prompts and errors
325314
└── Guard → Main entry point
326315
327316
TypeGuard.Wpf → WPF implementation (TextBox, TextBlock)
@@ -330,8 +319,8 @@ TypeGuard.Wpf → WPF implementation (TextBox, TextBlock)
330319
└── Guard → Main entry point
331320
332321
TypeGuard.Avalonia → Avalonia implementation (TextBox, TextBlock)
333-
├── AvaloniaInput → Reads from Textbox.Text
334-
├── AvaloniaOutput → Writes prompts and errors
322+
├── AvaloniaInput → Reads from Textbox.Text
323+
├── AvaloniaOutput → Writes prompts and errors
335324
└── Guard → Main entry point
336325
337326
TypeGuard.Maui → MAUI implementation (Entry, Label, Button)
@@ -354,15 +343,14 @@ TypeGuard.Blazor → Blazor implementation (InputText, DI-injected Gu
354343
```csharp
355344
using TypeGuard.Core.Interfaces;
356345

357-
public class EmailRule : IValidationRule<string>
346+
public class EmailRule : IHandlingRule<string>
358347
{
359348
public bool IsValid(string value) =>
360349
value.Contains('@') && value.Contains('.');
361350

362351
public string ErrorMessage => "Must be a valid email address";
363352
}
364-
365-
// Usage
353+
366354
string email = await Guard.String("Enter email")
367355
.WithCustomRule(new EmailRule())
368356
.GetAsync();
@@ -375,7 +363,7 @@ string email = await Guard.String("Enter email")
375363
## 💻 Requirements
376364

377365
- .NET 9.0 or .NET 10.0
378-
- Windows, macOS, or Linux (platform packages may have OS restrictions)
366+
- Windows, macOS, or Linux (certain packages may have OS restrictions)
379367

380368
---
381369

@@ -392,4 +380,4 @@ Contributions are welcome! You can:
392380
- Report bugs or request features via [Issues](https://github.com/DoubledDoge/TypeGuard/issues)
393381
- Submit pull requests
394382
- Suggest improvements to the API
395-
- Add new type validators/builders/rules
383+
- Adding new type handlers/builders/rules

src/TypeGuard.Avalonia/Guard.cs

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -50,113 +50,113 @@ public class Guard(TextBox inputTextBox, TextBlock promptBlock, TextBlock errorB
5050
private readonly AvaloniaOutput _output = new(promptBlock, errorBlock);
5151

5252
/// <summary>
53-
/// Creates a builder for validated <see cref="int"/> input.
53+
/// Creates a builder for handling <see cref="int"/> input.
5454
/// </summary>
5555
/// <param name="prompt">The prompt message to display to the user.</param>
5656
public IntegerInputBuilder<int> Int(string prompt) => new(prompt, _input, _output);
5757

5858
/// <summary>
59-
/// Creates a builder for validated <see cref="double"/> input.
59+
/// Creates a builder for handling <see cref="double"/> input.
6060
/// </summary>
6161
/// <param name="prompt">The prompt message to display to the user.</param>
6262
public NumericInputBuilder<double> Double(string prompt) => new(prompt, _input, _output);
6363

6464
/// <summary>
65-
/// Creates a builder for validated <see cref="decimal"/> input.
65+
/// Creates a builder for handling <see cref="decimal"/> input.
6666
/// </summary>
6767
/// <param name="prompt">The prompt message to display to the user.</param>
6868
public NumericInputBuilder<decimal> Decimal(string prompt) => new(prompt, _input, _output);
6969

7070
/// <summary>
71-
/// Creates a builder for validated numeric input of any type that implements
71+
/// Creates a builder for handling numeric input of any type that implements
7272
/// <see cref="INumber{TSelf}"/> and <see cref="IMinMaxValue{TSelf}"/>.
7373
/// Use this for less common numeric types such as <see cref="float"/>, <see cref="long"/>,
7474
/// <see cref="byte"/>, <see cref="Half"/>, and so on.
7575
/// </summary>
76-
/// <typeparam name="T">The numeric type to validate.</typeparam>
76+
/// <typeparam name="T">The numeric type to handle.</typeparam>
7777
/// <param name="prompt">The prompt message to display to the user.</param>
7878
public NumericInputBuilder<T> Numeric<T>(string prompt)
7979
where T : INumber<T>, IMinMaxValue<T> => new(prompt, _input, _output);
8080

8181
/// <summary>
82-
/// Creates a builder for validated integer input of any type that implements
82+
/// Creates a builder for handlinginteger input of any type that implements
8383
/// <see cref="IBinaryInteger{TSelf}"/> and <see cref="IMinMaxValue{TSelf}"/>.
8484
/// Use this for less common integer types such as <see cref="long"/>, <see cref="short"/>,
8585
/// <see cref="byte"/>, and so on.
8686
/// </summary>
87-
/// <typeparam name="T">The integer type to validate.</typeparam>
87+
/// <typeparam name="T">The integer type to handle.</typeparam>
8888
/// <param name="prompt">The prompt message to display to the user.</param>
8989
public IntegerInputBuilder<T> Integer<T>(string prompt)
9090
where T : IBinaryInteger<T>, IMinMaxValue<T> => new(prompt, _input, _output);
9191

9292
/// <summary>
93-
/// Creates a builder for validated <see cref="string"/> input.
93+
/// Creates a builder for handling <see cref="string"/> input.
9494
/// </summary>
9595
/// <param name="prompt">The prompt message to display to the user.</param>
9696
public StringInputBuilder String(string prompt) => new(prompt, _input, _output);
9797

9898
/// <summary>
99-
/// Creates a builder for validated <see cref="char"/> input.
99+
/// Creates a builder for handling <see cref="char"/> input.
100100
/// </summary>
101101
/// <param name="prompt">The prompt message to display to the user.</param>
102102
public CharInputBuilder Char(string prompt) => new(prompt, _input, _output);
103103

104104
/// <summary>
105-
/// Creates a builder for validated <see cref="DateOnly"/> input.
105+
/// Creates a builder for handling <see cref="DateOnly"/> input.
106106
/// </summary>
107107
/// <param name="prompt">The prompt message to display to the user.</param>
108108
/// <param name="format">The expected date format string. If null, any valid DateOnly format is accepted.</param>
109109
public DateOnlyInputBuilder DateOnly(string prompt, string? format = null) =>
110110
new(prompt, format, _input, _output);
111111

112112
/// <summary>
113-
/// Creates a builder for validated <see cref="DateTime"/> input.
113+
/// Creates a builder for handling <see cref="DateTime"/> input.
114114
/// </summary>
115115
/// <param name="prompt">The prompt message to display to the user.</param>
116116
/// <param name="format">The expected date and time format string. If null, any valid DateTime format is accepted.</param>
117117
public DateTimeInputBuilder DateTime(string prompt, string? format = null) =>
118118
new(prompt, format, _input, _output);
119119

120120
/// <summary>
121-
/// Creates a builder for validated <see cref="TimeOnly"/> input.
121+
/// Creates a builder for handling <see cref="TimeOnly"/> input.
122122
/// </summary>
123123
/// <param name="prompt">The prompt message to display to the user.</param>
124124
/// <param name="format">The expected time format string. If null, any valid TimeOnly format is accepted.</param>
125125
public TimeOnlyInputBuilder TimeOnly(string prompt, string? format = null) =>
126126
new(prompt, format, _input, _output);
127127

128128
/// <summary>
129-
/// Creates a builder for validated <see cref="TimeSpan"/> input.
129+
/// Creates a builder for handling <see cref="TimeSpan"/> input.
130130
/// </summary>
131131
/// <param name="prompt">The prompt message to display to the user.</param>
132132
/// <param name="format">The expected time span format string. If null, any valid TimeSpan format is accepted.</param>
133133
public TimeSpanInputBuilder TimeSpan(string prompt, string? format = null) =>
134134
new(prompt, format, _input, _output);
135135

136136
/// <summary>
137-
/// Creates a builder for validated <see cref="System.Guid"/> input.
137+
/// Creates a builder for handling <see cref="System.Guid"/> input.
138138
/// </summary>
139139
/// <param name="prompt">The prompt message to display to the user.</param>
140140
public GuidInputBuilder Guid(string prompt) => new(prompt, _input, _output);
141141

142142
/// <summary>
143-
/// Creates a builder for validated <see cref="IPAddress"/> input.
143+
/// Creates a builder for handling <see cref="IPAddress"/> input.
144144
/// </summary>
145145
/// <param name="prompt">The prompt message to display to the user.</param>
146146
public IpAddressInputBuilder IpAddress(string prompt) => new(prompt, _input, _output);
147147

148148
/// <summary>
149-
/// Creates a builder for validated <see cref="Uri"/> input.
149+
/// Creates a builder for handling <see cref="Uri"/> input.
150150
/// </summary>
151151
/// <param name="prompt">The prompt message to display to the user.</param>
152152
/// <param name="uriKind">The kind of URI to accept. Defaults to <see cref="UriKind.RelativeOrAbsolute"/>.</param>
153153
public UriInputBuilder Uri(string prompt, UriKind uriKind = UriKind.RelativeOrAbsolute) =>
154154
new(prompt, uriKind, _input, _output);
155155

156156
/// <summary>
157-
/// Creates a builder for validated enum input of type <typeparamref name="TEnum"/>.
157+
/// Creates a builder for handling enum input of type <typeparamref name="TEnum"/>.
158158
/// </summary>
159-
/// <typeparam name="TEnum">The enum type to validate.</typeparam>
159+
/// <typeparam name="TEnum">The enum type to handle.</typeparam>
160160
/// <param name="prompt">The prompt message to display to the user.</param>
161161
/// <param name="ignoreCase">If true, enum name parsing is case-insensitive. Defaults to true.</param>
162162
public EnumInputBuilder<TEnum> Enum<TEnum>(string prompt, bool ignoreCase = true)

0 commit comments

Comments
 (0)