User Interface

Stacks Image 52873

Search Form Overview

For a basic search, follow steps 1, 2 and 3:

Stacks Image 52879

Search Form Detail

Search In

Search Location

Path of the folder you want to search

Search will include subfolders.

 

Examples


/

To search your whole machine

­­

/Users/fredbloggs

To search this user's files

 

Shortcuts

  +O for Open Folder dialog

 

  +; for tab-completion

         Continue typing to filter the list

         Tab or / to step through completions

         / to update completion list with subdirectories

         Esc to dismiss completion list

         Enter to accept completion and dismiss the list

                       

^+P to change Search In folder to parent

File Contains

Spotlight pre-search

Usually left empty.

If a search isn't fast enough, you can often tweak the Spotlight pre-search query in this box to make it faster.

 

Searches only look in files matched by Spotlight pre-search

  •  Leave box empty for automatic Spotlight pre-search, or

  •  Enter your own Spotlight pre-search, which must be whole words or numbers (no symbols)

     (E.g. a variable or library name used in target files), or

  •  Turn off 'Use Spotlight' in the Search menu - for a slower exhaustive search that walks the filesystem.

 

Examples

 

-Leave it empty-

Leave File Contains empty for an automatic Spotlight pre-search using text from your Line Contains pattern.   Search will include only files that Spotlight says contain relevant text.  This speeds up most queries, but misses files that Spotlight doesn't index.

 

QMessageBox warning

Only search files that Spotlight says contain the word QMessageBox and the word warning

 

PyQt4 OR PyQt5

Only search files that Spotlight says contain either the word PyQt4 or the word PyQt5. The OR keyword must be uppercase. OR applies only to the nearest word (or symbol character) either side unless you use quotes - see below.

Advanced Search

  •  If Advanced Search is off, all symbols just match themselves.

  •  If Advanced Search is on, the symbols - * and " have special meanings

     (or you can set different symbols in Preferences)

  •  Advanced Search can be turned on and off from the Search menu. 

 

Advanced Search Examples

 

Popen  -subprocess

To exclude files from search use minus sign - prefix - Only search files that Spotlight says contain the word Popen, and don't contain the word subprocess

 

lam*da

To match partial words, use asterisk * as wildcard  - Only search files that Spotlight says contain words starting lam and ending da. 

 

"QMessageBox.warning"

Use double quotes " for phrase search - Only search files containing a specific token sequence. E.g. The word QMessageBox then a dot . then the word warning 

 

"self.x" OR "self.y"

Use double quotes " for OR with compound names - Search files containing self.x or self.y

Tips

  •  You can often speed up searches by putting an uncommon library or variable name in File Contains.

  •  Using a wildcard at the front of a word makes Spotlight pre-search slow.

  •  Phrase searches aren't sensitive to whitespace

  •  It's a good idea to change Advanced Search symbols to non-ASCII versions.  See app Preferences

 

Shortcuts 

When File Contains box is selected, you can toggle its case sensitivity with ^+C

Path Contains

Filter files by fullpath

Often just the extension of the files you want to search. 

If your Search In folder contains irrelevant files, use this box to exclude them.

 

Searches only look in files whose fullpath contains the text you put in this box

  •  If you give multiple text fragments, the fullpath must match them all. 

  •  To include all files, leave the box empty.

  •  Text fragments that start with dot . are assumed to specify file extension, others match anywhere in the path or filename

 

Examples

 

.py  /Dropbox/

Only search files whose extension is .py AND whose path contains a folder called Dropbox

 

name:build.x

name: operator matches whole filename explicitly - Search only files called build.x

 

.py OR conda 

Search files whose extension is .py OR whose path or filename contains "conda" (e.g. files within folder /Anaconda/)The OR keyword must be uppercase.

 

.c OR .h

Search files whose extension is .c OR .h

Advanced Search

  •  If Advanced Search is off, all symbols just match themselves.

  •  If Advanced Search is on, the symbols - * and " have special meanings

     (or you can set different symbols in Preferences)

  •  Advanced Search can be turned on and off from the Search menu. 

 

Advanced Search Examples

 

"/User Information/"    

To match text containing spaces, use double quotes " - Only search files whose path includes the folder  /User Information/

 

.c /Dropbox/  -bak      

