|
| 1 | +# Enum Generator: Before vs After SyntaxKit |
| 2 | + |
| 3 | +This example demonstrates the power of SyntaxKit for dynamic Swift code generation by showing a real-world scenario where enum maintenance becomes automated. |
| 4 | + |
| 5 | +## Scenario: API Configuration Management |
| 6 | + |
| 7 | +Imagine you're building an iOS app that needs to manage API endpoints. As your API evolves, you need to keep your Swift enums in sync with the server configuration. |
| 8 | + |
| 9 | +## The Problem: Manual Enum Maintenance |
| 10 | + |
| 11 | +### Before SyntaxKit (Manual Approach) |
| 12 | + |
| 13 | +**Step 1**: Your backend team updates the API configuration in `api-config.json`: |
| 14 | +```json |
| 15 | +{ |
| 16 | + "endpoints": { |
| 17 | + "users": "/api/v2/users", |
| 18 | + "posts": "/api/v2/posts", |
| 19 | + "comments": "/api/v2/comments", |
| 20 | + "userProfile": "/api/v2/users/{id}", |
| 21 | + "analytics": "/api/v2/analytics" |
| 22 | + }, |
| 23 | + "statusCodes": { |
| 24 | + "success": 200, |
| 25 | + "created": 201, |
| 26 | + "badRequest": 400, |
| 27 | + "unauthorized": 401, |
| 28 | + "forbidden": 403, |
| 29 | + "notFound": 404, |
| 30 | + "internalError": 500, |
| 31 | + "serviceUnavailable": 503 |
| 32 | + } |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +**Step 2**: You manually update your Swift enums: |
| 37 | +```swift |
| 38 | +// APIEndpoint.swift - Updated manually ❌ |
| 39 | +public enum APIEndpoint: String, CaseIterable { |
| 40 | + case users = "/api/v2/users" |
| 41 | + case posts = "/api/v2/posts" |
| 42 | + case comments = "/api/v2/comments" |
| 43 | + case userProfile = "/api/v2/users/{id}" |
| 44 | + case analytics = "/api/v2/analytics" // ← Added manually |
| 45 | +} |
| 46 | + |
| 47 | +// HTTPStatus.swift - Updated manually ❌ |
| 48 | +public enum HTTPStatus: Int, CaseIterable { |
| 49 | + case success = 200 |
| 50 | + case created = 201 |
| 51 | + case badRequest = 400 |
| 52 | + case unauthorized = 401 |
| 53 | + case forbidden = 403 |
| 54 | + case notFound = 404 |
| 55 | + case internalError = 500 |
| 56 | + case serviceUnavailable = 503 // ← Added manually |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +**Problems with this approach:** |
| 61 | +- ❌ Manual process prone to human error |
| 62 | +- ❌ Easy to forget updating Swift code when API changes |
| 63 | +- ❌ No validation that Swift enums match server configuration |
| 64 | +- ❌ Time-consuming for large APIs with many endpoints |
| 65 | +- ❌ Version drift between backend config and iOS enums |
| 66 | + |
| 67 | +## The Solution: Automated Generation with SyntaxKit |
| 68 | + |
| 69 | +### After SyntaxKit (Automated Approach) |
| 70 | + |
| 71 | +**Step 1**: Same API configuration update in `api-config.json` ✅ |
| 72 | + |
| 73 | +**Step 2**: Run the automated generator: |
| 74 | +```bash |
| 75 | +swift run enum-generator api-config.json Sources/Generated/ |
| 76 | +``` |
| 77 | + |
| 78 | +**Step 3**: Perfect Swift enums generated automatically: |
| 79 | +```swift |
| 80 | +// Generated/APIEndpoints.swift - Generated automatically ✅ |
| 81 | +/// API endpoints for the application |
| 82 | +/// |
| 83 | +/// Use this enum to ensure type-safe API endpoint references |
| 84 | +public enum APIEndpoint: String, CaseIterable { |
| 85 | + case users = "/api/v2/users" |
| 86 | + case posts = "/api/v2/posts" |
| 87 | + case comments = "/api/v2/comments" |
| 88 | + case userProfile = "/api/v2/users/{id}" |
| 89 | + case analytics = "/api/v2/analytics" // ← Added automatically |
| 90 | +} |
| 91 | + |
| 92 | +// Generated/HTTPStatus.swift - Generated automatically ✅ |
| 93 | +/// HTTP status codes for API responses |
| 94 | +public enum HTTPStatus: Int, CaseIterable { |
| 95 | + case success = 200 |
| 96 | + case created = 201 |
| 97 | + case badRequest = 400 |
| 98 | + case unauthorized = 401 |
| 99 | + case forbidden = 403 |
| 100 | + case notFound = 404 |
| 101 | + case internalError = 500 |
| 102 | + case serviceUnavailable = 503 // ← Added automatically |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +**Benefits of this approach:** |
| 107 | +- ✅ Zero manual Swift code updates needed |
| 108 | +- ✅ Guaranteed synchronization with backend configuration |
| 109 | +- ✅ Automatic validation and error detection |
| 110 | +- ✅ Scales to hundreds of endpoints effortlessly |
| 111 | +- ✅ No version drift possible |
| 112 | +- ✅ Can be integrated into CI/CD pipeline |
| 113 | + |
| 114 | +## Files in This Example |
| 115 | + |
| 116 | +- `before/` - Manual approach with prone-to-error maintenance |
| 117 | +- `after/` - SyntaxKit-powered automated generation |
| 118 | +- `api-config.json` - Example API configuration |
| 119 | +- `dsl.swift` - SyntaxKit generator implementation |
| 120 | +- `main.swift` - CLI tool for running the generator |
| 121 | +- `generate.swift` - Generation helper script |
| 122 | + |
| 123 | +## Run the Example |
| 124 | + |
| 125 | +```bash |
| 126 | +# Generate enums from configuration |
| 127 | +swift run enum-generator-example |
| 128 | + |
| 129 | +# See the generated code |
| 130 | +cat code.swift |
| 131 | +``` |
| 132 | + |
| 133 | +This demonstrates how SyntaxKit transforms tedious, error-prone manual processes into reliable, automated code generation. |
0 commit comments