Simplify/align macro overloads

.gitignore

@@ -1,5 +1,5 @@
 .DS_Store
-/.build
+.build
 /build
 /.swiftpm
 /Packages

Sources/Vexil/Flag.swift

@@ -11,54 +11,6 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Creates a flag with the specified configuration.
-///
-/// All Flags must be initialised with a default value and a description.
-/// The default value is used when none of the sources on the `FlagPole`
-/// have a value specified for this flag. The description is used for future
-/// developer reference and in Vexlliographer to describe the flag.
-///
-/// The type that you wrap with `@Flag` must conform to `FlagValue`.
-///
-/// You can access flag details and observe flag value changes using a peer
-/// property prefixed with `$`.
-///
-/// ```swift
-/// @Flag(default: false, description: "My magical flag")
-/// var magicFlag: Bool
-///
-/// // Subscribe to flag updates
-/// for try await magic in $magicFlag {
-///     // Do magic thing
-/// }
-///
-/// // Also works with Combine
-/// $magicFlag
-///     .sink { magic in
-///         // Do magic thing
-///     }
-/// ```
-///
-/// - Parameters:
-///   - name:               An optional display name to give the flag. Only visible in flag editors like Vexillographer.
-///                         Default is to calculate one based on the property name.
-///   - keyStrategy:        An optional strategy to use when calculating the key name. The default is to use the `FlagPole`s strategy.
-///   - default:            The default value for this `Flag` should no sources have it set.
-///   - description:        A description of this flag. Used in flag editors like Vexillographer,
-///                         and also for future developer context.
-///   - display:            How the flag should be displayed in Vexillographer. Defaults to `.default`,
-///                         you can set it to `.hidden` to hide the flag.
-///
-@attached(accessor)
-@attached(peer, names: prefixed(`$`))
-public macro Flag<Value: FlagValue>(
-    name: StaticString? = nil,
-    keyStrategy: VexilConfiguration.FlagKeyStrategy = .default,
-    default initialValue: Value,
-    description: StaticString,
-    display: FlagDisplayOption = .default
-) = #externalMacro(module: "VexilMacros", type: "FlagMacro")
-
 /// Creates a flag with the specified configuration.
 ///
 /// All Flags must be initialised via the property and include a description.

Sources/Vexil/Group.swift

