Add group option hint

With custom changers, the cycle result might not obviously explain its
origin. This option let user to add a static "hint" for each group
item. Used in select UI or conflict UI, to help user see more
information of the item.

Author: bootleq

CHANGES.md

@@ -11,6 +11,8 @@ CHANGES
 
 * Add `naming` group option, cycle between naming conventions.
 
+* Add `hints` group option, display a static hint for each item in select or conflict UI.
+
 * `sub_pairs` now supports using an identical character on both begin and end sides.
 
 * `Cycle()` and `CycleSelect()` functions now accept extra groups argument,

autoload/cycle.vim

@@ -18,6 +18,7 @@
 "   naming
 "   year
 "   cond
+"   hints
 "
 " Sub options for 'regex':
 "   to
@@ -113,9 +114,12 @@ function! cycle#select(class_name, ...) "{{{
 
   let options = []
   for match in matches
+    let hints = get(match.group.options, 'hints', [])
+    let hint = empty(hints) ? '' : get(hints, match.index)
     call add(options, {
           \   "group_name": get(match.group.options, 'name', ''),
-          \   "text":       match.pairs.after.text
+          \   "text":       match.pairs.after.text,
+          \   "hint":       hint,
           \ })
   endfor
 
@@ -269,9 +273,12 @@ function! s:conflict(ctx) "{{{
 
   let options = []
   for match in matches
+    let hints = get(match.group.options, 'hints', [])
+    let hint = empty(hints) ? '' : get(hints, match.index)
     call add(options, {
           \   "group_name": get(match.group.options, 'name', ''),
-          \   "text":       match.pairs.after.text
+          \   "text":       match.pairs.after.text,
+          \   "hint":       hint,
           \ })
   endfor
 

autoload/cycle/select.vim

@@ -1,5 +1,6 @@
 let s:funcs = {}
 let s:loaders = {}
+let s:hint_pad = 4
 
 
 " Select UI Loaders: {{{
@@ -64,13 +65,17 @@ function! s:open_inputlist(options) "{{{
   let index = 0
   let candidates = []
   let max_length = max(map(copy(a:options), 'strlen(v:val.text)'))
+  let max_hint_len = max(map(copy(a:options), 'strlen(v:val.hint)'))
+  let hint_pad = max_hint_len > 0 ? s:hint_pad : 0
   for option in a:options
     let group = get(option, 'group_name', '')
     let line = printf(
-          \   '%2S => %-*S %S',
+          \   '%2S => %-*S ' . repeat(' ', hint_pad) . ' %-*S %S',
           \   index + 1,
           \   max_length,
           \   option.text,
+          \   max_hint_len,
+          \   option.hint,
           \   len(group) ? printf(' (%s)', group) : ''
           \ )
     call add(candidates, line)
@@ -98,14 +103,19 @@ function! s:open_confirm(options) "{{{
   let captions = []
   let candidates = []
   let max_length = max(map(copy(a:options), 'strlen(v:val.text)'))
+  let max_hint_len = max(map(copy(a:options), 'strlen(v:val.hint)'))
+  let hint_pad = max_hint_len > 0 ? s:hint_pad : 0
+
   for option in a:options
     let caption = nr2char(char2nr('A') + index)
     let group = get(option, 'group_name', '')
     let line = printf(
-          \   ' %2S) => %-*S %S',
+          \   ' %2S) => %-*S ' . repeat(' ', hint_pad) . ' %-*S %S',
           \   caption,
           \   max_length,
           \   option.text,
+          \   max_hint_len,
+          \   option.hint,
           \   len(group) ? printf(' (%s)', group) : ''
           \ )
     call add(candidates, line)

doc/cycle.txt

@@ -584,6 +584,18 @@ By default no options are set.
       \   [['==', '!='], { 'cond': function('s:not_lua_context') }],
       \ ]
 <
+"hints"             List (default: none) ~
+
+  UI hint for each item.
+  Will be displayed in |CycleSelect()| or a conflict prompt. The list contains
+  string values, each corresponding to a group item. >
+      \   [['snake_case', 'SCREAMING_SNAKE_CASE'],
+      \     {'hints': ['snake_case', 'MACRO_CASE'}]}],
+< results in select UI like: >
+      Cycle to:
+        A) => foo_bar_baz      snake_case
+        B) => FOO_BAR_BAZ      MACRO_CASE
+<
 ------------------------------------------------------------------------------
 Phased Search                                            *cycle-phased-search*
 

lua/vim_cycle/init.lua

@@ -1,4 +1,5 @@
 local M = {}
+local hint_pad_size = 4
 
 local make_select_options = function(options)
   local max_length = math.max(
@@ -8,7 +9,21 @@ local make_select_options = function(options)
       end, options)
     )
   )
-  local format_str = string.format("%%-%dS", max_length)
+
+  local max_hint_length = math.max(
+    unpack(
+      vim.tbl_map(function(opt)
+        return string.len(opt.hint)
+      end, options)
+    )
+  )
+
+  local hint_pad = ''
+  if max_hint_length > 0 then
+    hint_pad = string.rep(' ', hint_pad_size)
+  end
+
+  local format_str = string.format("%%-%dS" .. hint_pad .. " %%-%dS", max_length, max_hint_length)
 
   local select_options = {
     prompt = 'Cycle to:',
@@ -20,7 +35,7 @@ local make_select_options = function(options)
         group = ''
       end
 
-      return vim.fn.printf(format_str, opt.text) .. group
+      return vim.fn.printf(format_str, opt.text, opt.hint) .. group
     end,
   }