visidata 2.11.dev0__py3-none-any.whl → 3.0__py3-none-any.whl

visidata/graph.py

@@ -1,6 +1,10 @@
-from visidata import *
+import math
 
-vd.option('color_graph_axis', 'bold', 'color for graph axis labels')
+from visidata import VisiData, Canvas, Sheet, Progress, BoundingBox, Point
+from visidata import vd, asyncthread, dispwidth, colors, clipstr
+
+vd.theme_option('color_graph_axis', 'bold', 'color for graph axis labels')
+vd.theme_option('disp_graph_tick_x', '╵', 'character for graph x-axis ticks')
 
 
 @VisiData.api
@@ -9,37 +13,67 @@ def numericCols(vd, cols):
 
 
 class InvertedCanvas(Canvas):
+    @asyncthread
+    def render_async(self):
+        self.plot_elements(invert_y=True)
+
+    def fixPoint(self, plotterPoint, canvasPoint):
+        'adjust visibleBox.xymin so that canvasPoint is plotted at plotterPoint'
+        self.visibleBox.xmin = canvasPoint.x - self.canvasW(plotterPoint.x-self.plotviewBox.xmin)
+        self.visibleBox.ymin = canvasPoint.y - self.canvasH(self.plotviewBox.ymax-plotterPoint.y)
+        self.refresh()
+
     def zoomTo(self, bbox):
         super().zoomTo(bbox)
-        self.fixPoint(Point(self.plotviewBox.xmin, self.plotviewBox.ymax), bbox.xymin)
-
-    def plotpixel(self, x, y, attr, row=None):
-        y = self.plotviewBox.ymax-y
-        self.pixels[y][x][attr].append(row)
+        self.fixPoint(Point(self.plotviewBox.xmin, self.plotviewBox.ymin),
+                      Point(bbox.xmin, bbox.ymax + 1/4*self.canvasCharHeight))
 
     def scaleY(self, canvasY):
-        'returns plotter y coordinate, with y-axis inverted'
-        plotterY = super().scaleY(canvasY)
-        return (self.plotviewBox.ymax-plotterY+4)
+        'returns a plotter y coordinate for a canvas y coordinate, with the y direction inverted'
+        return self.plotviewBox.ymax-round((canvasY-self.visibleBox.ymin)*self.yScaler)
 
-    def canvasH(self, plotterY):
-        return (self.plotviewBox.ymax-plotterY)/self.yScaler
+    def unscaleY(self, plotterY_inverted):
+        'performs the inverse of scaleY, returns a canvas y coordinate'
+        return (self.plotviewBox.ymax-plotterY_inverted)/self.yScaler + self.visibleBox.ymin
 
     @property
     def canvasMouse(self):
         p = super().canvasMouse
-        p.y = self.visibleBox.ymin + (self.plotviewBox.ymax-self.plotterMouse.y)/self.yScaler
+        if not p: return None
+        p.y = self.unscaleY(self.plotterMouse.y)
         return p
 
+    def calcTopCursorY(self):
+        'ymin for the cursor that will align its top with the top edge of the graph'
+        return self.visibleBox.ymax - self.cursorBox.h
+
+    def calcBottomCursorY(self):
+        # Shift by 1 plotter pixel, like with goTopCursorY for Canvas. But shift in the
+        # opposite direction, because the y-coordinate system is inverted.
+        'ymin for the cursor that will align its bottom with the bottom edge of the graph'
+        return self.visibleBox.ymin - (1/4 * self.canvasCharHeight)
+
+    def startCursor(self):
+        res = super().startCursor()
+        if not res: return None
+        # Since the y coordinates for plotting increase in the opposite
+        # direction from Canvas, the cursor has to be shifted.
+        self.cursorBox.ymin -= self.canvasCharHeight
 
 # provides axis labels, legend
 class GraphSheet(InvertedCanvas):
     def __init__(self, *names, **kwargs):
+        self.ylabel_maxw = 0
         super().__init__(*names, **kwargs)
 
         vd.numericCols(self.xcols) or vd.fail('at least one numeric key col necessary for x-axis')
         self.ycols or vd.fail('%s is non-numeric' % '/'.join(yc.name for yc in kwargs.get('ycols')))
 
