Merge branch 'main' into user/dickoff/help-search-functionality

Author: dickoff

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      swiftlang-actions:
+        patterns:
+          - "swiftlang/github-workflows/*"

.github/workflows/pull_request.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install apt dependencies
         run: sudo apt-get -qq update && sudo apt-get -qq -y install curl
@@ -25,8 +25,10 @@ jobs:
 
   tests:
     name: Test
-    uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
+    needs: [soundness, validate_format_config]
+    uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@0.0.11
     with:
+      linux_swift_versions: "[ \"6.0\", \"6.1\", \"6.2\", \"nightly-main\", \"nightly-6.3\"]"
       windows_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}]"
       enable_macos_checks: true
       macos_exclude_xcode_versions: "[{\"xcode_version\": \"16.0\"}, {\"xcode_version\": \"16.1\"}, {\"xcode_version\": \"16.2\"}]"
@@ -35,12 +37,13 @@ jobs:
 
   cmake-build:
     name: CMake Build
+    needs: [soundness, validate_format_config]
     runs-on: ubuntu-latest
     container:
       image: swift:6.0-jammy
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Install apt dependencies
         run: apt-get -qq update && apt-get -qq -y install curl ninja-build
       - name: Install CMake 3.30.2
@@ -58,6 +61,14 @@ jobs:
 
   soundness:
     name: Soundness
-    uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
+    uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.11
     with:
       shell_check_enabled: false  # bug: https://github.com/apple/swift-argument-parser/issues/703
+
+  required:
+    name: Required
+    runs-on: ubuntu-latest
+    needs: [tests, soundness, validate_format_config, cmake-build]
+    steps:
+      - name: Success
+        run: echo "All required jobs succeeded."

CHANGELOG.md

@@ -8,6 +8,51 @@ Add new items at the end of the relevant section under **Unreleased**.
 
 ---
 
