Project

General

Profile

Feature #13849

Show --dump options in help

Added by sonots (Naotoshi Seo) 25 days ago. Updated 4 days ago.

Status:
Closed
Priority:
Normal
Target version:
[ruby-core:82519]

Description

Current help does not show any helps for --dump options such as --dump=insns.
I want to get them.

$ ./ruby --help
Usage: ./ruby [switches] [--] [programfile] [arguments]
  -0[octal]       specify record separator (\0, if no argument)
  -a              autosplit mode with -n or -p (splits $_ into $F)
  -c              check syntax only
  -Cdirectory     cd to directory before executing your script
  -d, --debug     set debugging flags (set $DEBUG to true)
  -e 'command'    one line of script. Several -e's allowed. Omit [programfile]
  -Eex[:in], --encoding=ex[:in]
                  specify the default external and internal character encodings
  -Fpattern       split() pattern for autosplit (-a)
  -i[extension]   edit ARGV files in place (make backup if extension supplied)
  -Idirectory     specify $LOAD_PATH directory (may be used more than once)
  -l              enable line ending processing
  -n              assume 'while gets(); ... end' loop around your script
  -p              assume loop like -n but print line also like sed
  -rlibrary       require the library before executing your script
  -s              enable some switch parsing for switches after script name
  -S              look for the script using PATH environment variable
  -T[level=1]     turn on tainting checks
  -v, --verbose   print version number, then turn on verbose mode
  -w              turn warnings on for your script
  -W[level=2]     set warning level; 0=silence, 1=medium, 2=verbose
  -x[directory]   strip off text before #!ruby line and perhaps cd to directory
  --copyright     print the copyright
  --enable=feature[,...], --disable=feature[,...]
                  enable or disable features
  --external-encoding=encoding, --internal-encoding=encoding
                  specify the default external or internal character encoding
  --version       print the version
  --help          show this message, -h for short message
Features:
  gems            rubygems (default: enabled)
  did_you_mean    did_you_mean (default: enabled)
  rubyopt         RUBYOPT environment variable (default: enabled)
  frozen-string-literal
                  freeze all string literals (default: disabled)

History

#1 Updated by sonots (Naotoshi Seo) 25 days ago

  • Target version set to next minor

#2 [ruby-core:82520] Updated by sonots (Naotoshi Seo) 25 days ago

ruby 2.4.1 (actually, trunk)

#3 [ruby-core:82521] Updated by sonots (Naotoshi Seo) 25 days ago

version, copyright, usage, help, yydebug, syntax, parsetree, parsetree_with_comment, insns are available as an argument of --dump option.
I now wonder which I should support. I want yydebug, parsetree, and insns (parsetree_with_comment is too long to show in help?)
Any opinions?