+    def resetCanvasDimensions(self, windowHeight, windowWidth):
+        if self.left_margin < self.ylabel_maxw:
+            self.left_margin = self.ylabel_maxw
+        super().resetCanvasDimensions(windowHeight, windowWidth)
+
     @asyncthread
     def reload(self):
         nerrors = 0
@@ -62,10 +96,10 @@ class GraphSheet(InvertedCanvas):
                     attr = self.plotColor(k)
                     self.point(graph_x, graph_y, attr, row)
                     nplotted += 1
-                except Exception:
+                except Exception as e:
                     nerrors += 1
-                    if options.debug:
-                        raise
+                    if vd.options.debug:
+                        vd.exceptionCaught(e)
 
 
         vd.status('loaded %d points (%d errors)' % (nplotted, nerrors))
@@ -97,6 +131,26 @@ class GraphSheet(InvertedCanvas):
         srccol = self.ycols[0]
         return srccol.format(srccol.type(amt))
 
+    def formatXLabel(self, amt):
+        if self.xzoomlevel < 1:
+            labels = []
+            for xcol in self.xcols:
+                if vd.isNumeric(xcol):
+                    col_amt = float(amt) if xcol.type is int else xcol.type(amt)
+                else:
+                    continue
+                labels.append(xcol.format(col_amt))
+            return ','.join(labels)
+        else:
+            return self.formatX(amt)
+
+    def formatYLabel(self, amt):
+        srccol = self.ycols[0]
+        if srccol.type is int and self.yzoomlevel < 1:
+            return srccol.format(float(amt))
+        else:
+            return self.formatY(amt)
+
     def parseX(self, txt):
         return self.xcols[0].type(txt)
 
@@ -104,26 +158,39 @@ class GraphSheet(InvertedCanvas):
         return self.ycols[0].type(txt)
 
     def add_y_axis_label(self, frac):
-        txt = self.formatY(self.visibleBox.ymin + frac*self.visibleBox.h)
+        txt = self.formatYLabel(self.visibleBox.ymin + frac*self.visibleBox.h)
+        w = (dispwidth(txt)+1)*2
+        if self.ylabel_maxw < w:
+            self.ylabel_maxw = w
 
         # plot y-axis labels on the far left of the canvas, but within the plotview height-wise
-        attr = colors.color_graph_axis
-        self.plotlabel(0, self.plotviewBox.ymin + (1.0-frac)*self.plotviewBox.h, txt, attr)
+        self.plotlabel(0, self.plotviewBox.ymin + (1.0-frac)*self.plotviewBox.h, txt, 'graph_axis')
 
     def add_x_axis_label(self, frac):
-        txt = self.formatX(self.visibleBox.xmin + frac*self.visibleBox.w)
+        txt = self.formatXLabel(self.visibleBox.xmin + frac*self.visibleBox.w)
+        tick = vd.options.disp_graph_tick_x or ''
 
         # plot x-axis labels below the plotviewBox.ymax, but within the plotview width-wise
-        attr = colors.color_graph_axis
-        xmin = self.plotviewBox.xmin + frac*self.plotviewBox.w
-        if frac == 1.0:
-            # shift rightmost label to be readable
-            xmin -= max(len(txt)*2 - self.rightMarginPixels+1, 0)
-
-        self.plotlabel(xmin, self.plotviewBox.ymax+4, txt, attr)
+        x = self.plotviewBox.xmin + frac*self.plotviewBox.w
+
+        if frac < 1.0:
+            txt = tick + txt
+        else:
+            right_margin = self.plotwidth - 1 - self.plotviewBox.xmax
+            if (len(txt)+len(tick))*2 <= right_margin:
+                txt = tick + txt
+            else:
+                # shift rightmost label to be left of its tick
+                x -= len(txt)*2
+                if len(tick) == 0:
+                    x += 1
+                txt = txt + tick
+
+        self.plotlabel(x, self.plotviewBox.ymax+4, txt, 'graph_axis')
 
     def createLabels(self):
         self.gridlabels = []
+        self.ylabel_maxw = self.leftMarginPixels
 
         # y-axis
         self.add_y_axis_label(1.00)
@@ -143,18 +210,18 @@ class GraphSheet(InvertedCanvas):
         # TODO: grid lines corresponding to axis labels
 
         xname = ','.join(xcol.name for xcol in self.xcols if vd.isNumeric(xcol)) or 'row#'
