3.7. NppExec's script

NppExec's script is a set of NppExec's commands. NppExec's command can be an internal command such as "cls", "npp_save", "npe_debuglog" etc. or it can be a (path)name of an executable such as "cmd", "calc", "C:\tools\tcc\tcc.exe" etc. Each command, depending on its meaning, can have one or more parameters. For example:

INPUTBOX "Input something:" : something
NPP_EXEC "script name" "param 1" "param 2"
cmd /c copy /?
"C:\tools\tcc\tcc.exe" -run "$(FULL_CURRENT_PATH)"

and so on. You can use "//" to comment an entire line or right part of a line (after "//"):

// this is a comment
ECHO You'll see this // but not this (comment)

You can create and save NppExec's scripts using the "Execute NppExec Script..." dialog [3.6]. However, NppExec's script can also be located in a text file. I.e. you can create a text file which contains some NppExec's commands (one command per one line) and then execute this file (commands from this file) in NppExec. Such text file can be an ANSI file for ANSI version of NppExec and can be an ANSI or Unicode (UCS-2 LE/UCS-2 BE/UTF-8) file for Unicode version of NppExec. Note that Unicode text file must contain leading "BOM" bytes to be recognized by Unicode version of NppExec (by default, these bytes are present - until you force saving without "BOM"). To execute NppExec's script from a text file, use the "npp_exec" command. This command allows to execute commands from a previously saved (internal) script or from an (external) text file.

As you can store your NppExec's script in a text file, you can edit such file directly in Notepad++ and execute it with the following command(s):

NPP_SAVE  // save current file (NppExec's script)...
NPP_EXEC "$(FULL_CURRENT_PATH)"  // ...and execute it

With the Console Commands History enabled, you can type this command:

NPP_EXEC "$(FULL_CURRENT_PATH)"

in NppExec's Console once, then use the Arrow Up key to repeat this command. However, be sure to save current file (with Ctrl+S) before executing it.

To create a menu item for NppExec's script, use NppExec's Advanced Options dialog. Then a shortcut key can be assigned to it:

Create a menu item for the script using Plugins -> NppExec -> Advanced options (select a script in the "Associated script" drop-down list, specify its menu item name - by default it's the same as the script name - and press the "Add/Modify" button).
Restart Notepad++ to get this new menu item.
Assign a shortcut key to this new menu item using Notepad++'es Settings -> Shortcut Mapper -> Plugin commands (you'll find the menu item there).

NppExec stores your scripts in Notepad++'es "$(PLUGINS_CONFIG_DIR)" folder. The "npes_saved.txt" file stores all the scripts except the temporary one which is stored inside "npes_temp.txt".

NppExec's script syntax. General notes:

Commands are case-insensitive. Thus, npp_open is the same as NPP_OPEN, Npp_Open and so on.
Use help <command> to get detailed help [3.1] on any NppExec's <command>. For example: help npp_open, help set, help sci_sendmsg and so on.
Use spaces to separate parameters of NppExec's command. Do not use neither brackets nor commas:
```
sci_sendmsg SCI_SETTEXT 0 "some text"
set local pos ~ strfind "Hello world" Hello
```
Use " ", ` ` and ' ' around parameters that contain spaces or other quote characters [3.8.5] :
```
sci_sendmsg SCI_SETTEXT 0 `"some text in quotes"`
inputbox 'Hello World!'
set local pos ~ strfind "Hello's world" `Hello's`
set local len ~ strlen "  34' 78  "  // returns 12, including ""
set local len ~ $(len) - 2           // 10, without the ""
cd C:\Program Files (x86)  // cd accepts a parameter without quotes
```
Note: when a command expects several parameters, it extracts the parameters' values by removing the surrounding quotes (there are rare exceptions, though, such as substr that preserves the surrounding quotes). If a command expects just one parameter, the surrounding quotes may or may not be removed, depending on the command. Refer to the built-in help by typing e.g. "help sci_sendmsg", "help inputbox", "help set", "help cd" etc. for actual examples.
Use $(var) to get the value of an internal variable named "var" [3.8.2] . Don't forget to use the form of $(var) in mathematical expressions [3.8.4] as well:
```
set local x = 10        // assigns 10 to a variable 'x'
set local x ~ $(x) + 1  // accesses the previous value of 'x' and adds 1
```
Use $(sys.var) to get the value of an environment variable "var" [3.8.3] . NppExec does not understand such form as %var%:
```
echo $(SYS.PATH)  // prints the value of %PATH%
env_set PATH = $(SYS.PATH);C:\tools  // updates the value of %PATH%
```
Use cmd /C to explicitly invoke the system's command interpreter (cmd.exe) when needed [4.4] . For example:
```
cmd /C echo %PATH%
cmd /C time /t >time.txt && type time.txt
cmd /C taskkill /? | findstr /ic:pid
```

Use different forms of IF-GOTO when needed:

// Simple IF-GOTO
if $(x) == 1 goto 1
if $(x) == 2 goto 2
echo x is neither 1 nor 2
goto end
:1
echo x is 1
goto end
:2
echo x is 2
goto end
:end

// IF-GOTO-ELSE
if $(x) == 1 goto 1
else if $(x) == 2 goto 2
else
  echo x is neither 1 nor 2
  goto end
endif
:1
echo x is 1
goto end
:2
echo x is 2
goto end
:end

// IF-GOTO Loop
set local N = 10
set local x = 1
:1
echo $(x)
set local x ~ $(x) + 1
if $(x) <= $(N) goto 1

Use different forms of IF-THEN when needed:

// Simple IF-THEN
if $(x) == 1 then
  echo x is 1
endif
if $(x) == 2 then
  echo x is 2
endif
echo x is neither 1 nor 2

// IF-THEN-ELSE
if $(x) == 1 then
  echo x is 1
else if $(x) == 2 then
  echo x is 2
else
  echo x is neither 1 nor 2
endif

// Nested IF-THEN-ELSE
if $(x) == 1 then
  echo x is 1
else
  if $(x) == 2 then
    echo x is 2
  else
    echo x is neither 1 nor 2
  endif
endif

// IF-THEN-GOTO Loop
set local N = 10
set local x = 1
:1
if $(x) <= $(N) then
  echo $(x)
  set local x ~ $(x) + 1
  goto 1
endif

Use IF~ to calculate mathematical expressions during the comparison:

set local x = 8
set local y = 14
if~ $(x) + 2 == $(y) - 4 then
  echo left == right
else
  echo left != right
endif

 

See also: "Execute NppExec Script..." [3.6]; Run-time parameters [4.3].