diff --git a/ruby.c b/ruby.c
index f2f3c86e09..808a2bdce6 100644
--- a/ruby.c
+++ b/ruby.c
@@ -191,7 +191,7 @@ static struct {
 static void
 show_usage_line(const char *str, unsigned int namelen, unsigned int secondlen, int help)
 {
-    const unsigned int w = 16;
+    const unsigned int w = 17;
     const int wrap = help && namelen + secondlen - 2 > w;
     printf("  %.*s%-*.*s%-*s%s\n", namelen-1, str,
           (wrap ? 0 : w - namelen + 1),
@@ -238,6 +238,9 @@ usage(const char *name, int help)
        M("-W[level=2]",   "",                     "set warning level; 0=silence, 1=medium, 2=verbose"),
        M("-x[directory]", "",                     "strip off text before #!ruby line and perhaps cd to directory"),
        M("-h",            "",                     "show this message, --help for more info"),
+       M("--dump=insns",     "",                          "dump YARV instructions"),
+       M("--dump=yydebug",   "",                          "dump yydebug of yacc parser generator"),
+       M("--dump=parsetree", "",                          "dump parsetree"),
     };
     static const struct message help_msg[] = {
        M("--copyright",                   "", "print the copyright"),
``

#4 [ruby-core:82524] Updated by naruse (Yui NARUSE) 24 days ago

sonots (Naotoshi Seo) wrote:

version, copyright, usage, help, yydebug, syntax, parsetree, parsetree_with_comment, insns are available as an argument of --dump option.
I now wonder which I should support. I want yydebug, parsetree, and insns (parsetree_with_comment is too long to show in help?)
Any opinions?

Write detailed description elsewhere, and then just show the link in --help.

#5 [ruby-core:82525] Updated by sonots (Naotoshi Seo) 24 days ago

  • Target version changed from next minor to Next Major

elsewhere ... where are you supposed?

#6 [ruby-core:82526] Updated by nobu (Nobuyoshi Nakada) 24 days ago

Or add the message "try --dump=? to show valid arguments".

#7 [ruby-core:82530] Updated by shevegen (Robert A. Heiler) 24 days ago

+1

The "--dump=?" may also work. I do however think that Naotoshi Sao's suggestion,
although more verbose, may be best, since people can simply read what these
options do in the short description, such as "dump YARV instructions". (I
actually did not know that this option exists altogether.)

#8 [ruby-core:82531] Updated by sonots (Naotoshi Seo) 24 days ago

I feel splitting help to --dump=? is nice idea.

By the way, the current behavior is as:

bash

$ ./ruby --dump=?
./ruby: warning: don't know how to dump `?',
./ruby: warning: but only [version, copyright, usage, help, yydebug, syntax, parsetree, parsetree_with_comment, insns].

zsh (without setopt nonomatch)

 $ ./ruby --dump=?
zsh: no matches found: --dump=?
$ ./ruby '--dump=?'
./ruby: warning: don't know how to dump `?',
./ruby: warning: but only [version, copyright, usage, help, yydebug, syntax, parsetree, parsetree_with_comment, insns].

Since --dump=help is already used, I will pick --dump=?, but please note the zsh behavior.

#9 [ruby-core:82535] Updated by znz (Kazuhiro NISHIYAMA) 24 days ago

bash also expand glob if files exist.
And bash with shopt -s failglob can raise error like zsh.
So I think users should not depend such behavior.

$ touch ./--dump=a
$ ruby --dump=?
ruby: warning: don't know how to dump `a',
ruby: warning: but only [version, copyright, usage, yydebug, syntax, parsetree, parsetree_with_comment, insns].
$ rm ./--dump=a
$ shopt -s failglob
$ ruby --dump=?
-bash: 一致しません: --dump=?

#10 [ruby-core:82536] Updated by sonots (Naotoshi Seo) 24 days ago

It sounds --dump=? is troublesome, and also it is not easy to implement.
It looks --dump=help and --help is same. Can I drop the current --dump=help, and use --dump=help instead of --dump=? ?

#11 [ruby-core:82548] Updated by sonots (Naotoshi Seo) 24 days ago

I removed old --dump=help, and --dump=usage, and changed --dump=help to show help messages of --dump.
https://github.com/ruby/ruby/pull/1688

$ ./ruby --help
Usage: ./ruby [switches] [--] [programfile] [arguments]
   ...
  --dump=target[,....]
                  try --dump=help to show help messages of --dump

(this is not shown with short help, that is, -h)

$ ./ruby --dump=help
Usage: ./ruby [switches] [--] [programfile] [arguments]
  --dump=insns    dump instruction sequences
  --dump=yydebug  dump yydebug of yacc parser generator
  --dump=parsetree, --dump=parsetree_with_comment
                  dump AST or AST with comments.

#12 [ruby-core:82558] Updated by nobu (Nobuyoshi Nakada) 23 days ago

What about --help=dump (--help=feature and so on)?

#13 [ruby-core:82570] Updated by sonots (Naotoshi Seo) 23 days ago

Changed as:

 $ ./ruby --help
 Usage: ./ruby [switches] [--] [programfile] [arguments]
   -0[octal]       specify record separator (\0, if no argument)
   -a              autosplit mode with -n or -p (splits $_ into $F)
   -c              check syntax only
   -Cdirectory     cd to directory before executing your script
   -d, --debug     set debugging flags (set $DEBUG to true)
   -e 'command'    one line of script. Several -e's allowed. Omit [programfile]
   -Eex[:in], --encoding=ex[:in]
                   specify the default external and internal character encodings
   -Fpattern       split() pattern for autosplit (-a)
   -i[extension]   edit ARGV files in place (make backup if extension supplied)
   -Idirectory     specify $LOAD_PATH directory (may be used more than once)
   -l              enable line ending processing
   -n              assume 'while gets(); ... end' loop around your script
   -p              assume loop like -n but print line also like sed 
   -rlibrary       require the library before executing your script
   -s              enable some switch parsing for switches after script name
   -S              look for the script using PATH environment variable
   -T[level=1]     turn on tainting checks
   -v, --verbose   print version number, then turn on verbose mode
   -w              turn warnings on for your script
   -W[level=2]     set warning level; 0=silence, 1=medium, 2=verbose
   -x[directory]   strip off text before #!ruby line and perhaps cd to directory
   --copyright     print the copyright
+  --dump=target[,...]
+                  try --help=dump to show help messages of --dump
   --enable=feature[,...], --disable=feature[,...]
                   enable or disable features
   --external-encoding=encoding, --internal-encoding=encoding
                   specify the default external or internal character encoding
   --version       print the version
   --help          show this message, -h for short message
 Features:
   gems            rubygems (default: enabled)
   did_you_mean    did_you_mean (default: enabled)
   rubyopt         RUBYOPT environment variable (default: enabled)
   frozen-string-literal
                   freeze all string literals (default: disabled)
$ ./ruby --help=dump
Usage: ./ruby [switches] [--] [programfile] [arguments]
  --dump=insns    dump instruction sequences
  --dump=yydebug  dump yydebug of yacc parser generator
  --dump=parsetree, --dump=parsetree_with_comment
                  dump AST or AST with comments.
$ ./ruby --help=xxx
./ruby: warning: don't know how to show help `xxx',
./ruby: warning: but only [dump].

Now, --dump=help is kept.

#14 [ruby-core:82596] Updated by sonots (Naotoshi Seo) 23 days ago

Sorry for raising a discussion again.
I noticed that Features list are shown bottom at --help.

$ ruby --help
...
  --enable=feature[,...], --disable=feature[,...]
                  enable or disable features
  --external-encoding=encoding, --internal-encoding=encoding
                  specify the default external or internal character encoding
  --version       print the version
  --help          show this message, -h for short message
Features:
  gems            rubygems (default: enabled)
  did_you_mean    did_you_mean (default: enabled)
  rubyopt         RUBYOPT environment variable (default: enabled)
  frozen-string-literal
                  freeze all string literals (default: disabled)

I now feel showing dump lists with --help=dump does not have a consistency.
I have two idea.

(1) Show dump list at bottom as features list

$ ruby --help
Usage: ruby [switches] [--] [programfile] [arguments]
  -0[octal]       specify record separator (\0, if no argument)
  -a              autosplit mode with -n or -p (splits $_ into $F)
  -c              check syntax only
  -Cdirectory     cd to directory before executing your script
  -d, --debug     set debugging flags (set $DEBUG to true)
  -e 'command'    one line of script. Several -e's allowed. Omit [programfile]
  -Eex[:in], --encoding=ex[:in]
                  specify the default external and internal character encodings
  -Fpattern       split() pattern for autosplit (-a)
  -i[extension]   edit ARGV files in place (make backup if extension supplied)
  -Idirectory     specify $LOAD_PATH directory (may be used more than once)
  -l              enable line ending processing
  -n              assume 'while gets(); ... end' loop around your script
  -p              assume loop like -n but print line also like sed
  -rlibrary       require the library before executing your script
  -s              enable some switch parsing for switches after script name
  -S              look for the script using PATH environment variable
  -T[level=1]     turn on tainting checks
  -v, --verbose   print version number, then turn on verbose mode
  -w              turn warnings on for your script
  -W[level=2]     set warning level; 0=silence, 1=medium, 2=verbose
  -x[directory]   strip off text before #!ruby line and perhaps cd to directory
  --copyright     print the copyright
  --dump={insns|parsetree|...}[,...]
                  dump debug information. see below for available dump list
  --enable={gems|rubyopt|...}[,...], --disable={gems|rubyopt|...}[,...]
                  enable or disable features. see below for available features
  --external-encoding=encoding, --internal-encoding=encoding
                  specify the default external or internal character encoding
  --version       print the version
  --help          show this message, -h for short message
Dump List:
  insns           instruction sequences
  yydebug         yydebug of yacc parser generator
  parsetree       AST
  parsetree_with_comment
                  AST with comments 
Features:
  gems            rubygems (default: enabled)
  did_you_mean    did_you_mean (default: enabled)
  rubyopt         RUBYOPT environment variable (default: enabled)
  frozen-string-literal
                  freeze all string literals (default: disabled)

(2) Show dump list and features list by --help=dump and --help=feature respectively

$ ./ruby --help
Usage: ruby [switches] [--] [programfile] [arguments]
  -0[octal]       specify record separator (\0, if no argument)
  -a              autosplit mode with -n or -p (splits $_ into $F)
  -c              check syntax only
  -Cdirectory     cd to directory before executing your script
  -d, --debug     set debugging flags (set $DEBUG to true)
  -e 'command'    one line of script. Several -e's allowed. Omit [programfile]
  -Eex[:in], --encoding=ex[:in]
                  specify the default external and internal character encodings
  -Fpattern       split() pattern for autosplit (-a)
  -i[extension]   edit ARGV files in place (make backup if extension supplied)
  -Idirectory     specify $LOAD_PATH directory (may be used more than once)
  -l              enable line ending processing
  -n              assume 'while gets(); ... end' loop around your script
  -p              assume loop like -n but print line also like sed
  -rlibrary       require the library before executing your script
  -s              enable some switch parsing for switches after script name
  -S              look for the script using PATH environment variable
  -T[level=1]     turn on tainting checks
  -v, --verbose   print version number, then turn on verbose mode
  -w              turn warnings on for your script
  -W[level=2]     set warning level; 0=silence, 1=medium, 2=verbose
  -x[directory]   strip off text before #!ruby line and perhaps cd to directory
  --copyright     print the copyright
  --dump={insns|parsetree|...}[,...]
                  dump debug information. see --help=dump for details
  --enable={gems|rubyopt|...}[,...], --disable={gems|rubyopt|...}[,...]
                  enable or disable features. see --help=feature for details
  --external-encoding=encoding, --internal-encoding=encoding
                  specify the default external or internal character encoding
  --version       print the version
  --help          show this message, -h for short message
$ ./ruby --help=dump
Usage: ./ruby [switches] [--] [programfile] [arguments]
  --dump={insns|parsetree|...}[,...]
                  dump debug information. followings are available dump list
Dump List:
  insns           instruction sequences
  yydebug         yydebug of yacc parser generator
  parsetree       AST
  parsetree_with_comment
                  AST with comments
$ ./ruby --help=feature
Usage: ./ruby [switches] [--] [programfile] [arguments]
  --enable={gems|rubyopt|...}[,...], --disable={gems|rubyopt|...}[,...]
                  enable or disable features. followings are available features
Features:
  gems            rubygems (default: enabled)
  did_you_mean    did_you_mean (default: enabled)
  rubyopt         RUBYOPT environment variable (default: enabled)
  frozen-string-literal
                  freeze all string literals (default: disabled)

I feel (2) is better based on the matz principle to keep help as compact as possible.

#15 [ruby-core:82601] Updated by nobu (Nobuyoshi Nakada) 23 days ago

sonots (Naotoshi Seo) wrote:

I feel (2) is better based on the matz principle to keep help as compact as possible.

Compact help is -h, --help doesn't need to be.

#16 [ruby-core:82603] Updated by sonots (Naotoshi Seo) 23 days ago

!! So, (1) was fine.
Hmm, I feel showing everything by one command makes easier to find options, so I will change implementation to (1).

#19 Updated by sonots (Naotoshi Seo) 4 days ago

  • Status changed from Open to Closed

Also available in: Atom PDF