-        xname, _ = clipstr(xname, self.leftMarginPixels//2-2)
-        self.plotlabel(0, self.plotviewBox.ymax+4, xname+'»', colors.color_graph_axis)
+        xname, _ = clipstr(xname, self.left_margin//2-2)
+        self.plotlabel(0, self.plotviewBox.ymax+4, xname+'»', 'graph_axis')
 
 
 Sheet.addCommand('.', 'plot-column', 'vd.push(GraphSheet(sheet.name, "graph", source=sheet, sourceRows=rows, xcols=keyCols, ycols=numericCols([cursorCol])))', 'plot current numeric column vs key columns; numeric key column is used for x-axis, while categorical key columns determine color')
 Sheet.addCommand('g.', 'plot-numerics', 'vd.push(GraphSheet(sheet.name, "graph", source=sheet, sourceRows=rows, xcols=keyCols, ycols=numericCols(nonKeyVisibleCols)))', 'plot a graph of all visible numeric columns vs key columns')
 
 # swap directions of up/down
-InvertedCanvas.addCommand(None, 'go-up', 'sheet.cursorBox.ymin += cursorBox.h', 'move cursor up by its height')
-InvertedCanvas.addCommand(None, 'go-down', 'sheet.cursorBox.ymin -= cursorBox.h', 'move cursor down by its height')
-InvertedCanvas.addCommand(None, 'go-top', 'sheet.cursorBox.ymin = visibleBox.ymax', 'move cursor to top edge of visible canvas')
-InvertedCanvas.addCommand(None, 'go-bottom', 'sheet.cursorBox.ymin = visibleBox.ymin', 'move cursor to bottom edge of visible canvas')
+InvertedCanvas.addCommand(None, 'go-up', 'if cursorBox: sheet.cursorBox.ymin += cursorBox.h', 'move cursor up by its height')
+InvertedCanvas.addCommand(None, 'go-down', 'if cursorBox: sheet.cursorBox.ymin -= cursorBox.h', 'move cursor down by its height')
+InvertedCanvas.addCommand(None, 'go-top',  'if cursorBox: sheet.cursorBox.ymin = sheet.calcTopCursorY()', 'move cursor to top edge of visible canvas')
+InvertedCanvas.addCommand(None, 'go-bottom', 'if cursorBox: sheet.cursorBox.ymin = sheet.calcBottomCursorY()', 'move cursor to bottom edge of visible canvas')
 InvertedCanvas.addCommand(None, 'go-pagedown', 't=(visibleBox.ymax-visibleBox.ymin); sheet.cursorBox.ymin -= t; sheet.visibleBox.ymin -= t; sheet.refresh()', 'move cursor down to next visible page')
 InvertedCanvas.addCommand(None, 'go-pageup', 't=(visibleBox.ymax-visibleBox.ymin); sheet.cursorBox.ymin += t; sheet.visibleBox.ymin += t; sheet.refresh()', 'move cursor up to previous visible page')
 
@@ -185,3 +252,8 @@ vd.addGlobals({
     'GraphSheet': GraphSheet,
     'InvertedCanvas': InvertedCanvas,
 })
+
+vd.addMenuItems('''
+    Plot > Graph > current column > plot-column
+    Plot > Graph > all numeric columns > plot-numerics
+''')

visidata/guide.py

@@ -0,0 +1,180 @@
+'''
+# A Guide to VisiData Guides
+Each guide shows you how to use a particular feature in VisiData. Gray guides have not been written yet. We love contributions: [:onclick https://visidata.org/docs/api/guides]https://visidata.org/docs/api/guides[/].
+
+- [:keystrokes]Up/Down[/] to move the row cursor
+- [:keystrokes]Enter[/] to view a topic
+'''
+import re
+
+from visidata import vd, BaseSheet, Sheet, ItemColumn, Column, VisiData, ENTER, RowColorizer, AttrDict, MissingAttrFormatter
+from visidata import wraptext
+
+guides_list = '''
+GuideIndex ("A Guide to VisiData Guides (you are here)")
+HelpGuide ("Where to Start and How to Quit")  # manpage; ask for patreon
+MenuGuide ("The VisiData Menu System")
+CommandsSheet ("How to find the command you want run")
+
+#  real barebones basics
+MovementGuide ("Movement and Search")
+SortGuide ("Sorting")
+TypesSheet ("The basic type system")
+CommandLog  ("Undo and Replay")
+
+#  rev this thing up
+
+SelectionGuide ("Selecting and filtering") # stu|, and variants; filtering with dup-sheet; g prefix often refers to selected rowset
+SheetsSheet  ("The Sheet Stack")
+ColumnsSheet ("Columns: the only way to fly")
+StatusesSheet ("Revisit old status messages")
+SidebarSheet ("Dive into the sidebar")
+SaversGuide ("Saving Data")  # talk about options.overwrite + ro here
+
+ErrorsSheet ("What was that error?")
+ModifyGuide ("Adding, Editing, Deleting Rows")
+
+# the varieties of data experience
+
+SlideGuide ("Sliding rows and columns around")
+ExprGuide ("Compute Python over every row")
+JoinGuide ("Joining multiple sheets together")
+DescribeSheet ("Basic Statistics (min/max/mode/median/mean)")
+AggregatorsSheet ("Aggregations like sum, mean, and distinct")
+FrequencyTable ("Frequency Tables are how you GROUP BY")
+PivotGuide ("Pivot Tables are just Frequency Tables with more columns")
+MeltGuide ("Melt is just Unpivot")
+JsonGuide ("Some special features for JSON") # with expand/contract, unfurl
+RegexGuide ("Matching and Transforming Strings with Regex")
+GraphSheet ("Basic scatterplots and other graphs")
+WindowFunctionGuide ("Perform operations on groups of rows")
+
+# for the frequent user
+OptionsSheet ("Options and Settings")
+ClipboardGuide ("Copy and Paste Data via the Clipboard")
+DirSheet ("Browsing the local filesystem")
+FormatsSheet ("What can you open with VisiData?")
+SplitpaneGuide ("Split VisiData into two panes")
+ThemesSheet ("Change Interface Theme")
+ColorSheet ("See available colors")
+MacrosSheet ("Recording macros")
+MemorySheet ("Making note of certain values")
+
+# advanced usage and developers
+
+ThreadsSheet ("Threads past and present")
+PyobjSheet ("Inspecting internal Python objects")
+
+#  appendices
+
+InputEditorGuide ("Using the builtin line editor")
+'''
+
+vd.guides = {}  # name -> guidecls
+
+@VisiData.api
+def addGuide(vd, name, guidecls):
+    vd.guides[name] = guidecls
+
+@VisiData.api
+class GuideIndex(Sheet):
+    guide = __doc__
+
+    rowtype = 'guides' # rowdef: list(guide number, guide name, topic description, points, max_points)
+    columns = [
+        ItemColumn('n', 0, type=int),
+        ItemColumn('name', 1, width=0),
+        ItemColumn('topic', 2, width=60),
+    ]
+    colorizers = [
+            RowColorizer(7, 'color_guide_unwritten', lambda s,c,r,v: r and r[1] not in vd.guides)
+            ]
+    def iterload(self):
+        i = 0
+        for line in guides_list.splitlines():
+            m = re.search(r'(\w+?) \("(.*)"\)', line)
+            if m:
+                yield [i] + list(m.groups())
+                i += 1
+
+    def openRow(self, row):
+        name = row[1]
+        return vd.getGuide(name)
+
+class OptionHelpGetter:
+    'For easy and consistent formatting in sidebars and helpstrings, use {vd.options.help.opt_name}.'
+    def __getattr__(self, optname):
+        opt = vd.options._get(optname, 'default')
+        return f'[:onclick options-sheet {optname}]`{optname}`[/]: to {opt.helpstr} (default: {opt.value})'
+
+
+class CommandHelpGetter:
+    'For easy and consistent formatting in sidebars and helpstrings, use {vd.commands.help.long_name}.'
+    def __init__(self, cls):
+        self.cls = cls
+        self.helpsheet = vd.HelpSheet()
+        self.helpsheet.ensureLoaded()
+
+    def __getattr__(self, k):
+        longname = k.replace('_', '-')
+        binding = self.helpsheet.revbinds.get(longname, [None])[0]
+        # cmddict has a SheetClass associated with each command
+        # go through all the parents of the Sheet type, to look for the command
+        for cls in self.cls.superclasses():
+            cmd = self.helpsheet.cmddict.get((cls.__name__, longname), None)
+            if cmd:
+                break
+        if not cmd:
+            return ''
+        if 'input' in cmd.execstr.lower():
+            inputtype = 'input'
+            m = re.search(r'type="(\w*)"', cmd.execstr, re.IGNORECASE)
+            if not m:
+                m = re.search(r'input(\w*)\("', cmd.execstr, re.IGNORECASE)
+            if m:
+                inputtype = m.groups()[0].lower()
+                binding += f'[:45] {inputtype}[/]'
+
+        helpstr = cmd.helpstr
+        return f'`{binding}` (`{longname}`) to {helpstr}'
+
+
+class GuideSheet(Sheet):
+    rowtype = 'lines'
+    filetype = 'guide'
+    columns = [
+            ItemColumn('linenum', 0, type=int, width=0),
+            ItemColumn('guide', 1, width=80, displayer='full'),
+            ]
+    precious = False
+    guide_text = ''
+    sheettype = Sheet
+
+    def iterload(self):
+        winWidth = 78
+        helper = AttrDict(commands=CommandHelpGetter(self.sheettype),
+                          options=OptionHelpGetter())
+        guidetext = MissingAttrFormatter().format(self.guide_text, help=helper, vd=vd)
+        for startingLine, text in enumerate(guidetext.splitlines()):
+            text = text.strip()
+            if text:
+                for i, (L, _) in enumerate(wraptext(str(text), width=winWidth)):
+                    yield [startingLine+i+1, L]
+            else:
+                yield [startingLine+1, text]
+
+
+
+@VisiData.api
+def getGuide(vd, name): # -> GuideSheet()
+    if name in vd.guides:
+        return vd.guides[name]()
+    vd.warning(f'no guide named {name}')
+
+BaseSheet.addCommand('', 'open-guide-index', 'vd.push(GuideIndex("VisiData_Guide"))', 'open VisiData guides table of contents')
+
+vd.addMenuItems('''
+        Help > VisiData Feature Guides > open-guide-index
+''')
+
+vd.addGlobals({'GuideSheet':GuideSheet, "CommandHelpGetter": CommandHelpGetter, "OptionHelpGetter": OptionHelpGetter})

visidata/help.py

@@ -1,10 +1,35 @@
 import functools
 import collections
-from pkg_resources import resource_filename
 
-from visidata import *
+from visidata import VisiData, MetaSheet, ColumnAttr, Column, BaseSheet, VisiDataMetaSheet, SuspendCurses
+from visidata import vd, asyncthread, ENTER, drawcache, AttrDict
 
-vd.show_help = False
+vd.option('disp_help', 2, 'show help panel during input')
+
+@BaseSheet.api
+def hint_basichelp(sheet):
+    return 0, '`Alt+[:underline]H[/]` to open the [:underline]H[/]elp menu'
+
+
+@VisiData.api
+def iterMenuPaths(vd, item=None, menupath=[]):
+    'Generate (longname, menupath).'
+    if item is None:
+        item = vd.menus
+
+    if isinstance(item, (list, tuple)):
+        for m in item:
+            yield from vd.iterMenuPaths(m, menupath)
+    elif item.longname:
+        yield item.longname, ' > '.join(menupath+[item.title])
+    else:
+        yield from vd.iterMenuPaths(item.menus, menupath+[item.title])
+
+
+@VisiData.property
+@drawcache
+def menuPathsByLongname(vd):
+    return dict(vd.iterMenuPaths())
 
 
 @VisiData.api
@@ -16,10 +41,12 @@ class HelpSheet(MetaSheet):
 
     columns = [
         ColumnAttr('sheet'),
+        ColumnAttr('module'),
         ColumnAttr('longname'),
+        Column('menupath', width=0, cache=True, getter=lambda col,row: vd.menuPathsByLongname[row.longname]),
         Column('keystrokes', getter=lambda col,row: col.sheet.revbinds.get(row.longname, [None])[0]),
-        Column('all_bindings', width=0, getter=lambda col,row: list(set(col.sheet.revbinds.get(row.longname, [])))),
-        Column('description', getter=lambda col,row: col.sheet.cmddict[(row.sheet, row.longname)].helpstr),
+        Column('all_bindings', width=0, cache=True, getter=lambda col,row: list(set(col.sheet.revbinds.get(row.longname, [])))),
+        Column('description', width=40, getter=lambda col,row: col.sheet.cmddict[(row.sheet, row.longname)].helpstr),
         ColumnAttr('execstr', width=0),
         Column('logged', width=0, getter=lambda col,row: vd.isLoggableCommand(row.longname)),
     ]
@@ -54,73 +81,69 @@ class HelpSheet(MetaSheet):
         return revbinds
 
 
-@VisiData.api
-@asyncthread
-def help_search(vd, sheet, regex):
-    vs = HelpSheet(source=None)
-    vs.rows = []  # do not trigger push reload
-    vd.push(vs)   # push first, then reload
-    vd.sync(vs.reload())
-
-    # find rows matching regex on original HelpSheet
-    rowidxs = list(vd.searchRegex(vs, regex=regex, columns="visibleCols"))
-
-    # add only matching rows
-    allrows = vs.rows
-    vs.rows = []
-    for rowidx in rowidxs:
-        vs.addRow(allrows[rowidx])
-
-
 class HelpPane:
     def __init__(self, name):
+        import visidata
         self.name = name
         self.scr = None
         self.parentscr = None
         self.amgr = visidata.AnimationMgr()
 
-    def draw(self, scr, x=None, y=None):
+    @property
+    def width(self):
+        return self.amgr.maxWidth
+
+    @property
+    def height(self):
+        return self.amgr.maxHeight
+
+    def draw(self, scr, x=None, y=None, **kwargs):
         if not scr: return
-        if not vd.show_help:
-            if self.scr:
-                self.scr.erase()
-                self.scr.refresh()
-                self.scr = None
-            return
+#        if vd.options.disp_help <= 0:
+#            if self.scr:
+#                self.scr.erase()
+#                self.scr.refresh()
+#                self.scr = None
+#            return
         if y is None: y=0  # show at top of screen by default
         if x is None: x=0
+        hneeded = self.amgr.maxHeight+3
+        wneeded = self.amgr.maxWidth+4
+        scrh, scrw = scr.getmaxyx()
         if not self.scr or scr is not self.parentscr:  # (re)allocate help pane scr
             if y >= 0:
-                if y+self.amgr.maxHeight+3 < scr.getmaxyx()[0]:
+                if y+hneeded < scrh:
                     yhelp = y+1
                 else:
-                    yhelp = y-self.amgr.maxHeight-3
+                    hneeded = max(0, min(hneeded, y-1))
+                    yhelp = y-hneeded
             else:  # y<0
-                yhelp = scr.getmaxyx()[0]-self.amgr.maxHeight-4
+                yhelp = max(0, scrh-hneeded-1)
 
             if x >= 0:
-                if x+self.amgr.maxWidth+4 < scr.getmaxyx()[1]:
+                if x+wneeded < scrw:
                     xhelp = x+1
                 else:
-                    xhelp = x-self.amgr.maxWidth-4
+                    wneeded = max(0, min(wneeded, x-1))
+                    xhelp = x-wneeded
             else:  # x<0
-                xhelp = scr.getmaxyx()[1]-self.amgr.maxWidth-5
+                xhelp = max(0, scrh-wneeded-1)
 
-            self.scr = scr.derwin(self.amgr.maxHeight+3, self.amgr.maxWidth+4, yhelp, xhelp)
+            self.scr = vd.subwindow(scr, xhelp, yhelp, wneeded, hneeded)
             self.parentscr = scr
 
         self.scr.erase()
         self.scr.box()
-        self.amgr.draw(self.scr, y=1, x=2)
+        self.amgr.draw(self.scr, y=1, x=2, **kwargs)
         self.scr.refresh()
 
 
 @VisiData.api
 @functools.lru_cache(maxsize=None)
-def getHelpPane(vd, name, module='vdplus'):
+def getHelpPane(vd, name, module='visidata') -> HelpPane:
     ret = HelpPane(name)
     try:
-        ret.amgr.load(name, Path(resource_filename(module,'ddw/'+name+'.ddw')).open_text(encoding='utf-8'))
+        ret.amgr.load(name, (vd.pkg_resources_files(module)/f'ddw/{name}.ddw').open(encoding='utf-8'))
         ret.amgr.trigger(name, loop=True)
     except FileNotFoundError as e:
         vd.debug(str(e))
@@ -135,23 +158,31 @@ def getHelpPane(vd, name, module='vdplus'):
 def openManPage(vd):
     import os
     with SuspendCurses():
-        if os.system(' '.join(['man', resource_filename(__name__, 'man/vd.1')])) != 0:
-            vd.push(TextSheet('man_vd', source=Path(resource_filename(__name__, 'man/vd.txt'))))
+        module_path = vd.pkg_resources_files(__name__.split('.')[0])
+        if os.system(' '.join(['man', str(module_path/'man/vd.1')])) != 0:
+            vd.push(TextSheet('man_vd', source=module_path/'man/vd.txt'))
 
 
 # in VisiData, g^H refers to the man page
 BaseSheet.addCommand('g^H', 'sysopen-help', 'openManPage()', 'Show the UNIX man page for VisiData')
 BaseSheet.addCommand('z^H', 'help-commands', 'vd.push(HelpSheet(name + "_commands", source=sheet, revbinds={}))', 'list commands and keybindings available on current sheet')
 BaseSheet.addCommand('gz^H', 'help-commands-all', 'vd.push(HelpSheet("all_commands", source=None, revbinds={}))', 'list commands and keybindings for all sheet types')
-BaseSheet.addCommand(None, 'help-search', 'help_search(sheet, input("help: "))', 'search through command longnames with search terms')
 
 BaseSheet.bindkey('KEY_F(1)', 'sysopen-help')
 BaseSheet.bindkey('zKEY_F(1)', 'help-commands')
 BaseSheet.bindkey('zKEY_BACKSPACE', 'help-commands')
+BaseSheet.bindkey('gKEY_BACKSPACE', 'sysopen-help')
 
-HelpSheet.addCommand(ENTER, 'exec-command', 'quit(sheet); draw_all(); activeStack[0].execCommand(cursorRow.longname)', 'execute command on undersheet')
+HelpSheet.addCommand(None, 'exec-command', 'quit(sheet); draw_all(); activeStack[0].execCommand(cursorRow.longname)', 'execute command on undersheet')
 BaseSheet.addCommand(None, 'open-tutorial-visidata', 'launchBrowser("https://jsvine.github.io/intro-to-visidata/")', 'open https://jsvine.github.io/intro-to-visidata/')
 
 vd.addMenuItem("Help", "VisiData tutorial", 'open-tutorial-visidata')
 vd.addMenuItem("Help", 'Sheet commands', 'help-commands')
 vd.addMenuItem("Help", 'All commands', 'help-commands-all')
+
+vd.addGlobals(HelpSheet=HelpSheet)
+
+vd.addMenuItems('''
+    Help > Quick reference > sysopen-help
+    Help > Command list > help-commands
+''')

visidata/hint.py

@@ -0,0 +1,39 @@
+import collections
+
+from visidata import vd, BaseSheet
+
+
+@BaseSheet.lazy_property
+def prevHints(sheet):
+    return collections.defaultdict(int)
+
+
+@BaseSheet.api
+def getHint(sheet, *args, **kwargs) -> str:
+    funcs = [getattr(sheet, x) for x in dir(sheet) if x.startswith('hint_')]
+    results = []
+    hints = sheet.prevHints
+    for f in funcs:
+        try:
+            r = f(*args, **kwargs)
+            if r:
+                if isinstance(r, dict):
+                    n = r.get('_relevance', 1)
+                    v = r
+                elif isinstance(r, tuple):
+                    n, v = r
+                else:
+                    n = 1
+                    v = r
+
+                if v not in sheet.prevHints:
+                    results.append((n, v))
+                    sheet.prevHints[v] += 1
+        except Exception as e:
+            vd.debug(f'{f.__name__}: {e}')
+
+    if results:
+        return sorted(results, reverse=True)[0][1]
+
+
+vd.addCommand('', 'help-hint', 'status(getHint() or pressMenu("Help"))', 'get context-dependent hint on what to do next')