feat(usage): single char aliases first in help

Display short switches first in usage, and indent long switches only options. Fix #1403
yargs · Mar 4, 2020 · 1ecc5e3 · 1ecc5e3
1 parent c36c571
commit 1ecc5e3
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 91 deletions.
diff --git a/lib/usage.js b/lib/usage.js
@@ -248,6 +248,13 @@ module.exports = function usage (yargs, y18n) {
     if (!groups[defaultGroup]) groups[defaultGroup] = []
     addUngroupedKeys(keys, options.alias, groups)
 
+    const isShortSwitch = sw => /^[^0-9]$/.test(sw)
+
+    // check if some option groups use short switches
+    const shortSwitchesUsed = Object.keys(groups)
+      .filter(groupName => groupName !== self.getPositionalGroupName())
+      .some(groupName => groups[groupName].filter(filterHiddenOptions).some(isShortSwitch))
+
     // display 'Options:' table along with any custom tables:
     Object.keys(groups).forEach((groupName) => {
       if (!groups[groupName].length) return
@@ -268,14 +275,25 @@ module.exports = function usage (yargs, y18n) {
 
       // actually generate the switches string --foo, -f, --bar.
       const switches = normalizedKeys.reduce((acc, key) => {
-        acc[key] = [key].concat(options.alias[key] || [])
-          .map(sw => {
-            // for the special positional group don't
-            // add '--' or '-' prefix.
-            if (groupName === self.getPositionalGroupName()) return sw
-            else return (/^[^0-9]$/.test(sw) ? '-' : '--') + sw
-          })
-          .join(', ')
+        let keyAndAliases = [key].concat(options.alias[key] || [])
+        let indent = 0
+        // switch handling (except for the special positional group)
+        if (groupName !== self.getPositionalGroupName()) {
+          if (shortSwitchesUsed) {
+            // place short switches first (see #1403)
+            keyAndAliases = keyAndAliases.sort(
+              (a, b) => isShortSwitch(a) === isShortSwitch(b) ? 0 : (isShortSwitch(a) ? -1 : 1)
+            )
+            // indent long-switches only options (see #1403)
+            if (!isShortSwitch(keyAndAliases[0])) indent = '-x, '.length
+          }
+          // add switch prefixes
+          keyAndAliases = keyAndAliases.map(sw => (isShortSwitch(sw) ? '-' : '--') + sw)
+        }
+        acc[key] = {
+          text: keyAndAliases.join(', '),
+          indent
+        }
 
         return acc
       }, {})
@@ -308,7 +326,7 @@ module.exports = function usage (yargs, y18n) {
         ].filter(Boolean).join(' ')
 
         ui.span(
-          { text: kswitch, padding: [0, 2, 0, 2], width: maxWidth(switches, theWrap) + 4 },
+          { text: kswitch.text, padding: [0, 2, 0, 2 + kswitch.indent], width: maxWidth(switches, theWrap) + 4 },
           desc
         )
 
@@ -373,8 +391,11 @@ module.exports = function usage (yargs, y18n) {
     }
 
     table.forEach((v) => {
+      // column might be of the form "text"
+      // or { text: "text", indent: 4 }
+      const { text, indent = 0 } = v[0].text ? v[0] : { text: v[0] }
       width = Math.max(
-        stringWidth(modifier ? `${modifier} ${v[0]}` : v[0]),
+        stringWidth(modifier ? `${modifier} ${text}` : text) + indent,
         width
       )
     })