Help output should be line-wrapped to screen width about args HOT 10 CLOSED

dart-lang commented on July 21, 2024 3

Help output should be line-wrapped to screen width

from args.

Comments (10)

nex3 commented on July 21, 2024

Doing this automatically would require args to import dart:io, which would be a breaking change. That's not impossible, since I don't know if we really care about command-line argument parsing on the browser, but it's something to consider.

Another possibility would be to have a way to tell ArgParser what the screen width was, but that's not the most pleasant API.

from args.

Hixie commented on July 21, 2024

You could have an args package for dart:io users and an args package for non-dart:io users (though I don't really understand how you would use args without dart:io).

from args.

Hixie commented on July 21, 2024

cc @gspencer-goog

FWIW, this issue is dire enough for us (Flutter) at this point that I'd be eager to just have a way to tell ArgParser the size of the screen, if that's the best we can do. The current situation is that every help string we have ends up wrapped at a different length and it is really ugly.

from args.

gspencergoog commented on July 21, 2024

I wonder if we could just replace the help printing with our own algorithm that looks at the Option objects inside the arg parser instead of having the arg parser print the output itself.

from args.

Hixie commented on July 21, 2024

Here's an example (combined with some bad line spacing, see #48, to make this especially egregiously hard to read) of where our inconsistency in our conventions results in terrible output, which would be entirely mitigated if args could handle this:

$ flutter create --help
Create a new Flutter project.

If run on a project that already exists, this will repair the project, recreating any files that are m
issing.

Usage: flutter create <output directory>
-h, --help                     Print this usage information.
    --[no-]pub                 Whether to run "flutter packages get" after the project has been create
d.
                               (defaults to on)

    --[no-]offline             When "flutter packages get" is run by the create command, this indicate
s whether to run it in offline mode or not. In offline mode, it will need to have all dependencies alr
eady available in the pub cache to succeed.
    --[no-]with-driver-test    Also add a flutter_driver dependency and generate a sample 'flutter dri
ve' test.
-t, --template=<type>          Specify the type of project to create.

          [app] (default)      (default) Generate a Flutter application.
          [package]            Generate a shareable Flutter project containing modular Dart code.
          [plugin]             Generate a shareable Flutter project containing an API in Dart code
                               with a platform-specific implementation for Android, for iOS code, or f
or both.

    --description              The description to use for your new Flutter project. This string ends u
p in the pubspec.yaml file.
                               (defaults to "A new Flutter project.")

    --org                      The organization responsible for your new Flutter project, in reverse d
omain name notation.
                               This string is used in Java package names and as prefix in the iOS bund
le identifier.
                               (defaults to "com.example")

-i, --ios-language             [objc (default), swift]
-a, --android-language         [java (default), kotlin]

Run "flutter help" to see global options.

from args.

gspencergoog commented on July 21, 2024

How about supplying an optional usageFormatter argument to the ArgParser constructor that takes a callback that receives a List<dynamic> with Options and Strings in it and returns a String? Then you can have it do special formatting (e.g. ANSI coloring, line wrapping, whatever), but the default one can call new Usage(_optionsAndSeparators).generate(), and keep the dependency on dart:io out.

It would, of course, be nice if the existing Usage class was more modular so that anyone writing a formatter could just subclass it and override what they want to be different.

from args.

gspencergoog commented on July 21, 2024

Just to get an idea of what the desired output might look like (on an 80-column terminal):

$ flutter create --help
Create a new Flutter project.

If run on a project that already exists, this will repair the project,
recreating any files that are missing.

Usage: flutter create <output directory>
  -h, --help                 Print this usage information.

  --[no-]pub                 Whether to run "flutter packages get" after the
                             project has been created.
                             (defaults to on)

  --[no-]offline             When "flutter packages get" is run by the create
                             command, this indicates whether to run it in
                             offline mode or not. In offline mode, it will need
                             to have all dependencies already available in the
                             pub cache to succeed.

  --[no-]with-driver-test    Also add a flutter_driver dependency and generate a
                             sample 'flutter drive' test.

  -t, --template=<type>      Specify the type of project to create.
          [app] (default)    Generate a Flutter application.
          [package]          Generate a shareable Flutter project containing
                             modular Dart code.
          [plugin]           Generate a shareable Flutter project containing an
                             API in Dart code with a platform-specific
                             implementation for Android, for iOS code, or for
                             both.

  --description              The description to use for your new Flutter
                             project. This string ends up in the pubspec.yaml
                             file.
                             (defaults to "A new Flutter project.")

  --org                      The organization responsible for your new Flutter
                             project, in reverse domain name notation. This
                             string is used in Java package names and as prefix
                             in the iOS bundle identifier.
                             (defaults to "com.example")

  -i, --ios-language         [objc (default), swift]

  -a, --android-language     [java (default), kotlin]

Run "flutter help" to see global options.

I also think that even just having an optional wrapWidth argument that is null by default, and otherwise contains the column to wrap to, would go a long way towards solving this, since then we could interrogate the terminal ourselves (and incur the dart:io dependency), or even just hard code it to 80.

from args.

munificent commented on July 21, 2024

I believe if you give the args package help strings that contain newlines, it will retain them. So as a workaround, how about just manually line-wrapping the help text to fit within 80 columns? Even if the user's window is wider, it's may be more readable to keep the column relatively narrow.

I agree it would be nice if args could wrap for you based on terminal width.

from args.

Hixie commented on July 21, 2024

The idea is to wrap to the user's width. (e.g. I often have terminals narrower than 80 chars.)

from args.

natebosch commented on July 21, 2024

We have support for usageLineLength now. I don't think it makes sense to do this automatically due to the dart:io import so I don't think there's anything further to do on this issue.

from args.

Help output should be line-wrapped to screen width about args HOT 10 CLOSED

Comments (10)

Related Issues (20)

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent