Respect the COLUMNS and LINES environment variables when present

Sources/ArgumentParser/Parsable Types/ParsableArguments.swift

@@ -112,6 +112,23 @@ extension ParsableArguments {
     MessageInfo(error: error, type: self).fullText(for: self)
   }
 
+  /// Returns a full message for the given error, including usage information,
+  /// if appropriate.
+  ///
+  /// - Parameters:
+  ///   - error: An error to generate a message for.
+  ///   - columns: The column width to use when wrapping long line in the
+  ///     help screen. If `columns` is `nil`, uses the current terminal
+  ///     width, or a default value of `80` if the terminal width is not
+  ///     available.
+  /// - Returns: A message that can be displayed to the user.
+  public static func fullMessage(
+    for error: Error,
+    columns: Int?
+  ) -> String {
+    MessageInfo(error: error, type: self, columns: columns).fullText(for: self)
+  }
+
   /// Returns the text of the help screen for this type.
   ///
   /// - Parameters:

Sources/ArgumentParser/Usage/MessageInfo.swift

@@ -17,7 +17,7 @@ enum MessageInfo {
   case validation(message: String, usage: String, help: String)
   case other(message: String, exitCode: ExitCode)
 
-  init(error: Error, type: ParsableArguments.Type) {
+  init(error: Error, type: ParsableArguments.Type, columns: Int? = nil) {
     var commandStack: [ParsableCommand.Type]
     var parserError: ParserError? = nil
 
@@ -29,7 +29,7 @@ enum MessageInfo {
       // Exit early on built-in requests
       switch e.parserError {
       case .helpRequested(let visibility):
-        self = .help(text: HelpGenerator(commandStack: e.commandStack, visibility: visibility).rendered())
+        self = .help(text: HelpGenerator(commandStack: e.commandStack, visibility: visibility).rendered(screenWidth: columns))
         return
 
       case .dumpHelpRequested:
@@ -64,7 +64,7 @@ enum MessageInfo {
 
     case let e as ParserError:
       // Send ParserErrors back through the CommandError path
-      self.init(error: CommandError(commandStack: [type.asCommand], parserError: e), type: type)
+      self.init(error: CommandError(commandStack: [type.asCommand], parserError: e), type: type, columns: columns)
       return
 
     default:
@@ -97,7 +97,7 @@ enum MessageInfo {
           if let command = command {
             commandStack = CommandParser(type.asCommand).commandStack(for: command)
           }
-          self = .help(text: HelpGenerator(commandStack: commandStack, visibility: .default).rendered())
+          self = .help(text: HelpGenerator(commandStack: commandStack, visibility: .default).rendered(screenWidth: columns))
         case .dumpRequest(let command):
           if let command = command {
             commandStack = CommandParser(type.asCommand).commandStack(for: command)
@@ -120,7 +120,7 @@ enum MessageInfo {
     } else if let parserError = parserError {
       let usage: String = {
         guard case ParserError.noArguments = parserError else { return usage }
-        return "\n" + HelpGenerator(commandStack: [type.asCommand], visibility: .default).rendered()
+        return "\n" + HelpGenerator(commandStack: [type.asCommand], visibility: .default).rendered(screenWidth: columns)
       }()
       let argumentSet = ArgumentSet(commandStack.last!, visibility: .default, parent: nil)
       let message = argumentSet.errorDescription(error: parserError) ?? ""

Sources/ArgumentParser/Utilities/Platform.swift

@@ -116,25 +116,71 @@ func ioctl(_ a: Int32, _ b: Int32, _ p: UnsafeMutableRawPointer) -> Int32 {
 
 extension Platform {
   /// The default terminal size.
-  static var defaultTerminalSize: (width: Int, height: Int) {
-    (80, 25)
+  private static var defaultTerminalSize: (width: Int, height: Int) {
+    (width: 80, height: 25)
   }
 
-  /// Returns the current terminal size, or the default if the size is
-  /// unavailable.
-  static func terminalSize() -> (width: Int, height: Int) {
+  /// The terminal size specified by the COLUMNS and LINES overrides
+  /// (if present).
+  ///
+  /// Per the [Linux environ(7) manpage][linenv]:
+  ///
+  /// ```
+  /// * COLUMNS and LINES tell applications about the window size,
+  ///   possibly overriding the actual size.
+  /// ```
+  ///
+  /// And the [FreeBSD environ(7) version][bsdenv]:
+  ///
+  /// ```
+  /// COLUMNS    The user's preferred width in column positions for the
+  ///            terminal.  Utilities such as ls(1) and who(1) use this
+  ///            to format output into columns.   If  unset  or  empty,
+  ///            utilities  will use an ioctl(2) call to ask the termi-
+  ///            nal driver for the width.
+  /// ```
+  ///
+  /// > Note: Always returns `(nil, nil)` on Windows and WASI.
+  ///
+  /// - Returns: A tuple consisting of a width found in the `COLUMNS` environment
+  ///   variable (or `nil` if the variable is not present) and a height found in
+  ///   the `LINES` environment variable (or `nil` if that variable is not present).
+  ///
+  /// [linenv]: https://man7.org/linux/man-pages/man7/environ.7.html:~:text=COLUMNS
+  /// [bsdenv]: https://man.freebsd.org/cgi/man.cgi?environ(7)#:~:text=COLUMNS
+  private static func userSpecifiedTerminalSize() -> (width: Int?, height: Int?) {
+    var width: Int? = nil, height: Int? = nil
+
+#if !os(Windows) && !os(WASI)
+    if let colsCStr = getenv("COLUMNS"), let colsVal = Int(String(cString: colsCStr)) {
+      width = colsVal
+    }
+    if let linesCStr = getenv("LINES"), let linesVal = Int(String(cString: linesCStr)) {
+      height = linesVal
+    }
+#endif
+
+    return (width: width, height: height)
+  }
+
+  /// The current terminal size as reported by the windowing system,
+  /// if available.
+  ///
+  /// Returns (nil, nil) if no reported size is available.
+  private static func reportedTerminalSize() -> (width: Int?, height: Int?) {
 #if os(WASI)
     // WASI doesn't yet support terminal size
-    return defaultTerminalSize
+    return (width: nil, height: nil)
 #elseif os(Windows)
-    var csbi: CONSOLE_SCREEN_BUFFER_INFO = CONSOLE_SCREEN_BUFFER_INFO()
+    var csbi = CONSOLE_SCREEN_BUFFER_INFO()
     guard GetConsoleScreenBufferInfo(GetStdHandle(STD_OUTPUT_HANDLE), &csbi) else {
-      return defaultTerminalSize
+      return (width: nil, height: nil)
     }
     return (width: Int(csbi.srWindow.Right - csbi.srWindow.Left) + 1,
             height: Int(csbi.srWindow.Bottom - csbi.srWindow.Top) + 1)
 #else
     var w = winsize()
+
 #if os(OpenBSD)
     // TIOCGWINSZ is a complex macro, so we need the flattened value.
     let tiocgwinsz = Int32(0x40087468)
@@ -144,17 +190,38 @@ extension Platform {
 #else
     let err = ioctl(STDOUT_FILENO, TIOCGWINSZ, &w)
 #endif
-    let width = Int(w.ws_col)
-    let height = Int(w.ws_row)
-    guard err == 0 else { return defaultTerminalSize }
-    return (width: width > 0 ? width : defaultTerminalSize.width,
-            height: height > 0 ? height : defaultTerminalSize.height)
+    guard err == 0 else { return (width: nil, height: nil) }
+
+    let width = Int(w.ws_col), height = Int(w.ws_row)
+
+    return (width: width > 0 ? width : nil,
+            height: height > 0 ? height : nil)
 #endif
   }
 
+  /// Returns the current terminal size, or the default if the size is unavailable.
+  static func terminalSize() -> (width: Int, height: Int) {
+    let specifiedSize = self.userSpecifiedTerminalSize()
+
+    // Avoid needlessly calling ioctl() if a complete override is in effect
+    if let specifiedWidth = specifiedSize.width, let specifiedHeight = specifiedSize.height {
+        return (width: specifiedWidth, height: specifiedHeight)
+    }
+
+    // Get the size self-reported by the terminal, if available
+    let reportedSize = self.reportedTerminalSize()
+
+    // As it isn't required that both width and height always be specified
+    // together, either by the user or the terminal itself, they are
+    // handled separately.
+    return (
+      width: specifiedSize.width ?? reportedSize.width ?? defaultTerminalSize.width,
+      height: specifiedSize.height ?? reportedSize.height ?? defaultTerminalSize.height
+    )
+  }
+
   /// The current terminal size, or the default if the width is unavailable.
   static var terminalWidth: Int {
-    terminalSize().width
+    self.terminalSize().width
   }
 }
-

Sources/ArgumentParserTestHelpers/TestHelpers.swift

@@ -203,6 +203,7 @@ public func AssertEqualStrings(
 public func AssertHelp<T: ParsableArguments>(
   _ visibility: ArgumentVisibility,
   for _: T.Type,
+  columns: Int? = 80,
   equals expected: String,
   file: StaticString = #file,
   line: UInt = #line
@@ -229,18 +230,19 @@ public func AssertHelp<T: ParsableArguments>(
     _ = try T.parse([flag])
     XCTFail(file: file, line: line)
   } catch {
-    let helpString = T.fullMessage(for: error)
+    let helpString = T.fullMessage(for: error, columns: columns)
     AssertEqualStrings(actual: helpString, expected: expected, file: file, line: line)
   }
 
-  let helpString = T.helpMessage(includeHidden: includeHidden, columns: nil)
+  let helpString = T.helpMessage(includeHidden: includeHidden, columns: columns)
   AssertEqualStrings(actual: helpString, expected: expected, file: file, line: line)
 }
 
 public func AssertHelp<T: ParsableCommand, U: ParsableCommand>(
   _ visibility: ArgumentVisibility,
   for _: T.Type,
   root _: U.Type,
+  columns: Int? = 80,
   equals expected: String,
   file: StaticString = #file,
   line: UInt = #line
@@ -261,7 +263,7 @@ public func AssertHelp<T: ParsableCommand, U: ParsableCommand>(
   }
 
   let helpString = U.helpMessage(
-    for: T.self, includeHidden: includeHidden, columns: nil)
+    for: T.self, includeHidden: includeHidden, columns: columns)
   AssertEqualStrings(actual: helpString, expected: expected, file: file, line: line)
 }
 

Tests/ArgumentParserEndToEndTests/UnparsedValuesEndToEndTest.swift

@@ -26,7 +26,8 @@ fileprivate struct Qux: ParsableArguments {
 fileprivate struct Quizzo: ParsableArguments {
   @Option() var name: String
   @Flag() var verbose = false
-  let count = 0
+  let count: Int
+  init() { self.count = 0 } // silence warning about count not being decoded
 }
 
 extension UnparsedValuesEndToEndTests {

Tests/ArgumentParserExampleTests/CountLinesExampleTests.swift

@@ -15,6 +15,12 @@ import XCTest
 import ArgumentParserTestHelpers
 
 final class CountLinesExampleTests: XCTestCase {
+  override func setUp() {
+    #if !os(Windows) && !os(WASI)
+    unsetenv("COLUMNS")
+    #endif
+  }
+
   func testCountLines() throws {
     guard #available(macOS 12, *) else { return }
     let testFile = try XCTUnwrap(Bundle.module.url(forResource: "CountLinesTest", withExtension: "txt"))

Tests/ArgumentParserExampleTests/MathExampleTests.swift

@@ -14,6 +14,12 @@ import ArgumentParser
 import ArgumentParserTestHelpers
 
 final class MathExampleTests: XCTestCase {
+  override func setUp() {
+    #if !os(Windows) && !os(WASI)
+    unsetenv("COLUMNS")
+    #endif
+  }
+
   func testMath_Simple() throws {
     try AssertExecuteCommand(command: "math 1 2 3 4 5", expected: "15")
     try AssertExecuteCommand(command: "math multiply 1 2 3 4 5", expected: "120")

Tests/ArgumentParserExampleTests/RepeatExampleTests.swift

@@ -13,6 +13,12 @@ import XCTest
 import ArgumentParserTestHelpers
 
 final class RepeatExampleTests: XCTestCase {
+  override func setUp() {
+    #if !os(Windows) && !os(WASI)
+    unsetenv("COLUMNS")
+    #endif
+  }
+
   func testRepeat() throws {
     try AssertExecuteCommand(command: "repeat hello", expected: """
         hello

Tests/ArgumentParserExampleTests/RollDiceExampleTests.swift

@@ -13,6 +13,12 @@ import XCTest
 import ArgumentParserTestHelpers
 
 final class RollDiceExampleTests: XCTestCase {
+  override func setUp() {
+    #if !os(Windows) && !os(WASI)
+    unsetenv("COLUMNS")
+    #endif
+  }
+
   func testRollDice() throws {
     try AssertExecuteCommand(command: "roll --times 6")
   }

Tests/ArgumentParserPackageManagerTests/HelpTests.swift

@@ -14,6 +14,11 @@ import XCTest
 import ArgumentParserTestHelpers
 
 final class HelpTests: XCTestCase {
+  override func setUp() {
+    #if !os(Windows) && !os(WASI)
+    unsetenv("COLUMNS")
+    #endif
+  }
 }
 
 func getErrorText<T: ParsableArguments>(_: T.Type, _ arguments: [String]) -> String {

Tests/ArgumentParserPackageManagerTests/Tests.swift

@@ -14,6 +14,11 @@ import ArgumentParser
 import ArgumentParserTestHelpers
 
 final class Tests: XCTestCase {
+  override func setUp() {
+    #if !os(Windows) && !os(WASI)
+    unsetenv("COLUMNS")
+    #endif
+  }
 }
 
 extension Tests {

Tests/ArgumentParserUnitTests/HelpGenerationTests.swift

@@ -799,3 +799,55 @@ extension HelpGenerationTests {
       """)
   }
 }
+
+extension HelpGenerationTests {
+  private struct WideHelp: ParsableCommand {
+    @Argument(help: "54 characters of help, so as to wrap when columns < 80")
+    var argument: String?
+  }
+
+  func testColumnsEnvironmentOverride() throws {
+    #if os(Windows) || os(WASI)
+    throw XCTSkip("Unsupported on this platform")
+    #endif
+
+    defer { unsetenv("COLUMNS") }
+    unsetenv("COLUMNS")
+    AssertHelp(.default, for: WideHelp.self, columns: nil, equals: """
+      USAGE: wide-help [<argument>]
+
+      ARGUMENTS:
+        <argument>              54 characters of help, so as to wrap when columns < 80
+
+      OPTIONS:
+        -h, --help              Show help information.
+
+      """)
+
+    setenv("COLUMNS", "60", 1)
+    AssertHelp(.default, for: WideHelp.self, columns: nil, equals: """
+      USAGE: wide-help [<argument>]
+
+      ARGUMENTS:
+        <argument>              54 characters of help, so as to
+                                wrap when columns < 80
+
+      OPTIONS:
+        -h, --help              Show help information.
+
+      """)
+
+    setenv("COLUMNS", "79", 1)
+    AssertHelp(.default, for: WideHelp.self, columns: nil, equals: """
+      USAGE: wide-help [<argument>]
+
+      ARGUMENTS:
+        <argument>              54 characters of help, so as to wrap when columns <
+                                80
+
+      OPTIONS:
+        -h, --help              Show help information.
+
+      """)
+  }
+}