Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
DnV1eX authored Nov 26, 2024
1 parent 2954796 commit 22cf345
Showing 1 changed file with 17 additions and 5 deletions.
22 changes: 17 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# EnumRawValues
**@EnumRawValues** is a Swift attached extension macro to add raw values for enums. Built-in support for [raw values](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/enumerations/#Raw-Values) in Swift enums is limited by a string, integer, or floating-point literals. New macros functionality made it possible to achieve a similar level of expressiveness and compile-time safety while removing restrictions on the type and assignment of raw values.
The **EnumRawValues** is a Swift attached extension macro to add raw values for enums.

Built-in support for [raw values](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/enumerations/#Raw-Values) in Swift enums is limited by a string, integer, or floating-point literals. New macros functionality made it possible to achieve a similar level of expressiveness and compile-time safety while removing restrictions on the type and assignment of raw values.

## Macro Features
- Support for any equatable raw value types.
Expand All @@ -8,6 +10,13 @@
- Performs integrity checks.
- Automatically transfers existing raw values to macro arguments (including implicitly assigned raw values! 😎).

## Installation
To add the package to your Xcode project, open `File -> Add Package Dependencies...` and search for the URL:
```
https://github.com/DnV1eX/EnumRawValues.git
```
Then, simply **import EnumRawValues** and add the **@EnumRawValues** attribute before the target enum.

## Usage Examples
1. Assigning raw values using constants, expressions, functions, and more:
```Swift
Expand Down Expand Up @@ -35,9 +44,12 @@ enum Rocket: String {
case newGlenn = { "New Glenn" }() // Closures (currently causing build crash)
}
```
To use EnumRawValues, simply import the module, add the @EnumRawValues attribute, and then click the Fix button to convert raw values into macro arguments:
Add the **@EnumRawValues** attribute before the *Rocket* enum, and then click the `Fix` button to convert raw values into macro arguments:

<img width="499" alt="Fix enum pop-up" src="https://github.com/user-attachments/assets/d514cada-7773-4bfe-8e5f-f8e1556d80e5">
<img width="499" alt="Fix enum pop-up" align="right" src="https://github.com/user-attachments/assets/d514cada-7773-4bfe-8e5f-f8e1556d80e5">
<br>
<br>
<br>

```Swift
import EnumRawValues
Expand Down Expand Up @@ -94,11 +106,11 @@ extension TISInputSource {

## Notes on Usage
- Explicit type annotation is requied and can be specified either in the macro attribute generic clause (preferable) or as the enum type. In the latter case make sure the first item in the enum’s type inheritance list is a Type conforming to `ExpressibleByStringLiteral`, `ExpressibleByIntegerLiteral` or `ExpressibleByFloatLiteral` protocol, and macro arguments are of this type.
- Like the built-in implementaton, `EnumRawValues` is currently not compatible with [Associated Values](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/enumerations#Associated-Values). The support can be added in future with default initializers and nil for optional associated values, feel free to submit the feature request with your use case.
- Like the built-in implementaton, **EnumRawValues** is currently not compatible with [Associated Values](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/enumerations#Associated-Values). The support can be added in future with default initializers and nil for optional associated values, feel free to submit the feature request with your use case.
- Raw value uniqueness is checked in compile time by the switch flow control that displays warnings (grey ones in generated code). Keep in mind that they can be bypassed, for example, by specifying different constants with the same values.

## Implementation
Under the hood the `EnumRawValues` macro adds the enum extension with [RawRepresentable](https://developer.apple.com/documentation/swift/rawrepresentable) protocol conformance using the macro attribute arguments as enum case raw values in the order of declaration. There are also multiple format checks and syntax fix suggestions. The macro code is covered with unit tests.
Under the hood the **EnumRawValues** macro adds the enum extension with [RawRepresentable](https://developer.apple.com/documentation/swift/rawrepresentable) protocol conformance using the macro attribute arguments as enum case raw values in the order of declaration. There are also multiple format checks and syntax fix suggestions. The macro code is covered with unit tests.

## License
Copyright © 2024 DnV1eX. All rights reserved. Licensed under the Apache License, Version 2.0.

0 comments on commit 22cf345

Please sign in to comment.