global: clean up helps of user functions

ble.pp

@@ -267,6 +267,7 @@ function ble/base/initialize-version-information {
 
 function ble/util/put { builtin printf '%s' "$*"; }
 function ble/util/print { builtin printf '%s\n' "$*"; }
+function ble/util/print-lines { builtin printf '%s\n' "$@"; }
 
 ## @fn ble/bin/.default-utility-path commands...
 ##   取り敢えず ble/bin/* からコマンドを呼び出せる様にします。
@@ -641,9 +642,9 @@ function ble/base/initialize-cache-directory {
 fi
 function ble/base/print-usage-for-no-argument-command {
   local name=${FUNCNAME[1]} desc=$1; shift
-  printf '%s\n' \
-         "usage: $name" \
-         "$desc" >&2
+  ble/util/print-lines \
+    "usage: $name" \
+    "$desc" >&2
   [[ $1 != --help ]] && return 2
   return 0
 }

lib/core-complete-def.sh

@@ -57,9 +57,9 @@ bleopt/declare -v complete_allow_reduction ''
 bleopt/declare -n complete_menu_style align-nowrap
 function bleopt/check:complete_menu_style {
   if ! ble/is-function "ble/complete/menu-style:$value/construct-page"; then
-    builtin printf '%s\n' \
-            "bleopt: Invalid value complete_menu_style='$value'." \
-            "  A function 'ble/complete/menu-style:$value/construct-page' is not defined." >&2
+    ble/util/print-lines \
+      "bleopt: Invalid value complete_menu_style='$value'." \
+      "  A function 'ble/complete/menu-style:$value/construct-page' is not defined." >&2
     return 1
   fi
   return 0

lib/core-complete.sh

@@ -5908,11 +5908,9 @@ function ble-sabbrev {
     ble/complete/sabbrev/read-arguments "$@"
     if [[ $flag_help || $flag_error ]]; then
       [[ $flag_error ]] && ble/util/print
-      printf '%s\n' \
-             'usage: ble-sabbrev key=value' \
-             'usage: ble-sabbrev -m key=function' \
-             'usage: ble-sabbrev --help' \
-             'Register sabbrev expansion.'
+      ble/util/print-lines \
+        'usage: ble-sabbrev [key=value|-m key=function|--help]' \
+        '     Register sabbrev expansion.'
       [[ ! $flag_error ]]; return "$?"
     fi
 

memo/ChangeLog.md

@@ -12,7 +12,7 @@
 - edit (kill/copy): combine multiple kills and copies (suggested by 3ximus) `#D1443` 66564e1
   - edit (`{kill,copy}-region-or`): fix unconditionally combined kills/copies (reported by 3ximus) `#D1447` 1631751
 - canvas: update emoji database and support `bleopt emoji_version` (motivated by endorfina) `#D1454` d1f8c27
-- canvas, edit: support `bleopt info_display` (suggested by 0neGuyDev) `#D1458` 0000000
+- canvas, edit: support `bleopt info_display` (suggested by 0neGuyDev) `#D1458` 69228fa
 
 ## Changes
 
@@ -47,6 +47,7 @@
 - util: add function `ble/string#quote-words` `#D1451` f03b87b
 - syntax (`ble/syntax:bash/simple-word/eval`): cache `#D1453` 6d8311e
 - global: refactor `setup => set up / set-up` `#D1456` c37a9dd
+- global: clean up helps of user functions `#D1459` 0000000
 
 <!---------------------------------------------------------------------------->
 # ble-0.4.0-devel2

note.txt

@@ -3813,6 +3813,10 @@ bash_tips
 
 2021-02-03
 
+  * global: help の類の整理 [#D1459]
+    * bleopt: --help に対応していない
+    * blehook: --help が単純すぎる
+
   * canvas: status line を最終行に表示する可能性 (suggested by 0neGuyDev) [#D1458]
     https://github.com/akinomyoga/ble.sh/issues/85
 

src/benchmark.sh

@@ -179,9 +179,26 @@ function ble-measure {
   local flags= command= count=$_ble_measure_count
   ble-measure/.read-arguments "$@" || return "$?"
   if [[ $flags == *h* ]]; then
-    ble/util/print 'usage: ble-measure [-q|-ac COUNT] command'
-    ble/util/print '  Measure the time of command.'
-    return 0
+    ble/util/print-lines \
+      'usage: ble-measure [-q|-ac COUNT|-TB TIME] [--] COMMAND' \
+      '    Measure the time of command.' \
+      '' \
+      '  Options:' \
+      '    -q        Do not print results to stdout.' \
+      '    -a COUNT  Measure COUNT times and average.' \
+      '    -c COUNT  Measure COUNT times and take maximum.' \
+      '    -T TIME   Set minimal measuring time.' \
+      '    -B BASE   Set base time (overhead of ble-measure).' \
+      '    --        The rest arguments are treated as command.' \
+      '    --help    Print this help.' \
+      '' \
+      '  Arguments:' \
+      '    COMMAND   Command to be executed repeatedly.' \
+      '' \
+      '  Exit status:' \
+      '    Returns 1 for the failure in measuring the time.  Returns 2 after printing' \
+      '    help.  Otherwise, returns 0.'
+    return 2
   fi
 
   local prev_n= prev_utot=

src/color.sh

@@ -844,16 +844,17 @@ function ble/color/setface/.check-argument {
   fi
 
   local name=${FUNCNAME[1]}
-  printf '%s\n' "usage: $name FACE_NAME [TYPE:]SPEC" '' \
-         'TYPE' \
-         '  Specifies the format of SPEC. The following values are available.' \
-         '' \
-         '  gspec   Comma separated graphic attribute list' \
-         '  g       Integer value' \
-         '  ref     Face name or id (reference)' \
-         '  copy    Face name or id (copy value)' \
-         '  sgrspec Parameters to the control function SGR' \
-         '  ansi    ANSI Sequences' >&2
+  ble/util/print-lines \
+    "usage: $name FACE_NAME [TYPE:]SPEC" \
+    '    Set face.' \
+    '' \
+    '  TYPE      Specifies the format of SPEC. The following values are available.' \
+    '    gspec   Comma separated graphic attribute list' \
+    '    g       Integer value' \
+    '    ref     Face name or id (reference)' \
+    '    copy    Face name or id (copy value)' \
+    '    sgrspec Parameters to the control function SGR' \
+    '    ansi    ANSI Sequences' >&2
   ext=2; [[ $# == 1 && $1 == --help ]] && ext=0
   return 1
 }
@@ -966,16 +967,24 @@ function ble/color/initialize-faces {
 }
 
 function ble/color/list-faces {
-  local key g ret opt_color=
-  [[ -t 1 ]] && opt_color=1
+  local opt_color=; [[ -t 1 ]] && opt_color=1
+
+  local ret sgr0= sgr1= sgr2=
+  if [[ $opt_color ]]; then
+    sgr0=$_ble_term_sgr0
+    ble/color/face2sgr command_function; sgr1=$ret
+    ble/color/face2sgr syntax_varname; sgr2=$ret
+  fi
+
+  local key g
   for key in "${!_ble_faces__@}"; do
     local name=${key#_ble_faces__}
     ble/color/g2gspec $((_ble_faces[key])); local gspec=$ret
     if [[ $opt_color ]]; then
       ble/color/iface2sgr $((key))
       gspec=$ret$gspec$_ble_term_sgr0
     fi
-    printf 'ble-color-setface %s %s\n' "$name" "$gspec"
+    printf '%s %s %s\n' "${sgr1}ble-color-setface$sgr0" "$sgr2$name$sgr0" "$gspec"
   done
 }
 

src/decode.sh

@@ -2189,17 +2189,17 @@ function ble/debug/keylog#start {
 function ble/debug/keylog#end {
   {
     ble/util/print '===== bytes ====='
-    printf '%s\n' "${_ble_debug_keylog_bytes[*]}"
+    ble/util/print "${_ble_debug_keylog_bytes[*]}"
     ble/util/print
     ble/util/print '===== chars ====='
     local ret; ble-decode-unkbd "${_ble_debug_keylog_chars[@]}"
     ble/string#split ret ' ' "$ret"
-    printf '%s\n' "${ret[*]}"
+    ble/util/print "${ret[*]}"
     ble/util/print
     ble/util/print '===== keys ====='
     local ret; ble-decode-unkbd "${_ble_debug_keylog_keys[@]}"
     ble/string#split ret ' ' "$ret"
-    printf '%s\n' "${ret[*]}"
+    ble/util/print "${ret[*]}"
     ble/util/print
   } | fold -w 40
 

src/edit.sh

@@ -7564,13 +7564,13 @@ function ble/widget/command-help.core {
     MANOPT= ble/bin/man "${command##*/}" 2>/dev/null && return 0
     # Note: $(man "${command##*/}") だと (特に日本語で) 正しい結果が得られない。
     # if local content=$(MANOPT= ble/bin/man "${command##*/}" 2>&1) && [[ $content ]]; then
-    #   builtin printf '%s\n' "$content" | ble/util/pager
+    #   ble/util/print "$content" | ble/util/pager
     #   return 0
     # fi
   fi
 
   if local content; content=$("$command" --help 2>&1) && [[ $content ]]; then
-    builtin printf '%s\n' "$content" | ble/util/pager
+    ble/util/print "$content" | ble/util/pager
     return 0
   fi
 
@@ -7790,7 +7790,7 @@ if [[ $bleopt_internal_suppress_bash_output ]]; then
       local line opts=:$1:
       while TMOUT= IFS= builtin read -r line; do
         if [[ $line == *[^$_ble_term_IFS]* ]]; then
-          builtin printf '%s\n' "$line" >> "$_ble_edit_io_fname2"
+          ble/util/print "$line" >> "$_ble_edit_io_fname2"
         fi
 
         if ble-edit/io/check-ignoreeof-message "$line"; then
@@ -7993,7 +7993,7 @@ function ble/widget/print {
 
   _ble_edit_line_disabled=1 ble/widget/.insert-newline
   ble/util/buffer.flush >&2
-  builtin printf '%s\n' "$message" >&2
+  ble/util/print "$message" >&2
 }
 function ble/widget/internal-command {
   ble-edit/content/clear-arg

src/history.sh

@@ -1324,8 +1324,8 @@ function ble/builtin/history/option:s {
     fi
     local tmp=$_ble_base_run/$$.history.tmp
     [[ $bleopt_history_share ]] ||
-      builtin printf '%s\n' "$cmd" >> "$histfile"
-    builtin printf '%s\n' "$cmd" >| "$tmp"
+      ble/util/print "$cmd" >> "$histfile"
+    ble/util/print "$cmd" >| "$tmp"
     builtin history -r "$tmp"
   else
     ble/history:bash/clear-background-load

src/util.sh

@@ -18,7 +18,7 @@
 ##       変数の設定内容を表示する
 ##
 function bleopt {
-  local error_flag=
+  local flags=
   local -a pvars=()
   if (($#==0)); then
     local var ip=0
@@ -28,22 +28,24 @@ function bleopt {
     done
   else
     local spec var type= value= ip=0 rex
-    pvars=()
     for spec; do
       if rex='^[_a-zA-Z0-9]+:='; [[ $spec =~ $rex ]]; then
         type=a var=${spec%%:=*} value=${spec#*:=}
       elif rex='^[_a-zA-Z0-9]+='; [[ $spec =~ $rex ]]; then
         type=ac var=${spec%%=*} value=${spec#*=}
       elif rex='^[_a-zA-Z0-9]+$'; [[ $spec =~ $rex ]]; then
         type=p var=$spec
+      elif [[ $spec == --help ]]; then
+        flags=H$flags
+        continue
       else
         ble/util/print "bleopt: unrecognized argument '$spec'" >&2
         continue
       fi
 
       var=bleopt_${var#bleopt_}
       if [[ $type == *c* && ! ${!var+set} ]]; then
-        error_flag=1
+        flags=E$flags
         ble/util/print "bleopt: unknown bleopt option \`${var#bleopt_}'" >&2
         continue
       fi
@@ -53,7 +55,7 @@ function bleopt {
         [[ ${!var+set} && ${!var} == "$value" ]] && continue
         if ble/is-function bleopt/check:"${var#bleopt_}"; then
           if ! bleopt/check:"${var#bleopt_}"; then
-            error_flag=1
+            flags=E$flags
             continue
           fi
         fi
@@ -64,7 +66,20 @@ function bleopt {
     done
   fi
 
-  if ((${#pvars[@]})); then
+  if [[ $flags == *H* ]]; then
+    ble/util/print-lines \
+      'usage: bleopt [NAME|NAME=VALUE|NAME:=VALUE]...' \
+      '    Set ble.sh options. Without arguments, this prints all the settings.' \
+      '' \
+      '  Options:' \
+      '    --help      Print this help.' \
+      '' \
+      '  Arguments:' \
+      '    NAME        Print the value of the option.' \
+      '    NAME=VALUE  Set the value to the option.' \
+      '    NAME:=VALUE Set or create the value to the option.'
+    return 0
+  elif ((${#pvars[@]})); then
     local q="'" Q="'\''" var
 
     # 着色
@@ -87,15 +102,15 @@ function bleopt {
           local ret; ble/string#quote-word "${!var}" sgrq="$sgr3"
           value=$ret
         fi
-        builtin printf '%s\n' "${sgr1}bleopt$sgr0 ${sgr2}${var#bleopt_}$sgr0=$value"
+        ble/util/print "${sgr1}bleopt$sgr0 ${sgr2}${var#bleopt_}$sgr0=$value"
       else
-        error_flag=1
-        builtin printf '%s\n' "bleopt: invalid ble option name '${var#bleopt_}'" >&2
+        flags=E$flags
+        ble/util/print "bleopt: invalid ble option name '${var#bleopt_}'" >&2
       fi
     done
   fi
 
-  [[ ! $error_flag ]]
+  [[ $flags != *E* ]]
 }
 
 function bleopt/declare/.handle-obsolete-option {
@@ -1323,10 +1338,22 @@ function blehook/.print {
     ble/is-array "$hookname" || continue
     builtin eval -- "${code//NAME/${hookname#_ble_hook_h_}}"
   done
-  builtin printf %s "$out"
+  ble/util/put "$out"
 }
 function blehook/.print-help {
-  ble/util/print 'usage: blehook hook_name+=shell-command'
+  ble/util/print-lines \
+    'usage: blehook [NAME[[=|+=|-=|-+=]COMMAND]]...' \
+    '    Add or remove hooks. Without arguments, this prints all the existing hooks.' \
+    '' \
+    '  Options:' \
+    '    --help      Print this help.' \
+    '' \
+    '  Arguments:' \
+    '    NAME            Print the corresponding hooks.' \
+    '    NAME=COMMAND    Set hook after removing the existing hooks.' \
+    '    NAME+=COMMAND   Add hook.' \
+    '    NAME-=COMMAND   Remove hook.' \
+    '    NAME-+=COMMAND  Add hook if the command is not registered.'
 }
 
 function blehook {
@@ -2678,14 +2705,14 @@ if ((_ble_bash>=40400)) && ble/util/msleep/.check-builtin-sleep; then
       shift
     done
     if [[ $flags == *h* ]]; then
-      builtin printf '%s\n' \
-              'usage: sleep NUMBER[SUFFIX]...' \
-              'Pause for the time specified by the sum of the arguments. SUFFIX is one of "s"' \
-              '(seconds), "m" (minutes), "h" (hours) or "d" (days).' \
-              '' \
-              'OPTIONS' \
-              '     --help    Show this help.' \
-              '     --version Show version.'
+      ble/util/print-lines \
+        'usage: sleep NUMBER[SUFFIX]...' \
+        'Pause for the time specified by the sum of the arguments. SUFFIX is one of "s"' \
+        '(seconds), "m" (minutes), "h" (hours) or "d" (days).' \
+        '' \
+        'OPTIONS' \
+        '     --help    Show this help.' \
+        '     --version Show version.'
     fi
     if [[ $flags == *v* ]]; then
       ble/util/print "sleep (ble) $BLE_VERSION"