Skip to content

Commit fc6d5f3

Browse files
ns-vasilevns-vasilev
committed
Update README.md 
1 parent a2dc270 commit fc6d5f3

2 files changed

Lines changed: 268 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 268 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,268 @@
1-
# validator
1+
![Validator: xxxxx](https://raw.githubusercontent.com/space-code/validator/dev/Resources/validator.png)
2+
3+
<h1 align="center" style="margin-top: 0px;">validator</h1>
4+
5+
<p align="center">
6+
<a href="https://github.com/space-code/validator/blob/main/LICENSE"><img alt="Liscence" src="https://img.shields.io/cocoapods/l/service-core.svg?style=flat"></a>
7+
<a href="https://developer.apple.com/"><img alt="Platform" src="https://img.shields.io/badge/platform-ios%20%7C%20osx%20%7C%20watchos%20%7C%20tvos-%23989898"/></a>
8+
<a href="https://developer.apple.com/swift"><img alt="Swift5.5" src="https://img.shields.io/badge/language-Swift5.7-orange.svg"/></a>
9+
<a href="https://github.com/space-code/validator"><img alt="CI" src="https://github.com/space-code/validator/actions/workflows/ci.yml/badge.svg?branch=main"></a>
10+
<a href="https://github.com/apple/swift-package-manager" alt="Validator on Swift Package Manager" title="Validator on Swift Package Manager"><img src="https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg" /></a>
11+
</p>
12+
13+
## Description
14+
Validator is a framework written in Swift that provides functions that can be used to validate the contents of an input value.
15+
16+
- [Usage](#usage)
17+
- [Validation Rules](#validation-rules)
18+
- [Custom Validation Rules](#custom-validation-rules)
19+
- [Requirements](#requirements)
20+
- [Installation](#installation)
21+
- [Communication](#communication)
22+
- [Contributing](#contributing)
23+
- [Author](#author)
24+
- [License](#license)
25+
26+
## Usage
27+
28+
The package contains two libraries: `ValidatorCore` encompasses all validation logic and predefined validators, while `ValidatorUI` implements extensions for integrating the validator into UI objects. It supports both `SwiftUI` and `UIKit`.
29+
30+
### Basic usage
31+
32+
If you need to validate some data, you can use the `Validator` object for this purpose as follows:
33+
34+
```swift
35+
import ValidatorCore
36+
37+
let validator = Validator()
38+
let result = validator.validate(input: "text", rule: LengthValidationRule(min: 4, error: "error text"))
39+
40+
switch result {
41+
case .valid:
42+
print("text is valid")
43+
case let .invalid(errors):
44+
// handle validation errors
45+
print(errors)
46+
}
47+
```
48+
49+
### UIKit
50+
51+
If you want to validate a user's input data, you can import `ValidatorUI` and integrate validation logic into UI components. Your UI object must conform to `IUIValidatable` prototocol that requires to define an `inputValue` and `validateOnInputChange(_:)` method.
52+
53+
`ValidatorUI` supports an extension for convenient integration of the validator into `UITextField` objects:
54+
55+
```swift
56+
import UIKit
57+
import ValidatorUI
58+
import ValidatorCore
59+
60+
class ViewController: UIViewController {
61+
62+
let textField: UITextField = UITextField()
63+
64+
override func viewDidLoad() {
65+
super.viewDidLoad()
66+
67+
/// Adds validation rule to the text field.
68+
textField.add(rule: LengthValidationRule(max: 10, error: "error text"))
69+
/// Enables automatic validation on input change.
70+
textField.validateOnInputChange(isEnabled: true)
71+
/// Handels validation result.
72+
textField.validationHandler = { result in
73+
switch result {
74+
case .valid:
75+
print("text is valid")
76+
case let .invalid(errors):
77+
print(errors)
78+
}
79+
}
80+
}
81+
82+
/// Setup UITextField ...
83+
}
84+
```
85+
86+
### SwiftUI
87+
88+
If you need to validate a single field, you can use the validation view extension and handle the validation result in a validation handler:
89+
90+
```swift
91+
import SwiftUI
92+
import ValidatorUI
93+
import ValidatorCore
94+
95+
struct ContentView: View {
96+
@State private var text: String = ""
97+
98+
private let validationRules: [any IValidationRule<String>] = [
99+
LengthValidationRule(max: 10, error: "Text error")
100+
]
101+
102+
var body: some View {
103+
VStack {
104+
TextField("Text", text: $text)
105+
.validation($text, rules: validationRules) { result in
106+
// Handle a validation result here
107+
}
108+
}
109+
}
110+
}
111+
```
112+
113+
You can also use a view modifier where you can pass an error view:
114+
115+
```swift
116+
import SwiftUI
117+
import ValidatorUI
118+
import ValidatorCore
119+
120+
struct ContentView: View {
121+
@State private var text: String = ""
122+
123+
private let validationRules: [any IValidationRule<String>] = [
124+
LengthValidationRule(max: 10, error: "Text error")
125+
]
126+
127+
var body: some View {
128+
VStack {
129+
TextField("Text", text: $text)
130+
.validate(item: $text, rules: validationRules) { errors in
131+
Text("Text is bigger than 10 characters")
132+
}
133+
}
134+
}
135+
}
136+
```
137+
138+
### SwiftUI Forms
139+
140+
`ValidatorUI` supports form validation. If your screen contains a number of input fields and you want to handle validation results in one place, you can use a validation form manager as follows:
141+
142+
```swift
143+
import SwiftUI
144+
import ValidatorUI
145+
import ValidatorCore
146+
147+
class Form: ObservableObject {
148+
@Published
149+
var manager = FormFieldManager()
150+
151+
@FormField(rules: [LengthValidationRule(max: 20, error: "The first name is very long")])
152+
var firstName: String = ""
153+
154+
@FormField(rules: [LengthValidationRule(min: 5, error: "The last name is too short")])
155+
var lastName: String = ""
156+
157+
lazy var firstNameValidationContainer = _firstName.validate(manager: manager)
158+
lazy var lastNameValidationContainer = _lastName.validate(manager: manager)
159+
}
160+
161+
struct ContentView: View {
162+
@ObservedObject private var form = Form()
163+
164+
var body: some View {
165+
VStack {
166+
TextField("First Name", text: $form.firstName)
167+
.validate(validationContainer: form.firstNameValidationContainer) { errors in
168+
Text(errors.map { $0.message }.joined(separator: " "))
169+
}
170+
TextField("Last Name", text: $form.lastName)
171+
.validate(validationContainer: form.lastNameValidationContainer) { errors in
172+
Text(errors.map { $0.message }.joined(separator: " "))
173+
}
174+
Button(action: { self.form.manager.validate() }, label: { Text("Validate") })
175+
176+
Spacer()
177+
}
178+
.onReceive(
179+
form.manager.$isValid,
180+
perform: { value in
181+
if value {
182+
print("The form's fields are valid")
183+
} else {
184+
print("The form's fileds aren't valid")
185+
}
186+
}
187+
)
188+
}
189+
}
190+
```
191+
192+
## Validation Rules
193+
194+
| **Validator** | **Description** |
195+
|----------------------------|-------------------------------------------------------------------------------------|
196+
| **LengthValidationRule** | To validate whether a string is matching a specific length |
197+
| **NonEmptyValidationRule** | To validate whether a string is empty or blank |
198+
| **PrefixValidationRule** | To validate whether a string contains a prefix |
199+
| **SuffixValidationRule** | To validate whether a string contains a suffix |
200+
| **RegexValidationRule** | To validate if a pattern is matched |
201+
202+
## Custom Validation Rules
203+
204+
To implement a custom validation rule, you can conform to the `IValidationRule` protocol, which requires defining a validation type and implementing validation logic. For example:
205+
206+
```swift
207+
/// A non empty validation rule.
208+
public struct NonEmptyValidationRule: IValidationRule {
209+
// MARK: Types
210+
211+
public typealias Input = String
212+
213+
// MARK: Properties
214+
215+
/// The validation error.
216+
public let error: IValidationError
217+
218+
// MARK: Initialization
219+
220+
public init(error: IValidationError) {
221+
self.error = error
222+
}
223+
224+
// MARK: IValidationRule
225+
226+
public func validate(input: String) -> Bool {
227+
!input.isEmpty
228+
}
229+
}
230+
```
231+
232+
## Requirements
233+
- iOS 16.0+ / macOS 13+ / tvOS 16.0+ / watchOS 9.0+
234+
- Xcode 14.0
235+
- Swift 5.7
236+
237+
## Installation
238+
### Swift Package Manager
239+
240+
The [Swift Package Manager](https://swift.org/package-manager/) is a tool for automating the distribution of Swift code and is integrated into the `swift` compiler. It is in early development, but `validator` does support its use on supported platforms.
241+
242+
Once you have your Swift package set up, adding `validator` as a dependency is as easy as adding it to the `dependencies` value of your `Package.swift`.
243+
244+
```swift
245+
dependencies: [
246+
.package(url: "https://github.com/space-code/validator.git", .upToNextMajor(from: "1.0.0"))
247+
]
248+
```
249+
250+
## Communication
251+
- If you **found a bug**, open an issue.
252+
- If you **have a feature request**, open an issue.
253+
- If you **want to contribute**, submit a pull request.
254+
255+
## Contributing
256+
Bootstrapping development environment
257+
258+
```
259+
make bootstrap
260+
```
261+
262+
Please feel free to help out with this project! If you see something that could be made better or want a new feature, open up an issue or send a Pull Request!
263+
264+
## Author
265+
Nikita Vasilev, nv3212@gmail.com
266+
267+
## License
268+
validator is available under the MIT license. See the LICENSE file for more info.

‎Resources/validator.png‎

278 KB
Loading

0 commit comments

Comments
 (0)