Skip to content

Scripting Commands

Jump to bottom Edit New page
Doug P edited this page Feb 13, 2024 · 8 revisions

Scripting is a way to automate most of the actions on the dnGrep main window. Scripts may be run from the "Scripts" menu, from the Script Editor, or from a command line argument.

About Scripts

Scripts are simple text files with a .gsc file extension using a set of keywords.

Script files are stored in the "Scripts" subdirectory of the application data folder. If dnGrep is installed in the Program Files folder, then the application data folder is C:\Users\username\AppData\Roaming\dnGREP. If dnGrep is installed in another location or run as a portable application, the application data folder is the same directory where dnGREP.exe is located.

When running dnGrep, open the application data folder from the About - Application data and logs menu.

Save your scripts using the *.gsc file extension in the "Scripts" folder, or another subdirectory under the Scripts folder. The Scripts menu on the dnGrep main window will follow the subdirectory structure you create when saving your scripts. The subdirectories are included in the script file key, so the same named script can be found in different subfolders. For example, if the file 'testscript.gsc' is in the 'Scripts\cpp' folder, the script file key is: cpp\testscript

Creating Scripts

Create a new script using the Scripts - New Script menu item and the Script Editor window will open.

Enter commands in the script and as you enter command, the editor will suggest keywords based on the current context. The keywords must be entered exactly as suggested in the editor and shown in the tables below. The tooltips shown in the editor are hints for how the command or property is used in the application.

  • Ctrl+Space will open the command suggestions.
  • Space, Enter or Tab will accept the suggestion.
  • Esc will clear the tooltips.

You may include comments and blank lines in the script - comment lines begin with //.

To include spaces a command value, enclose the value in double quotes: set serachfor "apples "

Running Scripts

While scripts are running, the dnGrep main window is still active. The Cancel button or Cancel script menu item will cancel the script.

If the script has errors, the script messages window will pop up.

If you want confirmation that the script run has finished, include the messages command in the script.

Run options:

  1. Run scripts from the dnGrep main window 'Scripts' menu. Click a script name below the separator or in sub-menus to run it.

  2. You can also create and run a script without saving it: create a new script, enter the commands, and use the Tools - Run menu in the Script Editor to run the script. Close the editor without saving.

  3. To run a script from the command line, use the /sc, -sc, or -script flag followed by the script file key.

dnGrep.exe -sc testscript

Will run the C:\Users\username\AppData\Roaming\dnGREP\Scripts\testscript.gsc file.

If other command line arguments are also included, they will be applied before the script is run.

Script commands take one of three forms:

  • command target value, for example, set folder c:\testfiles
  • command value, for example, copyfiles c:\newfolder
  • command, for example, search

dnGrep Script Commands

Command Target Value Description
set X X set a property with a value
search start the search
replace replace matches
sort sort the results with the current sort options
report X X write a report
run X X run an external command
include X X include another script file in this script
bookmark X X use, add, or remove bookmarks
resetfilters change file filters to back to their default values
undo undo the last replace operation
copyfilenames copy the file names of the results to the clipboard
copyresults copy the result tree text to the clipboard
copyfiles X copy result files to a new location
movefiles X move results files to a new location
deletefiles delete the result files
copy X copy results files with rename for backup (see notes below for arguments)
expandfilefilters X expand or collapse the file filters panel
maximizeresults X maximize or restore the results panel
expandresultoptions X expand or collapse the result options panel
messages show the script messages window at the conclusion of the script run
exit close all windows and exit dnGrep

Notes

At the start of the script run, the current settings in the main window are the initial conditions for the run. So, the script must set properties as required for the script run. A named bookmark may be used to initialize the properties. Or an initialization script can be created to just set the initial properties, and then that script can be included in multiple script files.

The replace command will replace all matches in all writable files. There is no option for selecting matches for replacement. In script mode, it is assumed you accept all the message boxes that would appear when running normally.

The movefiles and copyfiles commands will stop if they encounter an existing file in the destination directory.

The deletefiles command can either move files to the Recycle Bin or delete them permanently depending on the user option setting in the Options dialog.

The copy command has a different format than the other scripting commands as it has four optional arguments:

copy -match [pattern] -rename [pattern] -overwrite [True/False] -out [destination]

The intent of the copy command is to create file backups before modification, but can be used to copy files anywhere, optionally renaming them. The command operates on all files in the current result set. The -match and -rename arguments are regular expressions. The match pattern should contain a capture group which is referenced in the rename pattern. Using regular expressions with capture groups provides many options for renaming files. The default for -overwrite is false, The default for the -out output directory is the same directory as the source file. The path to the destination directory may be a relative path or fully qualified path. If the copy command cannot copy all files successfully, it will stop the script execution.

Set command targets and values:

Command Target Value Field Name
set folder path or file Folder
set pathtomatch pattern Patterns to match
set pathtoignore *pattern Patterns to ignore
set searchinarchives True / False Search in archives
set patterntype Regex / Asterisk / Everything File pattern: Regular expression, Wildcard, Everything
set searchparallel True / False Search parallel
set usegitignore True / False Use .gitignore
set skipremotecloudstoragefiles True / False Skip remote cloud storage files
set encoding number Encoding: the code page number (see note below)
set filterbyfilesize No / Yes All sizes or size range
set sizefrom number Size lower limit
set sizeto number Size upper limit
set includesubfolder True / False Include subfolders
set maxsubfolderdepth number Max depth
set includehidden True / False Include hidden folders
set includebinary True / False Include binary files
set followsymlinks True / False Follow symbolic links
set filedatefilter All / Modified / Created All dates, Modified, Created
set filetimerange All / Dates / Minutes / Hours/ Days / Weeks / Months /Years Date from / to, or Past time range
set startdate date time From date as a string (see note below)
set enddate date time To date as a string (see note below)
set timerangefrom number Past lower limit
set timerangeto number Past upper limit
set hoursfrom number deprecated, use timerangefrom
set hoursto number deprecated, use timerangeto
set searchtype Regex / XPath / PlainText / Soundex / Hex Regular expression, XPath, Text, Phonetic, Byte
set searchfor pattern Search for
set replacewith text Replace with
set casesensitive True / False Case sensitive
set wholeword True / False Whole word
set multiline True / False Multiline
set dotasnewline True / False Dot as newline
set booleanoperators True / False Boolean operators
set capturegroupsearch True / False Capture group search
set searchinresults True / False Search in results
set previewfile True / False Preview file
set stopafterfirstmatch True / False Stop after first match
set highlightmatches True / False Highlight matches
set highlightgroups True / False Highlight groups
set showcontextlines True / False Show context lines
set contextlinesbefore number Lines before
set contextlinesafter number Lines after
set wraptext True / False Wrap text
set resultszoom number Zoom
set sorttype FileNameDepthFirst Path and filename, depth first
sorttype FileNameBreadthFirst Path and filename, breadth first
sorttype FileNameOnly File name only
sorttype FileTypeAndName File type and name
sorttype Size File size
sorttype Date Last write time
sorttype MatchCount Match count
set sortdirection Ascending / Descending
set reportmode FullLine / Matches / Groups Full lines, Matches only, Capture groups only
set fileinformation True / False Include file and line information
set trimwhitespace True / False Trim whitespace
set uniquevalues True / False Filter unique values
set uniquescope Global / PerFile Global, Per file
set separatelines True / False Show each match or group on a separate line
set listitemseparator text Separator for multiple matches or groups on a line

Notes

Encoding is set using the Code Page. Set the Encoding value to 65001 for UTF-8, or -1 for Auto detection. In dnGrep, the code page is shown in the file information tooltip on the results tree: Encoding: Unicode (UTF-8) cp65001.

Date time values should use ISO 8601 formatting, but some date time formats for your locale may also work.

  YYYY-MM-DD
  YYYY-MM-DDThh:mm:ssZ
  YYYY-MM-DDThh:mm:ss±hh:mm

where:
     YYYY = four-digit year
     MM   = two-digit month (01=January, etc.)
     DD   = two-digit day of month (01 through 31)
     T    = literal "T" to indicate start of the time element
     hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
     mm   = two digits of minute (00 through 59)
     ss   = two digits of second (00 through 59)
     TZD  = time zone designator (Z or +hh:mm or -hh:mm)

Run command targets and values:

Command Target Value Description
run powershell path and file name Run a PowerShell script (*.ps1)
run cmd path and file name Run a batch file (*.bat or *.cmd)

Include command targets and values:

Command Target Value Description
include script script key Include another script in this script

Note

The script key is the file name of the script file, without extension. If the script file is in a subdirectory of the "Scripts" folder, include the folder paths below the Scripts folder in key. For example, if the file 'testscript.gsc' is in the 'Scripts\cpp' folder, the key is: cpp\testscript

Report command targets and values:

Command Target Value Description
report full path and file name The full report including the search parameters
report text path and file name The customizable text-only report
report csv path and file name The customizable csv report

Bookmark command targets and values:

Command Target Value Description
bookmark use bookmark name Apply the named bookmark settings
bookmark add bookmark name or empty Create a new bookmark with optional name
bookmark addfolder bookmark name or empty Create a new folder linked bookmark with optional name
bookmark remove bookmark name or empty Remove the named bookmark, or current bookmark if empty
bookmark removefolder bookmark name or empty Remove the named folder linked bookmark, or disassociate the folder if empty

Validation In the Script Editor, use Tools - Validate to check the script. The validator is also run when saving the script.

Add a custom footer
Clone this wiki locally