@@ -11,6 +11,90 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// Creates a FlagGroup with the given parameters.
+///
+/// All FlagGroup's must have at least a `description` which is used for future developer
+/// reference and within Vexillographer, our generated flag management UI.
+///
+/// Attach this to a property within a `@FlagContainer`. The property's type must also
+/// be a `FlagContainer`.
+///
+/// ```swift
+/// @FlagContainer
+/// struct MyFlags {
+///     @FlagGroup("These flags are displayed inside a `NavigationLink` (this is the default)", display: .navigation)
+///     var navigation: NavigationFlags
+///
+///     @FlagGroup("These flags are displayed as a `Section`", display: .section)
+///     var section: SectionedFlags
+/// }
+///
+/// @FlagContainer
+/// struct NavigationFlags {
+///     @Flag("First Flag")
+///     var first = false
+/// }
+///
+/// @FlagContainer
+/// struct SectionedFlags {
+///     @Flag("Second Flag")
+///     var second = false
+/// }
+/// ```
+///
+/// - Parameters:
+///   - description:        A description of this flag group. Used in flag editors like Vexillographer, and also for future developer context.
+///   - display:            How the flag should be displayed in Vexillographer. Defaults to `.navigation` which wraps it in a
+///                         `NavigationLink`. Other options include `.section` to wrap it in a `Section` and `.hidden`
+///                         to hide it from Vexillographer entirely.
+///
+@attached(accessor)
+@attached(peer, names: prefixed(`$`))
+public macro FlagGroup(
+    _ description: StaticString,
+    display: FlagGroupDisplayOption = .navigation
+) = #externalMacro(module: "VexilMacros", type: "FlagGroupMacro")
+
+/// Creates a FlagGroup with the given parameters.
+///
+/// All FlagGroup's must have at least a `description` which is used for future developer
+/// reference and within Vexillographer, our generated flag management UI.
+///
+/// Attach this to a property within a `@FlagContainer`. The property's type must also
+/// be a `FlagContainer`.
+///
+/// ```swift
+/// @FlagContainer
+/// struct MyFlags {
+///     @FlagGroup(name: "Navigation Flags", description: "These flags are displayed inside a `NavigationLink` (this is the default)", display: .navigation)
+///     var navigation: NavigationFlags
+///
+///     @FlagGroup(name: "Section Flags", description: "These flags are displayed as a `Section`", display: .section)
+///     var section: SectionedFlags
+/// }
+///
+/// @FlagContainer
+/// struct NavigationFlags {
+///     @Flag("First Flag")
+///     var first = false
+/// }
+///
+/// @FlagContainer
+/// struct SectionedFlags {
+///     @Flag("Second Flag")
+///     var second = false
+/// }
+/// ```
+///
+/// - Parameters:
+///   - name:               An optional display name to give the flag group. Only visible in flag editors like Vexillographer.
+///                         Default is to calculate one based on the property name.
+///   - keyStrategy:        An optional strategy to use when calculating the key name. The default is to use the `FlagPole`s strategy.
+///   - description:        A description of this flag group. Used in flag editors like Vexillographer, and also for future developer context.
+///   - display:            How the flag should be displayed in Vexillographer. Defaults to `.navigation` which wraps it in a
+///                         `NavigationLink`. Other options include `.section` to wrap it in a `Section` and `.hidden`
+///                         to hide it from Vexillographer entirely.
+///
 @attached(accessor)
 @attached(peer, names: prefixed(`$`))
 public macro FlagGroup(

Sources/Vexil/Vexil.docc/DefiningFlags.md

@@ -69,14 +69,14 @@ import Vexil
 
 struct NormalFlags: FlagContainer {
 
-    @Flag(default: 10, "This is a demonstration Int flag")
-    var myIntFlag: Int
+    @Flag("This is a demonstration Int flag")
+    var myIntFlag = 10
 
-    @Flag(default: 0.5, "This is a demonstration Double flag")
-    var myDoubleFlag: Double
+    @Flag("This is a demonstration Double flag")
+    var myDoubleFlag = 0.5
 
-    @Flag(default: "Placeholder", "This is a demonstration String flag")
-    var myStringFlag: String
+    @Flag("This is a demonstration String flag")
+    var myStringFlag = "Placeholder""
 
 }
 ```
@@ -98,8 +98,8 @@ enum MyTheme: String, FlagValue, CaseIterable {
 
 struct ThemeFlags {
 
-    @Flag(default: .blue, "The theme to use for the app")
-    var currentTheme: MyTheme
+    @Flag("The theme to use for the app")
+    var currentTheme = MyTheme.blue
     
 }
 ```
@@ -117,8 +117,8 @@ struct MyStruct: FlagValue, Codable {
 
 struct TestFlags: FlagContainer {
 
-    @Flag(defaultValue: MyStruct(property1: "abc123", property2: 123, property3: "🤯"), description: "...")
-    var testFlag: MyStruct
+    @Flag(description: "...")
+    var testFlag = MyStruct(property1: "abc123", property2: 123, property3: "🤯")
     
 }
 ```

Sources/Vexil/Vexil.docc/FlagKeys.md

@@ -73,8 +73,8 @@ print(flagPole.subgroup.secondSubgroup.$myAwesomeFlag.key)
 Sometimes though you want to override how a specific flag calculates its key. Vexil allows you to pass in a ``Flag/CodingKeyStrategy`` when you declare your ``Flag`` to alter how its key is calculated:
 
 ```swift
-@Flag(codingKeyStrategy: .snakecase, default: false, description: "My Awesome Flag")
-var myAwesomeFlag: Bool
+@Flag(codingKeyStrategy: .snakecase, description: "My Awesome Flag")
+var myAwesomeFlag = false
 
 // Key is "subgroup.second-subgroup.my_awesome_flag"
 ```
@@ -86,8 +86,8 @@ That would leave `myAwesomeFlag` calculating its key as `"subgroup.second-subgro
 You can also go for a manually specified key instead of a calculated one using a ``Flag/CodingKeyStrategy`` of `.customKey("my-key")`:
 
 ```swift
-@Flag(codingKeyStrategy: .customKey("my-key"), default: false, description: "My Awesome Flag")
-var myAwesomeFlag: Bool
+@Flag(codingKeyStrategy: .customKey("my-key"), description: "My Awesome Flag")
+var myAwesomeFlag = false
 
 // Key is "subgroup.second-subgroup.my-key"
 ```
@@ -97,8 +97,8 @@ var myAwesomeFlag: Bool
 But sometimes your ``FlagValueSource`` doesn't play nice, or the people naming flags in the backend don't provide the same structure that you want your local flags to be in. You can instead set a manual key path. In this case the ``FlagPole`` will ignore the location of the ``Flag`` in the flag structure and will just use the key you specify.
 
 ```swift
-@Flag(codingKeyStrategy: .customKeyPath("my-key"), default: false, description: "My Awesome Flag")
-var myAwesomeFlag: Bool
+@Flag(codingKeyStrategy: .customKeyPath("my-key"), description: "My Awesome Flag")
+var myAwesomeFlag = false
 
 // Key is "my-key"
 ```
@@ -110,7 +110,7 @@ While a ``FlagGroup`` doesn't have an explicit key of its own, it does form part
 ```swift
 struct MyFlags: FlagContainer {
 
-    @FlagGroup(description: "A subgroup of flags")
+    @FlagGroup("A subgroup of flags")
     var subgroup: Subgroup
 
 }

Sources/Vexil/Vexil.docc/Migration2-3.md

@@ -57,10 +57,10 @@ struct MyFlags: FlagContainer {
 @FlagContainer
 struct MyFlags {
 
-    @Flag(default: false, description: "Test flag that does something magical")
-    var testFlag: Bool
+    @Flag("Test flag that does something magical")
+    var testFlag = false
 
-    @FlagGroup(description: "Some nested flags")
+    @FlagGroup("Some nested flags")
     var nested: NestedFlags
 
 }
@@ -117,12 +117,19 @@ FlagContainer.init(
 Under Vexil 3, this is now a macro:
 
 ```swift
+// Full macro
 public macro FlagGroup(
     name: StaticString? = nil,
     keyStrategy: VexilConfiguration.GroupKeyStrategy = .default,
     description: StaticString,
     display: VexilDisplayOption = .navigation
 )
+
+// Or shorter
+public macro FlagGroup(
+    _ description: StaticString,
+    display: VexilDisplayOption = .navigation
+)
 ```
 
 As you can see the changes here purely for simplification: `codingKeyStrategy`
@@ -136,14 +143,14 @@ could set your description to `.hidden`; now you pass `.hidden` to display:
 var nested: NestedFlags
 
 // Vexil 3
-@FlagGroup(description: "Nested flags", display: .hidden)
+@FlagGroup("Nested flags", display: .hidden)
 var nested: NestedFlags
 ```
 
 ### Flags
 
 Much like Flag Groups, the `@Flag` property wrapper was replaced with the
-``Flag(name:keyStrategy:default:description:)`` macro, with simplified parameters:
+``Flag(name:keyStrategy:description:display:)`` macro, with simplified parameters:
 
 ```swift
 // Vexil 2
@@ -156,9 +163,6 @@ var magic = false
 
 // Vexil 3
 
-@Flag(default: false, description: "Flag that enables magic")
-var magic: Bool
-
 @Flag("Flag that enables magic")
 var magic = false
 ```
@@ -184,18 +188,9 @@ init(
 )
 ```
 
-Both approaches are available via the `@Flag` macro:
+With the `@Flag` macro we now require the property initialiser.
 
 ```swift
-/// Explicit default parameter
-macro Flag<Value: FlagValue>(
-    name: StaticString? = nil,
-    keyStrategy: VexilConfiguration.FlagKeyStrategy = .default,
-    default initialValue: Value,
-    description: StaticString,
-    display: FlagDisplayOption = .default
-)
-
 /// Sets default via property initialiser
 macro Flag(
     name: StaticString? = nil,
@@ -211,6 +206,19 @@ macro Flag(_ description: StaticString)
 Same as with the `FlagGroup`, the `codingKeyStrategy` parameter has been shortened
 to `keyStrategy`, and the ability to hide flags has been moved to the `display` property.
 
+>Note:
+>
+>The `default:` parameter option was removed as it included a large foot-gun with cryptic
+>error message. It was decided to remove this potential issue by aligning with
+>[swift-argument-parser](https://github.com/apple/swift-argument-parser)'s approach.
+>
+>As the macro is type-checked without reference to the attached property's type you get errors like:
+>
+>```swift
+>@Flag(default: .enumCase, description: "")             // compiler error: Type of `.enumCase` cannot be inferred.
+>var myFlag: MyEnum
+>```
+
 ## Flag Pole Observation
 
 Under Vexil 2, every time a `FlagValueSource` reported a flag value change, we would

Sources/Vexil/Vexil.docc/Vexil.md

@@ -148,14 +148,14 @@ let snapshot = flagPole.snapshot()
 ### Flags
 
 - <doc:DefiningFlags>
-- ``Flag(name:keyStrategy:default:description:display:)``
 - ``Flag(name:keyStrategy:description:display:)``
 - ``Flag(_:)``
 - ``FlagValue``
 
 ### Flag Groups
 
 - ``FlagGroup(name:keyStrategy:description:display:)``
+- ``FlagGroup(_:display:)``
 - ``FlagContainer(generateEquatable:)``
 
 ### Snapshots

Sources/VexilMacros/FlagContainerMacro.swift

@@ -18,7 +18,7 @@
 
 public enum FlagContainerMacro {}
 
 extension FlagContainerMacro: MemberMacro {
 
     public static func expansion(
         of node: AttributeSyntax,
@@ -170,7 +170,7 @@
                                         ])
                                     }
                                 }
-                                ExprSyntax("lhs.\(lastBinding) == rhs.\(lastBinding)")
+                                ExprSyntax("lhs.\(lastBinding.trimmed) == rhs.\(lastBinding.trimmed)")
                             }
                         }
                         .with(\.modifiers, Array(scopes) + [ DeclModifierSyntax(name: .keyword(.static)) ])

Sources/VexilMacros/FlagGroupMacro.swift

@@ -56,7 +56,7 @@ public struct FlagGroupMacro {
         self.scopes = property.modifiers.scopeSyntax
 
         self.name = arguments[label: "name"]?.expression
-        self.description = arguments[label: "description"]?.expression
+        self.description = arguments[label: "description"]?.expression ?? arguments[label: nil]?.expression
         self.displayOption = arguments[label: "display"]?.expression
     }