To exclude files use minus sign - prefix - Only search C source files in folder Dropbox that don't have 'bak' in the path or filename.

 

-"/Deleted Users/"      

Exclude files with paths that match the text fragment  /Deleted Users/

 

-/*example*/ .m

To match partial file or folder names, use asterisk * as wildcard - Match .m files in any folder that doesn't have example in its name

 

 

-.py          

Exclude files with extension .py

 

 

.c*

Match files whose extension starts .c  such as .c files and .cpp files

 

 

name:README*            

Match README files whether or not they have an extension

 Tips

  •  Path Contains works with text fragments instead of tokens, so:

       -  You don't need to use whole words

       -  You don't need quotes unless the fragment has spaces

       -  Wildcard * matches any sequence of characters except /

  •  The order of text fragments isn't significant.

  •  It's a good idea to change Advanced Search symbols to non-ASCII versions.  See app Preferences

 

Shortcuts 

When Path Contains box is selected, use shortcuts to turn its options on and off:

  • Switch between Simple Search Syntax and Regex with ^+R

  • Toggle case sensitivity with ^+C

Line Contains

Internet-style search query, to match lines of code

Symbols and whole words from the lines you want to find. 

This is the main search box.         

 

Lines must match everything you put in this box, but will match in any order (unless you tick the Order box)

 

Examples

To match this line:

     self.SendScintilla(QsciScintilla.SCI_SETFOCUS, True)

            Use any or all of these words:      

            self SendScintilla QsciScintilla SCI_SETFOCUS True

            Also any of these:

     SCI SETFOCUS

            Partial words won't match (but see below for wildcards)

            Scintilla                WONT MATCH

            You can search for symbols. E.g. Can also find the line with this search

            ( . , )

            If you give the whole target line as a search, it will match itself of course

            self.SendScintilla(QsciScintilla.SCI_SETFOCUS, True)

 

More Examples

 

QMessageBox warning

Match lines that contain the word QMessageBox and the word warning

 

PyQt4 OR PyQt5

Match lines that contain either the word PyQt4 or the word PyQt5. The OR keyword must be uppercase. OR applies only to the nearest word (or symbol character) either side unless you use quotes - see below.

Advanced Search

  •  If Advanced Search is off, all symbols just match themselves.

  •  If Advanced Search is on, the symbols - * and " have special meanings

     (or you can set different symbols in Preferences)

  •  Advanced Search can be turned on and off from the Search menu. 

 

Advanced Search Examples

 

QMessageBox  -warning

To exclude results use minus sign - prefix - Match lines that contain the word QMessageBox, and don't contain the word warning

 

lam*da

To match partial words, use asterisk * as wildcard  - Match lines that contain any word starting lam and ending da. 

 

"QMessageBox.warning"

Use double quotes " for phrase search - Match lines containing a specific token sequence. E.g. The word QMessageBox then a dot . then the word warning 

 

"self.x" OR "self.y"

Use double quotes " for OR with compound names - Match lines that have either self.x or self.y

 

"()" OR "[]"        

Use double quotes " for OR with symbol sequences - Match lines that have either () or []

 

-"self.x" "self.y"  

Use double quotes " with minus - to exclude compound names - Match lines that contain self.y but don't contain self.x

   Tips

  •  Automatic Spotlight pre-search speeds up searches, using the words and numbers you're trying to match.

  •  Wildcard at the front of words makes Spotlight pre-search slow.

  •  Phrase search isn't whitespace sensitive: Inside quotes, whitespace between tokens will match a variable amount of whitespace including none, e.g. "A[" will match    A[    and       A    [

 

Shortcuts 

When Line Contains box is selected, use shortcuts to turn its options on and off:

  • Switch between Simple Search Syntax and Regex with ^+R

  • Toggle case sensitivity with ^+C

  • Toggle order sensitivity with ^+O

Advanced Search

Overview

Advanced Searches are completely optional. Lots of people search the internet for years without using any Advanced Search techniques. It's off by default, but you can toggle on and off from the Search menu.

They can be used in the Line Contains box, the Path Contains box and the File Contains box.

