Skip to content

Home

Jump to bottom
t9md edited this page Mar 1, 2017 · 24 revisions

Overview

narrow-ui

overview

Control bar

control-bar

Term and Roles

  • narrow-provider: Provide items to narrow and action to jump to item selected.
  • narrow-ui: in most case, it means narrow-editor.
    • handles user input and update item list.
    • manage narrow-editor and control-bar, syntax highlight grammar.
  • narrow-editor: text-editor where items are rendered and where you input narrow-query.

Specs

  • Provider provides items( collection of item ).
  • Basically all provider has to provide item which is openable as text file.
    • e.g. Executing command by narrowing command list by narrow-ui is out of scope of narrow.
    • Item has to have point field.
    • If provider is not bound to single file, item also must have filePath field.
  • Two kind of provider
    • boundToSingleFile provider: e.g. scan, fold, symbols.
      • Not show project and file header( since all items are from single file ).
      • Basically, this provider can detect non-saved change, and refresh items on did change buffer content.
        • symbols provider is exceptional, cannot detect change, need to save to make items up-to-date.
    • Not boundToSingleFile provider: e.g. search, atom-scan, git-diff-all.
      • Shows project and file header.
      • Basically, this provider can not detect non-saved change, and refresh items on buffer saved.
  • Provider have corresponding, dedicated narrow-ui, in other word narrow-ui is not shared by multiple provider.
  • narrow-ui is always bound to current active editor.
    • And sync cursor position of active-editor with items on narrow-editor.
  • narrow-editor must be normal text-editor.

Flow of startup

  1. User invoke narrow:scan
  2. Instantiate Scan provider and instantiate Ui to use for this provider.
  3. Open narrow-editor( Ui hold narrow-editor and control-bar etc..).

Narrow query

  • Used to filter items on narrow-editor.
  • You can input query on first line of narrow-editor.
  • Basically query is matched as-is( No regular expression support currently ).
  • Can chain multiple query separating by whilte-space.
    • e.g. foo bar means, select items matches foo and bar.
  • * is treated as wildcard, internally converted to .* regular expression.
    • To search * itself, use * solely separate it by space.
    • Or use double **. ( e.g. To match to string *hello use **hello as query).
  • ! is treated as negate, !foo means 'not matching foo'.
    • If config negateNarrowQueryByEndingExclamation set to true, you can also use foo!.
  • Query case sensitivity is configurable with config caseSensitivityForNarrowQuery.
    • Can override global setting on each provider if you want.
  • See also this issue

Built-in provider

scan

  • Scan current editor( use editor.scan under the hood )
  • It use first narrow query as search term( first word separated by white-spaces on query text ).
  • Rest of include and exclude(! starting word) queries are treated as normal filter query.
  • To make this exceptional query handling obvious by eye, use different syntax grammar highlight for first query(= scan term).

search

  • Search by ag( you need to install ag by yourself).
  • Need to install ag by yourself.

atom-scan

  • Similar to search but use Atom's atom.workspace.scan.

fold

  • Provide fold-starting rows as item.
  • Can change fold level to show up on narrow-editor by
    • narrow-ui:fold:increase-fold-level
    • narrow-ui:fold:decrease-fold-level

git-diff

  • Show git-diff for current active-editor. Info source is core git-diff package.

git-diff-all

  • Show all modified state file across project.
  • If you are comfortable with this provider, you don't need git-diff at all( like me ).

bookmarks

  • Info source is core bookmarks package
  • This is toy, I don't use bookmarks feature heavily.

symbols

  • Provide symbols for current file.
  • Useful to quick previewing function definition on same file.

project-symbols

  • Provide project-wide symbols information by reading tags file.

linter

  • Use message provided by linter package.

Provider specific configuration

directionToOpen

  • Possible value and short descriptions are here.
    • inherit: pick global setting.
    • right: default, no behavior change
    • right:never-use-previous-adjacent-pane: don't use previous adjacent pane( use only next adjacent )
    • right:always-new-pane:
    • down:
    • down:never-use-previous-adjacent-pane:
    • down:always-new-pane:

caseSensitivityForNarrowQuery

negateNarrowQueryByEndingExclamation

  • When true, foo! means "not matching foo" as like !foo means that.
  • Only select-files provider enabled by default. ( To exclude md file by md!).
    • This is better than !md keystroke.
    • Since user can confirm which files are excluded.
    • At the timing when query become md and before adding ending !.

autoPreview

  • When you move cursor on narrow-editor, item under cursor is automatically opened to preview.

autoPreviewOnQueryChange

  • When you input query and items on narrow-editor re-rendered, auto-preview first item.

closeOnConfirm

  • When true, close narrow-editor on confirmed by enter.
  • Set to false if you want keep narrow-editor open after confirmation.
    • Or you can use narrow-ui:confirm-keep-open as alternative.

revealOnStartCondition

Reveal closest item at startup.

  • Value can be
    • never: Never reveal
    • always: Always try to reveal
    • on-input: Reveal when initial query was provided via -by-current-word commands.
  • Each provider have different default value( opinionated ). So no global default.
    • Basic strategy to choose default value is below.
      • boundToSingleFile provider( scan, fold, symbols ) have on-input default
      • Other have always default( search, atom-scan, git-diff-all ).
Clone this wiki locally