+## [1.7.1] - 2026-03-20
+
+### Changes
+
+- Adds detailed documentation for providing descriptions of enum values. ([#825])
+- Adds `aliases` to the dump-help output. ([#813])
+- Improves zsh completions; prevents bash completion cleanup commands from being appended to shell history. ([#864], [#859])
+- Eliminates deprecation warnings in `Examples/math`. ([#879])
+
+### Fixes
+
+- Fixes build issues in Swift 5.7-5.9. ([#874], [#875])
+- Fixes `--help` output for nested subcommands with default subcommands. ([#866])
+- Prevents `@OptionGroup` type names from appearing in help usage strings. ([#873])
+- Fixes handling of visibility with nested option groups. ([#838])
+- Updates GitHub Actions workflows and streamlines the required checks. ([#839], [#843], [#844], [#853], [#856], [#857], [#876], [#877])
+
+The 1.7.0 release includes contributions from [bkhouri], [bob-wilson], [jglogan],
+[kphrx], [louisunlimited], [natecook1000], [rauhul], [rgoldberg], [salmanmkc],
+[stackotter], and [William-Laverty]. Thank you!
+
+## [1.7.0] - 2025-12-17
+
+### Additions
+
+- Access the state of an ancestor command using the new `@ParentCommand` property wrapper. ([#802])
+
+### Fixes
+
+- Corrects the help display for an case iterable option value type. ([#821])
+- Fixes ArgumentParser build failure for WASI (WebAssembly System Interface). ([#794])
+- Updates help text for readability in Repeat example and README. ([#787])
+- Provides an ambiguity breaker for some `ExpressibleByArgument` types. ([#841])
+- Shell completion script fixes. ([#801], [#808], [#811])
+
+### Changes
+
+- `docc`: Updates the output to present the string representation of command arguments as a wrapped text block. ([#791])
+- Uses Foundation Essentials when possible to reduce binary size on non-Darwin platforms. ([#804])
+- CMake: Suppress needlessly alarming messages. ([#628])
+
+The 1.7.0 release includes contributions from [bkhouri], [cmcgee1024], [dabrahams], [heckj], [incertum], [kkebo], [Konstantin-Krokhin], [natecook1000], [rauhul], [rgoldberg], and [tshortli]. Thank you!
+
+---
+
 ## [1.6.2] - 2025-10-01
 
 ### Fixes
@@ -966,7 +1011,9 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 
 <!-- Link references for releases -->
 
-[Unreleased]: https://github.com/apple/swift-argument-parser/compare/1.6.2...HEAD
+[Unreleased]: https://github.com/apple/swift-argument-parser/compare/1.7.1...HEAD
+[1.7.1]: https://github.com/apple/swift-argument-parser/compare/1.7.0...1.7.1
+[1.7.0]: https://github.com/apple/swift-argument-parser/compare/1.6.2...1.7.0
 [1.6.2]: https://github.com/apple/swift-argument-parser/compare/1.6.1...1.6.2
 [1.6.1]: https://github.com/apple/swift-argument-parser/compare/1.6.0...1.6.1
 [1.6.0]: https://github.com/apple/swift-argument-parser/compare/1.5.1...1.6.0
@@ -1093,6 +1140,7 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [#619]: https://github.com/apple/swift-argument-parser/pull/619
 [#621]: https://github.com/apple/swift-argument-parser/pull/621
 [#627]: https://github.com/apple/swift-argument-parser/pull/627
+[#628]: https://github.com/apple/swift-argument-parser/pull/628
 [#634]: https://github.com/apple/swift-argument-parser/pull/634
 [#636]: https://github.com/apple/swift-argument-parser/pull/636
 [#644]: https://github.com/apple/swift-argument-parser/pull/644
@@ -1158,9 +1206,36 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [#777]: https://github.com/apple/swift-argument-parser/pull/777
 [#782]: https://github.com/apple/swift-argument-parser/pull/782
 [#783]: https://github.com/apple/swift-argument-parser/pull/783
+[#787]: https://github.com/apple/swift-argument-parser/pull/787
 [#789]: https://github.com/apple/swift-argument-parser/pull/789
+[#791]: https://github.com/apple/swift-argument-parser/pull/791
 [#792]: https://github.com/apple/swift-argument-parser/pull/792
 [#794]: https://github.com/apple/swift-argument-parser/pull/794
+[#801]: https://github.com/apple/swift-argument-parser/pull/801
+[#802]: https://github.com/apple/swift-argument-parser/pull/802
+[#804]: https://github.com/apple/swift-argument-parser/pull/804
+[#808]: https://github.com/apple/swift-argument-parser/pull/808
+[#811]: https://github.com/apple/swift-argument-parser/pull/811
+[#813]: https://github.com/apple/swift-argument-parser/pull/813
+[#821]: https://github.com/apple/swift-argument-parser/pull/821
+[#825]: https://github.com/apple/swift-argument-parser/pull/825
+[#838]: https://github.com/apple/swift-argument-parser/pull/838
+[#839]: https://github.com/apple/swift-argument-parser/pull/839
+[#841]: https://github.com/apple/swift-argument-parser/pull/841
+[#843]: https://github.com/apple/swift-argument-parser/pull/843
+[#844]: https://github.com/apple/swift-argument-parser/pull/844
+[#853]: https://github.com/apple/swift-argument-parser/pull/853
+[#856]: https://github.com/apple/swift-argument-parser/pull/856
+[#857]: https://github.com/apple/swift-argument-parser/pull/857
+[#859]: https://github.com/apple/swift-argument-parser/pull/859
+[#864]: https://github.com/apple/swift-argument-parser/pull/864
+[#866]: https://github.com/apple/swift-argument-parser/pull/866
+[#873]: https://github.com/apple/swift-argument-parser/pull/873
+[#874]: https://github.com/apple/swift-argument-parser/pull/874
+[#875]: https://github.com/apple/swift-argument-parser/pull/875
+[#876]: https://github.com/apple/swift-argument-parser/pull/876
+[#877]: https://github.com/apple/swift-argument-parser/pull/877
+[#879]: https://github.com/apple/swift-argument-parser/pull/879
 
 <!-- Link references for contributors -->
 
@@ -1173,18 +1248,22 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [artemnovichkov]: https://github.com/apple/swift-argument-parser/commits?author=artemnovichkov
 [atierian]: https://github.com/apple/swift-argument-parser/commits?author=atierian
 [Austinpayne]: https://github.com/apple/swift-argument-parser/commits?author=Austinpayne
+[bkhouri]: https://github.com/apple/swift-argument-parser/commits?author=bkhouri
+[bob-wilson]: https://github.com/apple/swift-argument-parser/commits?author=bob-wilson
 [BradLarson]: https://github.com/apple/swift-argument-parser/commits?author=BradLarson
 [bripeticca]: https://github.com/apple/swift-argument-parser/commits?author=bripeticca
 [buttaface]: https://github.com/apple/swift-argument-parser/commits?author=buttaface
 [cg-soft]: https://github.com/apple/swift-argument-parser/commits?author=cg-soft
 [Chamepp]: https://github.com/apple/swift-argument-parser/commits?author=Chamepp
 [clayellis]: https://github.com/apple/swift-argument-parser/commits?author=clayellis
+[cmcgee1024]: https://github.com/apple/swift-argument-parser/commits?author=cmcgee1024
 [CodaFi]: https://github.com/apple/swift-argument-parser/commits?author=CodaFi
 [Coeur]: https://github.com/apple/swift-argument-parser/commits?author=Coeur
 [compnerd]: https://github.com/apple/swift-argument-parser/commits?author=compnerd
 [CraigSiemens]: https://github.com/apple/swift-argument-parser/commits?author=CraigSiemens
 [CypherPoet]: https://github.com/apple/swift-argument-parser/commits?author=CypherPoet
 [d-ronnqvist]: https://github.com/apple/swift-argument-parser/commits?author=d-ronnqvist
+[dabrahams]: https://github.com/apple/swift-argument-parser/commits?author=dabrahams
 [damuellen]: https://github.com/apple/swift-argument-parser/commits?author=damuellen
 [dcantah]: https://github.com/apple/swift-argument-parser/commits?author=dcantah
 [dduan]: https://github.com/apple/swift-argument-parser/commits?author=dduan
@@ -1207,9 +1286,11 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [ian-twilightcoder]: https://github.com/apple/swift-argument-parser/commits?author=ian-twilightcoder
 [ibrahimoktay]: https://github.com/apple/swift-argument-parser/commits?author=ibrahimoktay
 [imxieyi]: https://github.com/apple/swift-argument-parser/commits?author=imxieyi
+[incertum]: https://github.com/apple/swift-argument-parser/commits?author=incertum
 [IngmarStein]: https://github.com/apple/swift-argument-parser/commits?author=IngmarStein
 [interstateone]: https://github.com/apple/swift-argument-parser/commits?author=interstateone
 [jakepetroules]: https://github.com/apple/swift-argument-parser/commits?author=jakepetroules
+[jglogan]: https://github.com/apple/swift-argument-parser/commits?author=jglogan
 [john-mueller]: https://github.com/apple/swift-argument-parser/commits?author=john-mueller
 [jonathanpenn]: https://github.com/apple/swift-argument-parser/commits?author=jonathanpenn
 [keith]: https://github.com/apple/swift-argument-parser/commits?author=keith
@@ -1219,10 +1300,13 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [kkk669]: https://github.com/apple/swift-argument-parser/commits?author=kkk669
 [klaaspieter]: https://github.com/apple/swift-argument-parser/commits?author=klaaspieter
 [konomae]: https://github.com/apple/swift-argument-parser/commits?author=konomae
+[Konstantin-Krokhin]: https://github.com/apple/swift-argument-parser/commits?author=Konstantin-Krokhin
+[kphrx]: https://github.com/apple/swift-argument-parser/commits?author=kphrx
 [KS1019]: https://github.com/apple/swift-argument-parser/commits?author=KS1019
 [kylemacomber]: https://github.com/apple/swift-argument-parser/commits?author=kylemacomber
 [Lantua]: https://github.com/apple/swift-argument-parser/commits?author=Lantua
 [lorentey]: https://github.com/apple/swift-argument-parser/commits?author=lorentey
+[louisunlimited]: https://github.com/apple/swift-argument-parser/commits?author=louisunlimited
 [LucianoPAlmeida]: https://github.com/apple/swift-argument-parser/commits?author=LucianoPAlmeida
 [MarcoEidinger]: https://github.com/apple/swift-argument-parser/commits?author=MarcoEidinger
 [MartinP7r]: https://github.com/apple/swift-argument-parser/commits?author=MartinP7r
@@ -1246,20 +1330,24 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 [rjstelling]: https://github.com/apple/swift-argument-parser/commits?author=rjstelling
 [robertmryan]: https://github.com/apple/swift-argument-parser/commits?author=robertmryan
 [Sajjon]: https://github.com/apple/swift-argument-parser/commits?author=Sajjon
+[salmanmkc]: https://github.com/apple/swift-argument-parser/commits?author=salmanmkc
 [schlagelk]: https://github.com/apple/swift-argument-parser/commits?author=schlagelk
 [SergeyPetrachkov]: https://github.com/apple/swift-argument-parser/commits?author=SergeyPetrachkov
 [sgl0v]: https://github.com/apple/swift-argument-parser/commits?author=sgl0v
 [sharplet]: https://github.com/apple/swift-argument-parser/commits?author=sharplet
 [sjavora]: https://github.com/apple/swift-argument-parser/commits?author=sjavora
+[stackotter]: https://github.com/apple/swift-argument-parser/commits?author=stackotter
 [Steelskin]: https://github.com/apple/swift-argument-parser/commits?author=Steelskin
 [stuartcarnie]: https://github.com/apple/swift-argument-parser/commits?author=stuartcarnie
 [thomasvl]: https://github.com/apple/swift-argument-parser/commits?author=thomasvl
 [TiagoMaiaL]: https://github.com/apple/swift-argument-parser/commits?author=TiagoMaiaL
 [toddthomas]: https://github.com/apple/swift-argument-parser/commits?author=toddthomas
+[tshortli]: https://github.com/apple/swift-argument-parser/commits?author=tshortli
 [vlm]: https://github.com/apple/swift-argument-parser/commits?author=vlm
 [werm098]: https://github.com/apple/swift-argument-parser/commits?author=werm098
 [Wevah]: https://github.com/apple/swift-argument-parser/commits?author=Wevah
 [Wildchild9]: https://github.com/apple/swift-argument-parser/commits?author=Wildchild9
+[William-Laverty]: https://github.com/apple/swift-argument-parser/commits?author=William-Laverty
 [yim-lee]: https://github.com/apple/swift-argument-parser/commits?author=yim-lee
 [yonihemi]: https://github.com/apple/swift-argument-parser/commits?author=yonihemi
 [YuAo]: https://github.com/apple/swift-argument-parser/commits?author=YuAo

Examples/default-as-flag/DefaultAsFlag.swift

@@ -0,0 +1,54 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Argument Parser open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+import ArgumentParser
+
+@main
+struct DefaultAsFlag: ParsableCommand {
+  static let configuration = CommandConfiguration(
+    abstract: "A utility demonstrating defaultAsFlag options.",
+    discussion: """
+      This command shows how defaultAsFlag options can work both as flags
+      and as options with values.
+      """
+  )
+
+  @Option(defaultAsFlag: "default", help: "A string option with defaultAsFlag.")
+  var stringFlag: String?
+
+  @Option(defaultAsFlag: 42, help: "An integer option with defaultAsFlag.")
+  var numberFlag: Int?
+
+  @Option(defaultAsFlag: true, help: "A boolean option with defaultAsFlag.")
+  var boolFlag: Bool?
+
+  @Option(
+    defaultAsFlag: "transformed",
+    help: "A string option with transform and defaultAsFlag.",
+    transform: { $0.uppercased() }
+  )
+  var transformFlag: String?
+
+  @Option(name: .shortAndLong, help: "A regular option for comparison.")
+  var regular: String?
+
+  @Argument
+  var additionalArgs: [String] = []
+
+  func run() {
+    print("String flag: \(stringFlag?.description ?? "nil")")
+    print("Number flag: \(numberFlag?.description ?? "nil")")
+    print("Bool flag: \(boolFlag?.description ?? "nil")")
+    print("Transform flag: \(transformFlag?.description ?? "nil")")
+    print("Regular option: \(regular?.description ?? "nil")")
+    print("Additional args: \(additionalArgs)")
+  }
+}

Examples/math/Math.swift

@@ -204,6 +204,10 @@ extension Math.Statistics {
     )
     var customArg: String?
 
+    @available(
+      *, deprecated,
+      message: "Deprecated use of custom completion for @Argument"
+    )
     @Argument(
       completion: .custom { _ in ["alabaster", "breakfast", "crunch", "crash"] }
     )
@@ -236,6 +240,9 @@ extension Math.Statistics {
     @Option(completion: .custom(customCompletion))
     var custom: String?
 
+    @available(
+      *, deprecated, message: "Deprecated use of custom completion for @Option"
+    )
     @Option(completion: .custom(customDeprecatedCompletion))
     var customDeprecated: String?
 

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.7
+// swift-tools-version:6.0
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the Swift Argument Parser open source project
@@ -78,6 +78,11 @@ var package = Package(
       name: "color",
       dependencies: ["ArgumentParser"],
       path: "Examples/color"),
+    .executableTarget(
+      name: "default-as-flag",
+      dependencies: ["ArgumentParser"],
+      path: "Examples/default-as-flag"
+    ),
 
     // Tools
     .executableTarget(