If Advanced Search is OFF, no symbols have any special meanings, all symbols simply match themselves.
If Advanced Search is ON, three symbol characters are reserved for the same kind of advanced searches you may know from Google, Bing or DuckDuckGo:

  • Search for phrases (internet search uses double quote " for this)

  • Exclude Matches (internet search uses minus sign - for this)

  • Wildcards (internet search uses asterisk * for this)

Three special symbols

Internet search engines use double quotes " for phrase searches, the minus sign - as a prefix for excluding matches and asterisk * as a wildcard

To help you feel at home, these are also the default characters for Advanced Searches in Pop, but we strongly recommend using Pop's app preferences to change them to non-ASCII alternatives because these symbols are so common in code.

We like to use backtick ` to delimit phrase searches, the not-equals sign as a prefix for excluding matches (type it as = on English keyboards) and a bullet as a wildcard (Easy to remember, it's alt+asterisk: *) . But the in-app preferences give several symbols to choose from.

If you use the default symbols, this might be a typical search:

QMessage* -warning -critical "(self"

With the suggested non-ASCII alternatives it would look like this:

QMessage• ≠warning ≠critical `(self`

OR operator

Using OR in the Line Contains box
The OR operator is just the word OR in upper case. Use it to match either of two alternatives with one search. E.g. a Line Contains pattern like this:
   import PyQt4 OR PyQt5
Will match any lines containing the word import and the word PyQt4, as well as any containing the word import and the word PyQt5.

OR operates only on the search terms on each side of it. Parentheses are not supported for grouping search terms; parentheses just match themselves as other symbols do.


Using OR in the Path Contains box
OR is useful in the Path Contains box too. E.g. a Path Contains pattern like this will search C language files as well as headers:

.c OR .h


When using OR with compound names, use phrase search
In the Line Contains box, you must put compound names in quotes when using them with OR with. E.g. self.x is actually three tokens, and OR will only operate on one of them. E.g. To search for   self.x OR other.y   use this:

"self.x" OR "other.y"

(assuming double quote is your phrase delimiter)

This doesn't apply to Path Contains patterns, because its terms aren't tokens, they are text fragments separated by whitespace. So for Path Contains .c is a single term, not two.


The OR operator respects the Order sensitive checkbox
E.g. If you've ticked the Order box, a Line Contains pattern like this

( OR [ f

will match lines that have a f, so long as a ( or [ preceeds it.


You can use multiple OR operators
E.g. a Line Contains pattern like this:

a b OR c OR D OR e f

will match lines that have a AND f AND any of: b, c, d or e

Phrase search

Default phrase delimiter symbol is "
Change in-app preferences to use a recommended alternative: ` backtick or left double quote


When you're searching the internet you can search for a phrase like "The quick brown fox jumps over the lazy dog". Putting quotes around the phrase finds pages with this sequence of words.

Phrase search in Line Contains
The same technique works in Pop to find lines with a specific sequence of words and/or symbols, e.g. a Line Contains pattern of "self.x" without the quotes will find lines that have self . and x anywhere on the line. With the quotes you'll find only lines with this exact sequence. Just as with an internet phrase search, Pop phrase searches aren't whitespace sensitive.

Some more examples:
    "match_list["
"failed to copy flags of"
"new_line += 1"
"dict()"
"[]()"

Phrase searches play nicely with ordered search and the other Advanced Search operators, such as the exclusion prefix, OR and wildcard:
E.g to find x except when it appears in self.x
    x  -"self.x"

E.g. to match convert camel case as well as convert camelcase using wildcard
    "convert camel*"

E.g. to find Python method calls of the os package that aren't in its path module
    "os.*(" -path    

E.g. to use the OR operator with compound names
    "self.x" OR "other.y"

NB Underscore is an honorary alphanumeric character, you don't need phrase search for snake case names such as   match_list   (this won't find match and list separately)


Phrase search in Path Contains
The Path Contains box differs from Line Contains because its search terms are fragments of text rather than tokens.
So you don't need quotes, unless you're trying to match or exclude a fragment of text that includes whitespace.

E.g. this Path Contains pattern would restrict files searched to those in the folder called User Information
	"/User Information/"
E.g. this Path Contains pattern would restrict files searched to those that have a .cfg extension and are not in a folder called Deleted Users
	-"/Deleted Users/" .cfg

Exclude matches

Default exclusion prefix is - (minus sign)
Change in-app preferences to use a recommended alternative: (=) or ¬ (L)

When you're searching the internet you can exclude matches with a minus sign.
E.g.this search will find web pages on Python the programming language and Monty Python, and none on snakes:
	python -snake

Exclude line matches with Line Contains

The same technique works in Pop to exclude matches that contain specific words, phrases or symbols,

E.g. this search will find lines that have the name set_case_sensitivity, but not the word regex
	set_case_sensitivity -regex

E.g. this search will exclude matches that contain the word warning, and also exclude matches that contain the word critical
	QMessage* -warning -critical "(self"

To exclude matches with compound names, wrap them in phrase search delimiters

E.g to find x except when it appears in self.x

x -"self.x"

The same applies to compound symbols, e.g. to exclude matches preceeded by a double forward slash, tick Order by and use this Line Contains pattern:

Exclude operator respects the Order checkbox

E.g. if you've ticked the Order check box, this Line Contains pattern matches Python print statements that haven't been commented out
	–# print

If you haven't ticked the Order box, it matches Python lines with a print statement that don't have # anywhere on the line

Exclude files from search with Path Contains

Use the exclude operator to exclude files from your search, based on text in the filename or path
E.g. this Path Contains pattern searches files that have a .c extension and do not have the text bak anywhere in the path or filename
	.c  -bak

E.g. this Path Contains pattern searches files that have a .cfg extension as long as they are not in a folder called Deleted Users
	-"/Deleted Users/" .cfg

E.g. this Path Contains pattern searches files whose extension starts with .c, unless it's .cpp
	.c* -.cpp

Wildcards

Default wildcard symbol is * (asterisk)  
Change in-app preferences to use a recommended alternative: (*) or § (section sign)


Use wildcards to match partial tokens in
Line Contains

Use a wildcard to stand for an unknown sequence of alphanumerics in a token
E.g.this search matches setFocus, setInputFocus, setFocusToSearchForm and setFocusToResultsText
	set*focus*

This works for numbers too
E.g.this search finds pi when it has two or more digits
	"3.14*"
We have used a phrase search, because this is three tokens: 3   . and 14*

When the Use Spotlight option is on, a wildcard at the beginning of any name causes a delay of up to a minute before the search returns results. Often its quicker to turn off Spotlight and reduce the Search In scope.

Use wildcards to match partial folder names in Path Contains
In the Path Contains box, use wildcard to match partial folder names - a wildcard matches any sequence of characters except a forward slash.
E.g. this search will match paths that contain a folder called todo today but not a path that contains one folder called todo and a child folder called someday
	/to*day/

Configuration

App preferences dialog
You can change the Advanced Search Symbols in app settings, shortcut: ⌘,
From here you can also change the theme. There are three light syntax colour schemes available and three dark ones.

Detailed configuration file
Detailed configuration settings, including user macro definitions are stored in the UserSettings.json file:

	~/Library/Application Support/Pop/UserSettings.json


This is an extended .json format file, similar to Sublime Text .json configuration files: It's basically .json plus comments: any line that starts with // is taken to be a comment and the whole line is ignored during processing. The file has extensive comments which explain the meaning of the various configuration options

Some of the more important things you can configure:


Search logic

AUTO_APPEND_PC_PATTERN_SSS default is ""
This value is a string that will be automatically appended to the Path Contains box when a search is run. Use this for folders or file extensions you always want to ignore, e.g.:
"≠.pdf  ≠/.git/"


SKIP_NONUTF8 default is false
How to handle non-UTF8 characters
false -> replace non-utf 8 chars by placeholder chars; True => skip file altogether

LINELEN_LIMIT default is 10000
Individual lines longer than this many characters are ignored by order sensitive searches to avoid combinatorial explosion.


UI look and feel

FILEPATH_STYLE
Style applied to file paths in results list

BLANKLINE_BEFORE_FILE
Blank line before each file path?

SEARCH_HISTORY_LIMIT default 25
How many recent searches to cache

BIGFILE_BROWSE_WARNING_BYTES_LIMIT default 5000000
Max size of file you can open in file browser without seeing a warning that it might be slow to open

QS_LEXER_FROM_FILE
Is a map from file extensions to the choice of lexer to use in Pop's match browser.


Built in macros

You can edit many of the built-in commands, because they're implemented as macros in this file.
MENU_BINDINGS maps from menus to macros, and KEY_BINDINGS does the same for shortcuts that aren't bound to menus

For example Pop's useful X-Ray command is implemented as this macro:
	["@macro", 
["@replacelc", "{selectedtext}"],
["@replacesi", "{parentpath}"], "@cancel_search", "@start_search"]

Macros

Macros let you define actions for Pop when you click on a match, or press a shortcut key.
For example it's pretty easy to set up a macro to open the match file you click on in your preferred external editor. (There are example macros for this in the config file)

You enter macros alongside other settings by editing Pop's configuration file:

	~/Library/Application Support/Pop/UserSettings.json


You can also edit many of the built-in commands, because they're implemented as macros there too (see above).

MENU_BINDINGS maps from menus to macros, and KEY_BINDINGS does the same for shortcuts that aren't bound to menus


User macros

Macros are crude, but powerful.

Some macro commands need data, some don't.

A macro command that doesn't need data is just a string, e.g. "@start_search" which does the equivalent of pressing Enter in the UI
You can bind this to a shortcut key or a menu in UserSettings.json

Here's a list of the macro commands that don't need data.

"@open_folder" - open dialog for Search In folder
"@parent_folder" - set Search In folder to parent of whatever is currently set
"@dropdown_folder" - start tab completion for Search In folder path
"@focus_si" - move focus to Search In box
"@focus_fc" - move focus to File Contains box
"@focus_pc" - move focus to Path Contains box
"@focus_lc" - move focus to Line Contains box
"@start_search" - start search if no search is running else cancel active search
"@cancel_search" - cancel the active search
"@clear_searchform" - clear all the fields in the Search Form
"@show_all" - show the Search Form and the Match Browser
"@toggle_status" - hide/show the status bar
"@show_help" - show the context help
"@zoom_in" - increase font size for current pane (Results List or Match Browser)
"@zoom_out" - decrease font size for current pane (Results List or Match Browser)
"@toggle_searchform" - hide / show Search Form
"@toggle_browser" - hide / show Match Browser
"@toggle_results" - toggle max screen space for results pane
"@show_searchform" - show the Search Form
"@hide_searchform" - hide the Search Form
"@show_browser" - show the Match Browser (if it has text)
"@hide_browser" - hide the Match Browser
"@focus_searchform" - set focus to the Search Form
"@focus_results" - set focus to Results List
"@focus_browser" - set focus to Match Browser
"@focus_nextpane" - set focus to next pane
"@go_next_match" - move cursor to next matched line in Results List
"@go_prev_match" - move cursor to previous matched line in Results List
"@set_linenumbers" - make line numbers visible
"@unset_linenumbers" - hide line numbers
"@toggle_linenumbers" - show/hide line numbers
"@set_wrap" - turn on line wrapping
"@unset_wrap" - turn off line wrapping
"@toggle_wrap" - toggle line wrapping
"@set_syntax" - turn on syntax highlighting
"@unset_syntax" - turn off syntax highlighting
"@toggle_syntax" - toggle syntax highlighting
"@toggle_case" - toggle case sensitivity for which ever search box is currently focused (File Contains, Path Contains or Line Contains)
"@set_case" - turn on case sensitivity for which ever search box is currently focused (File Contains, Path Contains or Line Contains)
"@unset_case - turn off case sensitivity for which ever search box is currently focused (File Contains, Path Contains or Line Contains)
"@toggle_regex" - toggle between regex and internet-style search syntax for which ever search box is currently focused (Path Contains or Line Contains)
"@set_regex" - turn on regex search syntax for which ever search box is currently focused (Path Contains or Line Contains)
"@unset_regex" - turn off regex search (turn on internet-style search) for which ever search box is currently focused (Path Contains or Line Contains)
"@toggle_order" - toggle order sensitive search if Line Contains box is currently focused
"@set_order" - turn on order sensitive search if Line Contains box is currently focused
"@unset_order" - turn off order sensitive search if Line Contains box is currently focused
"@grow_browser" - grow the size of the Match Browser by step size (if it"s docked at bottom of screen)
"@shrink_browser - shrink the size of the Match Browser by step size (if it"s docked at bottom of screen)


Macro commands that need data should be entered as a two item list.
The first item is the command name (a string), the second item is the data (also a string)

E.g. the macro ["@replacelc", "{selectedtext}"] runs the macro command "@replacelc", which replaces the current
Line Contains pattern by its data item.
If the data item had been a static string, like "TODO", every time you ran the macro your Line Contains pattern would be set to TODO. In fact the data item "{selectedtext}" is a place holder for whatever text is selected in the UI when the macro is run.

You can put additional text in the string if you want. At runtime the additional text will be unchanged, but the curly braces and the name they contain will be substituted by the appropriate value. The other data placeholders relate to details of the currently focused cursor line

"{fullpath}" - fullpath of the file containing that line
"{parentpath}" - path of the parent folder of the file containing that line
"{name} "- name of the file containing that line
"{linenumber}" - line number of that line within its file

There is a related set of data placeholders that put quotes around the data; e.g this macro opens the current match in pycharm at the correct line:
	["@shell", "/usr/local/bin/charm --line {linenumber} {qfullpath}"]


The data item for "@shell" is a bash command string you want to execute. If we used the fullpath of the match file without any quotes it would fail for paths that contain spaces. qfullpath is just the same as fullpath but it uses shlex.quote to quote the value it returns.

Here is a complete list of data placeholders
"{selectedtext}" - currently selected text in UI
"{fullpath}" - fullpath of the file containing that line
"{qfullpath}" - quoted fullpath of the file containing that line
"{parentpath}" - path of the parent folder of the file containing that line
"{qparentpath}" - quoted path of the parent folder of the file containing that line
"{name} "- name of the file containing that line
"{qname} "- quoted name of the file containing that line
"{linenumber}" - line number of that line within its file

Here's a list of the macro commands that need data (these are always the first item of a two item list)

"@shell" - run bash command string given by data item
"@appendlc" - append data item to line contains box
"@appendpc" - append data item to path contains box
"@appendfc" - append data item to file contains box
"@replacelc" - replace contents of line contains box by data item
"@replacepc" - replace contents of path contains box by data item
"@replacefc" - replace contents of file contains box by data item
"@replacesi" - replace contents of search In box by data item
"@message" - pop up a message box with data item as the message

There's one additional macro command that needs data, it's always the first item of a variable length list
"@macro" - it specifies that what follows is a list of macro commands to be executed sequentially

How Pop searches

With Spotlight option ON

When your line search includes words and numbers

Spotlight is used to find files in your Search In folder that contain all the words and numbers you're searching for.

The fullpaths of these files are compared to your Path Contains pattern; any that contain all its text fragments (in any order) are passed on to line-search

Line search looks for any line that has all the tokens from your Line Contains pattern (if your Line Contains pattern is Order Sensitive, so is this step)

A final step may then take place for each matched line to check constraints such as excluded matches. For Order Sensitive searches with excluded matches, this can require checking of multiple match placements on each line.


When your line search has symbol characters only


Spotlight doesn't work well when searching for symbols in file contents, so if you're not searching for any words or numbers, Pop will try instead to use information from your Path Contains pattern to search for matching filenames

Otherwise the logic is the same as above


When searching for symbol characters only, and no filename or extension is specified in Path Contains

A text fragment in a Path Contains pattern is taken to be a file extension if it stars with ., and a filename if it has a name: operator prefix (analogous to the site: operator for internet search). Other text fragments match anywhere in the path, so can't be used in a Spotlight file name search.

In this case the search walks the file system, and every file in the Search In folder is compared to the Path Contains pattern.


With Spotlight option OFF

Pop walks the filesystem and compares the fullpath of each file met to your Path Contains pattern; any that contain all its text fragments (in any order) are passed on to line-search

Line search looks for any line that has all the tokens from your Line Contains pattern (if your Line Contains pattern is Order Sensitive, so is this step)

A final step may then take place for each matched line to check constraints such as excluded matches. For Order Sensitive searches with excluded matches, this can require checking of multiple match placements on each line.


With a blank Line Contains pattern

If your Line Contains pattern is blank, the appropriate logic from above is followed according to whether Spotlight is on or off. But there is no line search.
Your result set is just a list of the fullpaths of all the files that satisfy your Path Contains pattern.


We use Google and Clicky Analytics to count how many people visit, and how many come back.
For now, if you don't want a cookie, please browse in incognito mode.

© 2019 Etia UK