Title Page

NppExec User Guide

by

Vitaliy Dovgan

A Notepad++ Plugin that Allows You to Run Commands and Programs Directly from the Editor

User Guide Version 1.00

April 2009


1.1. Introduction

NppExec is a plugin for Notepad++ which allows you to run some commands/programs directly from Notepad++ and provides an output window (NppExec's Console).

NppExec can be used for running other programs from Notepad++, passing text from Notepad++ to some external tool, compiling source files (using external compiler) etc.

When the NppExec plugin is installed, you can see its icon "Show Console Dialog" on Notepad++'es toolbar, and you can find NppExec's submenu under Plugins menu of Notepad++.

You can always find the latest version of NppExec at https://sourceforge.net/projects/npp-plugins/ - it is there among other Notepad++'es plugins.


1.2. NppExec is...

+ NppExec is an intermediary between Notepad++ and external tool/compiler. It allows to run external tool/compiler directly from Notepad++.

+ NppExec is a Console window which can show the running process'es output, and can redirect the Console window's input to the running process (with some limitations).

+ NppExec is an interpreter of its own internal commands. NppExec can execute several commands one after another (so-called NppExec's script) from its "Execute..." dialog and can execute single command directly from its Console window.


1.3. NppExec is not...

- NppExec is not a console emulator. NppExec redirects the running process'es output to its Console window, and can redirect the Console window's input to the running process (with some limitations). The NppExec's Console is not a "real" console window (actually, it uses RichEdit control for text input/output), it does not provide a console screen buffer. Thus, a console application which requires a "real" console screen buffer must be run in its own console window (using NPP_RUN command).

- NppExec is not a command interpreter. NppExec does not understand such commands as 'copy', 'call', 'for' and so on because it is neither a "real" console nor a console emulator. However, NppExec has its own internal implementation of such commands as 'cls', 'cd', 'dir', 'echo', 'set' ('env_set') and introduces other, specific, commands. Also you can use "cmd /c <command>" to execute any cmd's command inside NppExec.

- NppExec is not a compiler. NppExec allows you to use external tools and compilers to process/compile your current file, but it has no ability to do it by itself. No magic here :)


2.1. What? Installation?

Usually latest stable version of NppExec is included in Notepad++'es package, so you don't have to do anything manually.

However, you may want to know:

  • what actually is the NppExec plugin and how can it be installed or removed;
  • how can you install the latest version of NppExec;
  • how can you use several copies of NppExec.


2.2. The NppExec plugin (NppExec.dll)

NppExec is a dynamic-link library (DLL) implemented as a plugin for Notepad++. Actually (physically) the NppExec plugin is one file named "NppExec.dll". This file ("NppExec.dll") must be placed (copied) to Notepad++'es Plugins subfolder in order to work with Notepad++.


2.3. Installing the latest version

You can always find the latest version of NppExec at https://sourceforge.net/projects/npp-plugins/ - it is there among other Notepad++'es plugins.

Once you download the archive containing the latest "NppExec.dll" file, unpack this file ("NppExec.dll") to your Notepad++'es Plugins subfolder (you may need to overwrite your existing "NppExec.dll" with the latest one). Also you may be interested in the documentation inside the archive as it always contains the latest information about NppExec's commands and variables, advanced options and changes.

If you are not sure about the "Notepad++'es Plugins subfolder", do the following:

  1. locate the file "notepad++.exe" on your computer (usually it is located somewhere here: C:\Program Files\Notepad++\notepad++.exe);
  2. go to the folder which contains the file "notepad++.exe" (e.g. C:\Program Files\Notepad++);
  3. go to its subfolder "plugins" (e.g. C:\Program Files\Notepad++\plugins);
  4. you are there! :)


2.4. Using several copies of NppExec

You can have several copies of "NppExec.dll" in your Notepad++'es Plugins subfolder in order to have several NppExec's Console windows. Each copy of NppExec saves its own options and its own console commands history (if it is enabled in NppExec's options). In the same time, saved NppExec's scripts are shared between several copies of NppExec.

To have several copies of "NppExec.dll", just copy it with different name(s), for example, "NppExec2.dll", "NppExecCpp.dll", "NppExecWeb.dll" and so on. This will give you additional NppExec's Console windows with the corresponding titles: "Console2", "ConsoleCpp", "ConsoleWeb" and so on.


2.5. Unicode and ANSI version

There are two builds of NppExec: the Unicode build and the ANSI build. The Unicode build is compatible with Unicode Notepad++ and the ANSI build is compatible with ANSI Notepad++. You can check your version of Notepad++ by pressing F1 or from its main menu (? -> About Notepad++). You will see something similar to "Notepad++ v5.1.3 (UNICODE)" or "Notepad++ v5.1.3 (ANSI)". The corresponding version of NppExec (Unicode or ANSI) is required.

I recommend you to use Unicode version of Notepad++. The ANSI version of Notepad++ exists just for compatibility with old non-Unicode systems (such as Windows 98 or Millenium) and with old non-Unicode plugins.

Talking about NppExec, its Unicode build is more powerful because it has a full Unicode interface and supports ANSI, UTF-8, UCS-2 LE (Unicode wide characters in Windows) and UCS-2 BE input files. The ANSI version of NppExec supports just ANSI input files. It is caused by the following reason: conversion of UTF-8 or UCS-2 to ANSI may lead to loss of some Unicode characters which have no ANSI analogue.


3.1. Getting help

The description of all commands and environment variables supported by current version of NppExec can be found in the file "NppExec.txt". Usually you can find this file in downloaded NppExec's archive [2.3] or in Notepad++'es Plugins subfolder [2.3] (in its "doc" subfolder).

All advanced "hidden" settings of current version of NppExec are described in the file "NppExec_TechInfo.txt". Usually you can find this file in the same place where the file "NppExec.txt" is located. Remark: you can change some of the advanced settings using NppExec's Advanced Options dialog.

The most recent and detailed information about all NppExec's commands and environment variables can be found in NppExec's built-in help. To use the built-in help, open NppExec's Console [3.5], type "help" and press Enter. You'll see a long list which contains:

- NppExec's Console hotkeys;

- NppExec's Console commands (which work in the Console only);

- NppExec's general commands (which work everywhere in NppExec);

- NppExec's predefined environment variables.

To get detailed help about any NppExec's command, type "help <command>" and press Enter. For example, "help set", "help inputbox", "help npp_exec" etc. The detailed help usually contains the command description, examples and remarks. This is the most essential information.

Some additional information can be found in NppExec's Help/About window. For example:

- You can execute commands and scripts directly from the Console window;

- Commands are case-insensitive (i.e. NPP_OPEN is the same as Npp_Open);

- and so on.


3.2. Do something (intro)

The main principle of NppExec is the same as Notepad++'es "Run..." command (F5): to execute a command given. Usually it means to run some program/tool with specified parameters which can be passed in a form of Notepad++'es environment variables. For example, it allows you to launch your current file in Internet Explorer or to compile your current file using certain compiler. NppExec provides additional abilities for this:

- it has a Console window to show the console program's output

- it allows you to execute several commands one after another

- it supports all Notepad++'es environment variables plus several own variables

- it has additional commands which allow you to do more than you expect :)

- it is cool :)

NppExec actually provides four different ways to execute some command(s):

  1. using NppExec's Console [3.5] - allows you to enter some command and execute it by pressing Enter;
  2. using NppExec's dialog "Execute..." [3.6] - allows you to enter several commands (which will be executed one after another) and to save these commands as NppExec's script;
  3. using NppExec's command "npp_exec <script>" - allows you to execute commands from existing script [3.7];
  4. using NppExec's command "npp_exec <file>" - allows you to execute commands from existing text file [3.7].

By the way, NppExec uses the 3rd way (described above) for its menu items which allow you to execute some NppExec's script.

Remarks:

NppExec by itself understands only its own internal commands and environment variables. When you type another command, such as "copy", "cmd" or "calc", NppExec tries to run it as a child process - i.e. it performs CreateProcess(...) and waits until this process ends. When you type something like "npp_run cmd" or "npp_run calc", NppExec tries to run specified command (the argument of npp_run) as an external process - i.e. it performs ShellExecute(...) and does not care about this process.


3.3. Do something (how-to)

To run some program (optionally, with parameters) as a child process of NppExec, just type the (path)name of this program (optionally, with parameters) in NppExec's Console [3.5] or in NppExec's "Execute..." dialog [3.6]. This makes NppExec to:

  1. run the program (optionally, with parameters)
  2. show its output in NppExec's Console (if it is a console program)
  3. wait until the program exits

For example, type

cmd

to start the "cmd.exe". You will see the cmd's output in NppExec's Console. You can type some cmd's commands in order to cmd to execute them and, finally, type "exit" in order to exit cmd.

Also you can type

calc

in order to start the "calc.exe". NppExec will wait until you close the calc's window.

Finally, here is an example with parameters:

cmd /c time /t

The last example shows the output of cmd's command "time /t" in NppExec's Console - i.e. it shows current time.

The same approach can be used to execute .bat and .cmd files - but the file extension (.bat or .cmd) can not be omitted in this case.

To run some program (optionally, with parameters) as an external process (with respect to NppExec), type "npp_run " and the (path)name of this program (optionally, with parameters) in NppExec's Console [3.5] or in NppExec's "Execute..." dialog [3.6]. This makes NppExec to:

  1. run the program (optionally, with parameters)
  2. a console program is shown in its own console window
  3. NppExec does not wait until the program exits

For example, type

npp_run cmd

to start the "cmd.exe" in its own window.

Also you can use "npp_run " to open specified file in its associated program. For example, "npp_run index.htm" opens the .htm file in your default internet browser.


3.4. NppExec's submenu

You can access NppExec's submenu from Notepad++'es main menu: Plugins -> NppExec. This submenu contains the following items:

Execute...

- shows NppExec's "Execute..." dialog [3.6];

Direct Execute Previous

- executes previous NppExec's script [3.7] immediately;

Show Console dialog

- shows/hides NppExec's Console [3.5];

Toggle Console dialog

- activates/deactivates NppExec's Console [3.5]

(depends on Console's option "hide toggled Console");

Console Commands History

- enables/disables NppExec's Console's commands history;

Console Output... {OEM/OEM}

- shows "Console Output/Input encoding" dialog;

No internal messages

- disables command confirmations and so on in NppExec's Console;

Save all files on execute

- (always) save all modified files before executing NppExec's script;

Follow $(CURRENT_DIRECTORY)

- (always) set current directory to active file's path;

Console Output Filters...

- shows "NppExec Console Filters" dialog;

Advanced Options...

- shows "NppExec Advanced Options" dialog;

Change Console Font...

- allows to change NppExec's Console's font;

Help/About...

- shows some information about the plugin.


3.5. NppExec's Console

NppExec's Console can be shown using the toolbar button "Show Console Dialog" or the menu item "Show Console Dialog" in NppExec's submenu (Plugins -> NppExec -> Show Console Dialog).

* By the way, you can reassign the toolbar button or even disable it via NppExec's "Advanced options..." dialog.

NppExec's Console is used to:

  1. show the running console process'es output; optionally, the Console Output Filters can be used. This happens when some child console process is being executed;
  2. show NppExec's internal messages (command confirmations and so on - can be disabled with "No internal messages" option). This happens when (also may be before or after) some command is executed;
  3. show NppExec's built-in help. This happens when you type "help" or "help <command>" (e.g. "help npp_run", "help set" etc.) in the Console;
  4. go to specified line in specified file by double-clicking the Console's line which contains the file (path)name and the line - using the Console Output Filters -> HighLight;
  5. execute a single command by typing it in the Console and pressing Enter;
  6. copy (Ctrl+C) some text from and paste (Ctrl+V) to the Console;
  7. and more; type "help" in the Console for details.


3.6. NppExec's "Execute..."

NppExec's "Execute..." dialog can be shown using its hotkey (F6 by default) or the menu item "Execute..." in NppExec's submenu (Plugins -> NppExec -> Execute...).

NppExec's "Execute..." dialog allows to specify several NppExec's commands (one command per one line) which will be executed one after another. Such set of commands forms so-called NppExec's script. The script can be saved using the "Save..." button of the "Execute..." dialog. For example, you can create NppExec's script which makes a reserve copy of current file:

1) open the "Execute..." dialog and type the following

// save current file
NPP_SAVE
// copy current file to C:\Backup
cmd /c copy "$(FULL_CURRENT_PATH)" "C:\Backup\$(FILE_NAME)" /Y

2) press the "Save..." button, type "Reserve Copy" and press the "Save" button.

This example allows you to create and save NppExec's script named "Reserve Copy". You can call this script later from the "Execute..." dialog. Also you can create a menu item for this script using NppExec's Advanced Options (Plugins -> NppExec -> Advanced Options...).

It is not necessary to save a new script each time you want to execute several commands. You can use the "<temporary script>" for commands you don't need to save. The temporary script is saved automatically when you close Notepad++. Also, if you modify commands of some saved script (e.g. if you modify the "Reserve Copy" script), it will be saved automatically when you close Notepad++. Or you can press the "Save" button to save it immediately.

You can delete previously saved scripts using the "Execute..." dialog. Press the "Save..." button (yes, the irony :)), select a script name and press the "Delete" button.


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" "$(FULL_CURRENT_PATH)" -run

and so on. You can use "//" to comment a whole 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..." 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 a 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.


3.8.1. Predefined (read-only) variables

NppExec supports all basic (predefined) environment variables of Notepad++ plus several its own (predefined) environment variables. See NppExec's help [3.1] for more details about supported predefined variables.

Consider such predefined environment variables as "read-only": you can use these variables in NppExec's commands and scripts, but can not modify their values.

These variables exist in NppExec's commands and scripts - actually, these variables are replaced with their current values by NppExec when you use them. These variables do not exist outside of NppExec (do not exist for child processes and so on). It means you can't use such variables as $(FULL_CURRENT_PATH), $(NPP_DIRECTORY), $(#1) and so on inside external programs or tools. However, you can:

1) pass the values of these variables as input parameters of external programs/tools, e.g.

// pass "$(FULL_CURRENT_PATH)" as a parameter of tcc
tcc "$(FULL_CURRENT_PATH)" -run

2) use the command "env_set" to create a heritable environment variable [3.8.3] which will be accessed inside external programs/tools, e.g.

// create new environment variable NPPHOME
ENV_SET NPPHOME = $(NPP_DIRECTORY)
// start cmd.exe
cmd

Now you can type something similar to "echo %NPPHOME%" inside cmd in order to use the value of this environment variable.


3.8.2. User (internal) variables

NppExec allows you to create, modify and remove your own (user) variables using NppExec's commands "set" and "unset". See NppExec's help [3.1] for more details about the commands "set" and "unset".

Consider such user variables as "internal": these variables exist only for NppExec. You can create, modify and remove such variables in NppExec's commands and scripts any time you need: to store some value, to set some value in one script in order to use it in another script etc. These variables do not exist outside of NppExec (do not exist for child processes and so on). It means you can't use these variables inside external programs or tools. However, you can:

  1. pass the values of these variables as input parameters of external programs/tools (see [3.8.1]);
  2. use the command "env_set" to create a heritable environment variable [3.8.3] which will be accessed inside external programs/tools (see [3.8.1]).


3.8.3. Environment (heritable) variables

NppExec (ver. 0.3 RC1 or higher) allows you to create and modify (heritable) environment variables using NppExec's commands "env_set" and "env_unset". See NppExec's help [3.1] for more details about the commands "env_set" and "env_unset".

Consider such heritable environment variables as "real" environment variables: these variables exist both inside NppExec (in a form of $(SYS.<var>) which allows you to use the var's value inside NppExec) and outside NppExec (usually in a form of %<var>% which allows to use and modify the var's value inside external tool).

NppExec allows to modify and restore a value of such existing environment variable, and to create, modify and remove such new environment variable (which did not exist before you create it in NppExec).


4.1. NppExec's Console behaviour

By default, NppExec's Console is automatically shown each time you execute some NppExec's script. The reason is simple: usually script execution assumes some output which is needed or at least may be usefull for user.

However, you may want some of your scripts to be executed silently (i.e. without showing NppExec's Console) or even want to force NppExec's Console to be closed. And NppExec allows you to do this using its command NPP_CONSOLE.

You can use

NPP_CONSOLE ?

in the beginning of your script in order to keep current Console's state. It means that hidden (closed) Console remains hidden and shown (opened) Console remains shown.

Also you can use

NPP_CONSOLE 0

to hide the Console, and

NPP_CONSOLE 1

to show the Console during script execution.

Type "help npp_console" in NppExec's Console for more details.


4.2. Environment

NppExec allows you to specify the environment (i.e. environment variables) for any program you start from NppExec. You can do it from NppExec's scripts or directly from NppExec's Console window. You can set or remove/restore such environment variables using NppExec's commands ENV_SET and ENV_UNSET.

For example, you can set your own value of PATH:

ENV_SET PATH = C:\temp  // modified

Now you can start cmd.exe (from NppExec's script or NppExec's console) and type "echo %PATH%" to ensure that the value of PATH is now "C:\temp". Type "exit" to exit cmd.exe and then execute this NppExec's command:

ENV_UNSET PATH  // restored

This command restores the initial value of PATH. NppExec does not remove the PATH variable because this variable existed before it was modified with ENV_SET. In the same time, you can create and remove new environment variables:

ENV_SET new_environment_variable = Hello  // created
ENV_UNSET new_environment_variable        // removed

Such environment variables can be used (and modified) by any program you start from NppExec. Also, values of such variables can be used by NppExec in a form of $(SYS.variable_name). For example:

ENV_SET a = My Variable  // created:  a=My Variable
echo $(SYS.a)            // prints:   My Variable
ENV_SET a = aaa          // modified: a=aaa
echo $(SYS.a)            // prints:   aaa
ENV_UNSET a              // removed

I.e. you can use "$(SYS.variable_name)" to read the variable's value and use "ENV_SET variable_name = value" to set the variables's value.

Type "help env_set" in NppExec's Console for more details.

Good way to set your environment is to do it inside NppExec's start-up script. You can specify your start-up script in NppExec's Advanced Options. This script will be executed each time Notepad++ starts. For example, you can create similar script:

// don't show Console if it's hidden
NPP_CONSOLE ?
// set our environment variables
ENV_SET NPPHOME = $(NPP_DIRECTORY)
ENV_SET TCCHOME = C:\tools\tcc\tcc.exe
// restore initial value of PATH
ENV_UNSET PATH
// set our value of PATH
ENV_SET PATH = $(SYS.NPPHOME);$(SYS.TCCHOME);$(SYS.PATH)
// clear Console screen
CLS

The first command ("NPP_CONSOLE ?") forbids the Console to be shown if it's hidden - this is usefull at Notepad++'es start-up.

The two following commands set new environment variables: NPPHOME and TCCHOME. These environment variables can be used by any program you start from NppExec.

The following command ("ENV_UNSET PATH") restores the initial value of PATH if it was previously modified by NppExec. Of course, it can not be modified by NppExec before its start-up script is executed, but you may execute the start-up script again (using NPP_EXEC or from NppExec's "Execute..." dialog), so it may be important to restore the initial value of PATH before modifying it. Otherwise, the value of PATH may grow again and again - each time you call the start-up script explicitly or execute another script which modifies the PATH variable.

The next command sets the new value of the PATH variable. Now PATH includes both NPPHOME and TCCHOME, so you can type just "notepad++" or "tcc" in order to use Notepad++'es command line switches or to run tcc.

Finally, the last command ("CLS") clears NppExec's Console's output, so the Console will contain no text when you open it.


4.3. Run-time parameters

NppExec supports several different ways to use run-time parameters which you can vary according to your needs.

The first line of each section below shows how the run-time parameter(s) can be set, and the second line shows how these parameters can be used.

  1. Passing parameters to a script (to use them inside the script):
    NPP_EXEC "my script" "param 1" "param 2"
-> $(ARGV), $(ARGV[1]), $(ARGV[2]), ...
  2. Run-time input (sets NppExec's variable $(INPUT) and so on):
    INPUTBOX "Input some value:" : "default value"
-> $(INPUT),$(INPUT[1]), $(INPUT[2]), ...
  3. User's variables (internal NppExec's variables):
    SET variable = value
-> $(variable)
  4. Environment variables (can be modified also outside of NppExec)
    ENV_SET variable = value
-> $(SYS.variable)


4.4. Using cmd.exe

NppExec by itself does not support standard console commands such as "copy", "move", "mkdir", "for" etc. Actually, these commands are part of system's command interpreter (cmd.exe). So, you can use cmd.exe to perform such commands. For example, you can type the following commands in NppExec's Console or inside NppExec's script:

// create a directory C:\Backup
cmd /c mkdir C:\Backup
// save current Notepad++'es file
NPP_SAVE
// copy current file to C:\Backup
cmd /c copy "$(FULL_CURRENT_PATH)" "C:\Backup\$(FILE_NAME)" /Y
// change current directory
cd C:\Backup
// list all .txt files in C:\Backup
cmd /c for %f in (*.txt) do @echo %f

NppExec by itself can not redirect console program's output into a text file. And, again, you can do it via cmd.exe:

cmd /c program.exe >program.txt

or even

cmd /c for /? >for.txt

By the way, cmd.exe allows to execute several commands one after another while each previous command is completed successfully. For example:

cmd /c for /? >for.txt && type for.txt
cmd /c C: && cd C:\Backup && for %f in (*.txt) do @echo %f

You can always type

cmd /?

for more details about cmd.exe and its commands. You'll be surprised how powerful it is :)

Don't forget you can execute .bat and .cmd files in the same way as executable files [3.3] - but the file extension (.bat or .cmd) can not be omitted in this case. The batch files (.bat or .cmd) allow to implement sequences of commands with simple algorithms, so you can use them when single cmd's commands are not enough.


4.5. Console output redirection

By default, when you run some console program using NppExec, the program's output is shown in NppExec's Console. It is possible because the console program is started as a child process of NppExec. NppExec uses pipes to redirect child process'es output to NppExec's Console window and to redirect user's input from NppExec's Console window to child process'es input. Such approach has several known limitations:

- no output may be shown until child process ends (if this child process performs a lot of operations without explicit flushing of its output);

- no output may be shown while child process waits for initial input (this may happen with some interpreters, but does not happen with cmd.exe);

- stdout and stderr output may be mixed (stdout and stderr are redirected into the same pipe);

- no output or incorrect output may happen when child process requires "real" console screen buffer.

The advantages:

+ NppExec's Console supports ANSI (Windows), OEM (DOS) and UTF-8 output and input (the standard console supports just OEM or ANSI);

+ NppExec's Console allows to change the console output using NppExec's Exclude/Include and Replacing filters;

+ NppExec's Console allows to highlight warnings/errors and process them using NppExec's Highlight filters.

If you want your console program's output to be redirected into a text file, you can use something similar to the following:

cmd /c program.exe >C:\temp\out.txt

This will redirect the output of 'program.exe' into a text file 'out.txt' inside 'temp' folder on your drive C (this folder must exist).

Then you can open this text file in Notepad++:

NPP_OPEN C:\temp\out.txt

Thus, you can use the following NppExec's script:

SET OUTFILE = C:\temp\out.txt
cmd /c program.exe >$(OUTFILE)
NPP_OPEN $(OUTFILE)


4.6.1. Applying external tool to selected text

Let's suppose you want to apply some AWK program to your selected text in Notepad++.

The first thing you require is NppExec plugin ;)

The second thing you require is an AWK executable, for example, "awk95.exe" or "gawk.exe".

When you want to apply some AWK program to your selected text, this AWK program must exists, isn't it? So, create a file "do.awk" in your Notepad++'s folder. The full path to this file is "$(NPP_DIRECTORY)\do.awk".

OK, the file is created, now you need some AWK program. Open the "do.awk" in Notepad++ and type your program, for example:

{ print $0 }

This simple AWK program will print each record (i.e. text line) from the input file given.

Now, open another file in Notepad++ and select some text (few lines, for example).

Now you have the selected text and a tool (awk95.exe or gawk.exe) you want to apply to this selected text.

The only thing remaining is NppExec's script which will allow you to do what you want.

Press F6 (or Plugins -> NppExec -> Execute...) and type:

// full path to AWK executable
set AWK_EXE = C:\tools\awk\awk95.exe
// this temporary file name will be used
set TEMP_FILE = $(SYS.TEMP)\npp_sel.txt
// save current selection as ANSI text file
SEL_SAVETO $(TEMP_FILE) :a
// run do.awk for this file
"$(AWK_EXE)" -f "$(NPP_DIRECTORY)\do.awk" "$(TEMP_FILE)"

Save this script as "do.awk on selected text" or whatever you want.

Press OK.

You will see the AWK's output in the NppExec's Console window. You can copy it from there with Ctrl+C.

As you understand, such approach can be used for any command-line external tool such as grep, php and so on.

Good luck!


4.6.2. Calculating

Of course, you can use external tools for calculations. All you need to do is to select the text which contains some mathematical expression and call NppExec's script which would allow to calculate it.

For example:

set AWK_EXE = C:\tools\gawk\gawk.exe
"$(AWK_EXE)" "BEGIN { print $(CURRENT_WORD) }"

This simple script allows you to calculate such expressions as "1 + sin(3)/4" or "(2 + 0x10)*3" etc.

You can modify the file "do.awk" from previous example [4.6.1] in order to calculate an average value of numbers given as the following table:

1.  552
2.  554
3.  549
4.  551

Here is the AWK script (i.e. the content of "do.awk") which calculates an average value of numbers in the second column:

BEGIN {
   Sum = 0
   N = 0
}
NF == 2 {
   Sum += $2
   ++N
}
END {
   print "avg = " Sum/N " (Sum = " Sum ", N = " N ")"
}

Now, all you have to do is to select the given table (see above) in Notepad++ and execute NppExec's script "do.awk on selected text". You will see the following output in NppExec's Console:

avg = 551.5 (Sum = 2206, N = 4)

Of course, you can use other external tools for calculations of selected expressions or table data. The output of such external tools will be shown in NppExec's Console. Also you can redirect such output into a text file and then open that text file in Notepad++ [4.5].


4.7.1. Compiling simple C-programs

You can edit, compile & run simple C-programs directly from Notepad++. All you need is the following:

1) download tcc (tcc is a freeware C-compiler, about 1 MB in archive)

2) unpack tcc to "C:\tools\tcc" or create "tcc" subfolder in your Notepad++ folder (for example, "C:\Program Files\Notepad++\tcc") and unpack tcc there

3) run Notepad++ and call NppExec's "Execute..." dialog (Plugins -> NppExec -> Execute... - or just press F6).

4) type these commands in the "Execute..." dialog:

4.1) if tcc is placed in C:\tools\tcc

// save current file
NPP_SAVE
// compile & run with tcc
C:\tools\tcc\tcc.exe "$(FULL_CURRENT_PATH)" -run

4.2) if tcc is placed in $(NPP_DIRECTORY)\tcc

// save current file
NPP_SAVE
// compile & run with tcc
"$(NPP_DIRECTORY)\tcc\tcc.exe" "$(FULL_CURRENT_PATH)" -run

5) save these commands: press Save... button, type "tcc-run" (this is a name of your script) and press Save.

Now, when you have a C source file opened in Notepad++, you can call NppExec's "Execute..." dialog, select "tcc-run" and press OK to compile & run this C-file. In this case tcc works as an interpreter for your C source file (its command "-run" does it).


4.7.2. Compiling Java

[This article uses some text originally posted by Sam (sammi101082) in Notepad++'es Help forum.]

[ Sam: ]

To compile a Java file, all you have to do is the following:

  1. Navigate to Plugins -> NppExec -> Execute. (Default Shortcut key is F6)
  2. In the new popup window, type this
    3. cmd /c cd "$(CURRENT_DIRECTORY)" && "%JAVA_HOME%\bin\javac" "$(FULL_CURRENT_PATH)"
  3. Click on "Save" and give it a name say "Java Compile".
  4. Bingo. You are there. Now any Java file you are editing in Notepad++ can be compiled by pressing F6 and choosing this script "Java Compile". It will compile the Java class for you. This is irrespective of which directory you are in.

The NppExec plugin can be used to execute any executable as you would from a command prompt. For running the compiled Java class, the script is:

cmd /k cd "$(CURRENT_DIRECTORY)" && "%JAVA_HOME%\bin\java" "$(NAME_PART)" && exit

P.S. Remember to set the JAVA_HOME environment variable. To check if it is set, open a command prompt and type java.

[ DV: ]

Actually, the same thing can be done without explicit usage of 'cmd.exe'. You can use several commands (one command per line) in NppExec's script, and these commands will be executed one by one. For example:

cd "$(CURRENT_DIRECTORY)"
"$(SYS.JAVA_HOME)\bin\javac" "$(FULL_CURRENT_PATH)"

Also you can use ENV_SET to set environment variables such as PATH or JAVA_HOME for any process (program) you start from Notepad++ [4.2].


4.7.3. Using Visual Studio's compiler (cl.exe)

If you want to run 'cl.exe' from NppExec, it requires some additional environment. Such environment can be set using a batch file or using NppExec's command ENV_SET [4.2].

1. Using a batch file

To use a batch file, create a file 'cl.cmd' with similar text:

REM cl.cmd
REM Visual Studio 8.0 (2005) Express
@echo off
Set VCDIR=C:\Program Files\Microsoft Visual Studio 8\VC
Set VSCOMMON=C:\Program Files\Microsoft Visual Studio 8\Common7\IDE
Set MSSDK=C:\Program Files\Microsoft Platform SDK for Windows Server 2003
Set PATH=%VCDIR%\bin;%MSSDK%\bin;%VSCOMMON%;%PATH%
Set INCLUDE=%MSSDK%\include;%VCDIR%\include;%INCLUDE%
Set LIB=%MSSDK%\lib;%VCDIR%\lib;%LIB%
cl.exe %*

Now, use something similar to

cl.cmd "$(FULL_CURRENT_PATH)"

to compile your source file(s).

As you can see, the VC's environment is handled inside the 'cl.cmd' in this case. I.e. it is handled by the system (well, by cmd.exe) and not by NppExec.

2. Using ENV_SET

The initialization of environment variables for VC will look similar to the following:

// setting NppExec's internal (user) variables
SET VCDIR = C:\Program Files\Microsoft Visual Studio 8\VC
SET VSCOMMON = C:\Program Files\Microsoft Visual Studio 8\Common7\IDE
SET MSSDK = C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2

// saving previous values of environment variables (just in case)
SET PATH_0 = $(SYS.PATH)
SET INCLUDE_0 = $(SYS.INCLUDE)
SET LIB_0 = $(SYS.LIB)
// setting NppExec's child process'es environment variables
ENV_SET PATH = $(VCDIR)\bin;$(MSSDK)\bin;$(VSCOMMON);$(SYS.PATH)
ENV_SET INCLUDE = $(MSSDK)\include;$(VCDIR)\include;$(SYS.INCLUDE)
ENV_SET LIB = $(MSSDK)\lib;$(VCDIR)\lib;$(SYS.LIB)

// executing the child process with specified environment variables
rc /r /Fo"$(CURRENT_DIRECTORY)\Resources.res" "$(CURRENT_DIRECTORY)\Resources.rc"
cl.exe "$(FULL_CURRENT_PATH)"

// restoring previous values of environment variables
ENV_SET PATH = $(PATH_0)
ENV_SET INCLUDE = $(INCLUDE_0)
ENV_SET LIB = $(LIB_0)

Don't forget that ENV_SET does not understand such form of existing environment variables as "%PATH%" because NppExec does not accept such declaration. "$(SYS.PATH)" should be used instead of "%PATH%".

In general, it's not a good idea to set and then restore the environment every time it is needed by some tool. Instead, you can set all the required environment in NppExec's start-up script [4.2]. Such approach would allow you to use any of your tools without further specifying of full paths or additional environment variables.


4.7.4. Compiling ANY source file

Compiling any source file using NppExec assumes the following:

- usage of external compilers/interpreters to compile (and run) your source file(s);

- creating specific NppExec's scripts for compiling (and running) specific source files;

- creating general NppExec's script which would allow to use different compilers/interpreters for different source files;

- usage of NppExec's Highlight filters to parse the compiler's/interpreter's output (warnings, errors etc).

You can find all this information inside the file "NppExec_Guide.txt". Please refer to.


About

NppExec | A plugin for Notepad++, developed by DV.
User Manual

The user manual for NppExec written by DV using KeyNote 1.6.5. There are three versions:

  • NppExec_Manual.knt - User Manual in Keynote format
  • NppExec_Manual.txt - User Manual in text format
  • NppExec_Manual.chm - User Manual in compiled HTML format
Notepad++ | A generic source editor (text editor with advanced features for programmers) created by Don HO.


Questions/suggestions?

Did not find an answer for your question? You can try the following:
  1. Read this manual once again ;)
  2. Visit https://sourceforge.net/projects/npp-plugins/ and search NppExec's forum for the answer or ask your question there.
Have a suggestion? Visit NppExec's forum and let me know.


Acknowledgment

Acknowledgments

  1. This CHM file has been created with the generous support of AbeeTech, developers of Chm Maker (www.abeetech.com).
  2. Greg Webb for converting the original text from Keynote to CHM.


Guide: Using NppExec to compile sources with associated compilers

As a Notepad++ user, did you ever think about ability to compile your source
file with its associated compiler in a single action?
You may use the NppExec plugin to perform certain actions on your files, but
what about the automatization? What if you want your .c files to be compiled
with tcc, .cpp files to be compiled with g++ and .awk files to be interpretted
with gawk automatically, without explicit call to required compiler or
interpretter? Is it possible?
Yes, NppExec ALREADY allows you to do this. All you need is some imagination
and several things to do. And I'm about to tell what is needed.

Let's begin with several theoretical questions.
At first, how can NppExec understand which compiler/interpretter is required
by your current source file? NppExec is not a compiler, it does not have
any information about your file and does not know what to do with it.
Moreover, Notepad++ itself is not such IDE as Visual C++ Express or Dev-C++,
it does not include any compiler and also does not know what to do with your
source file.
So, the only way to compile your source file with required compiler is to tell
Notepad++ (to tell NppExec in our case) _which_ compiler to use and _how_ to
use it.
This is the solution which you may use already - explicit usage of certain
compiler/interpretter with certain source file. For example, you may want to
compile and run your .c source file with tcc. A simple NppExec's script can
be created for this purpose:

  "C:\tools\tcc\tcc.exe" "$(FULL_CURRENT_PATH)" -run

The full path "C:\tools\tcc\tcc.exe" specifies a path to required compiler;
Notepad++'es environment variable "$(FULL_CURRENT_PATH)" specifies full path
name to your current source file; and "-run" in tcc's command line means
"run compiled source". The full path was given in quotes, because, in general,
it can contain spaces.
Now, we are talking about NppExec's script. It assumes the script has been
created and saved with some name which identified that script. If you are
not sure about NppExec's script creation & saving, let me guide you.

To create & save some NppExec's script, do the following:
1) Open NppExec's "Execute..." window: press the hotkey (F6 by default)
   or select (main menu) Plugins -> NppExec -> Execute...
2) Type the text of your script in the "Execute..." window. For example:

     "C:\tools\tcc\tcc.exe" "$(FULL_CURRENT_PATH)" -run

3) Save this new script: press the "Save..." button, type your script name
   (for example, type "run@.c") and press Save.

Now you can compile & run any single .c file opened in Notepad++. To do it,
press F6 (default hotkey for the "Execute..." window), select "run@.c" in
the combo-box and press OK.
You can press Ctrl+F6 (by default) to execute the same script again without
showing the "Execute..." window.

As you can see, currently you have to call the "run@.c" script explicitly
in order to compile & run your .c source file. Thus, to compile & run
another source file (.cpp, .asm, .php, .lua, ...) you also have to call
corresponding script explicitly. [The last sentence assumes you have created
separate scripts for every language you use (.cpp, .asm, .php, .lua, ...)]
However, we don't want to call required script explicitly. We want NppExec
to call the "run@.c" script for a .c file and call different script required
for different (.cpp, .asm, .php, .lua, ...) file automatically.
So, a question: how can we do it?
The first part of the answer is in your source file's extension. There is
such environment varible as $(EXT_PART) which contains the extension of
current file opened in Notepad++.
The second part of the answer is in NppExec's internal command NPP_EXEC.
As you probably know already, this command expects an existing script name
or a script file name as its first argument. The purpose of this command is
to execute specified NppExec's script.
Thus, if you use NPP_EXEC command, and its first argument (a script to be
executed) depends on current file's extension, you can call different scripts
for different file types from one starting script!
Let's examine it in more detail.

We are about to create a general NppExec's script which would allow us to
call different scripts for different source files depending on their extension.
In other words, we use the NPP_EXEC command to call required script, and the
script name depends on current file's extension. The name of the script above,
"run@.c", consists of two parts: the prefix "run@" and the extension ".c".
As the file's extension can be got from Notepad++, we can write general form
of this script's name: "run@$(EXT_PART)".
It's not hard to understand that this script's name transforms to "run@.cpp"
for .cpp source file, "run@.lua" for .lua source file and so on.
So, let's create our general compile-or-run script which will be called each
time you want compile or run ANY source file:

  // save current file
  NPP_SAVE
  // construct the script name to be called
  SET Compiler = run@$(EXT_PART)
  // call the script
  NPP_EXEC "$(Compiler)"

Save this script as "compile_or_run". Now this is your only starting script
which will allow you to compile or run ANY source file. I.e. press F6, select
the "compile_or_run" and press OK in order to compile or run ANY source file.
However, don't forget that this script requires existing scripts for every
source file you want to compile. Thus, "run@.cpp" must exist to compile a .cpp
file, "run@.php" must exist to compile a .php file and so on.
You can see several examples of such scripts below:

  // run@.c
  "C:\tools\tcc\tcc.exe" "$(FULL_CURRENT_PATH)" -run

  // run@.cpp
  SET g++ = C:\Dev-Cpp\bin\g++.exe
  SET obj = $(CURRENT_DIRECTORY)\$(NAME_PART)
  "$(g++)" -c "$(FULL_CURRENT_PATH)" -o "$(obj).o"
  "$(g++)" "$(obj).o" -o "$(obj).exe"
  NPP_RUN "$(obj).exe"
  UNSET obj
  UNSET g++

  // run@.awk
  "C:\tools\gawk\gawk.exe" -f "$(FULL_CURRENT_PATH)"

All of these scripts will be started automatically from the "compile_or_run"
script for .c, .cpp and .awk files. You can create more "run@..." scripts to
support any source file extension you use.

Now, let's return to our "compile_or_run" script. It uses the NPP_EXEC command
which supports a script file name as its first argument. What does it mean?
It means you can execute NppExec's script from a file.
As you can see, current implementation of the "compile_or_run" script requires
a lot of additional "run@..." scripts to exist together with other scripts
which you may want to call explicitly. In the same time, you do not call the
"run@..." scripts explicitly. So, the "run@..." scripts may be undesired in
the NppExec's script combo-box (in the "Execute..." window).
Thus, you may modify the "compile_or_run" script in order to call script files
instead of internal scripts. For example:

  // compile_or_run
  NPP_SAVE
  SET Compiler = C:\tools\NppExec Scripts\run@$(EXT_PART).txt
  NPP_EXEC "$(Compiler)"

Now you must create a directory "C:\tools\NppExec Scripts" which contains
the following files: "run@.c.txt", "run@.cpp.txt", "run@.awk.txt" and so on.
The text of these files must be exactly the same as in the scripts "run@.c",
"run@.cpp" and "run@.awk" above.
E.g. the file "C:\tools\NppExec Scripts\run@.awk.txt" must contain

  "C:\tools\gawk\gawk.exe" -f "$(FULL_CURRENT_PATH)"

and so on for other file extensions (.c, .cpp, ...).
To read more information about the NPP_EXEC command, open the NppExec's
Console in Notepad++, and type:

  help npp_exec

and press Enter.
To get general NppExec's help information, type just

  help

and press Enter.

One more thing regarding NppExec usage. Compiler/interpreter's output is shown
in NppExec's Console and can be parsed by NppExec. It means that different
error/warning messages can be shown using different colours, and you can jump
to corresponding line in the source file by double-clicking on such warning
or error message in the NppExec's Console.
To enable such parsing, you must tell NppExec what form do these error/warning
messages have (i.e. specify the message mask). You can configure it from
(main menu) Plugins -> NppExec -> Console Output Filters... -> HighLight.
That window contains an example of parsing (highlighting) masks for GCC:

  Example 1: %ABSFILE%:%LINE%: warning:* => detects the warning lines from gcc
  Example 2: %ABSFILE%:%LINE%: error:* => detects the error lines from gcc

I.e. to enable detection (parsing) of GCC errors in NppExec, you must specify
the mask of the compiler's error line ("%ABSFILE%:%LINE%: error:*") and,
optionally, specify Red, Green and Blue components of the line to be
highlighted and, also optionally, this line can be shown using Italic, Bold
and/or Underlined font typeface. And, of course, corresponding check-box must
be checked to enable this parsing mask.
For example, if you want to see GCC's errors as Bold lines with Red colour
and GCC's warnings as Italic lines with Blue colour, it will look similar to
the following:

  [v] [%ABSFILE%:%LINE%: error:*       ]  0x80 0x00 0x00  [ ] [v] [ ]
  [v] [%ABSFILE%:%LINE%: warning:*     ]  0x00 0x00 0x80  [v] [ ] [ ]

Well, seems it's time to finish the guide. I hope this guide was usefull for
you, because otherwise it was waste of time for both of us: the reader (you)
and the writer (me).
If you like this guide, I hope it will inspire you to find your own usefull
application of NppExec's functions, and maybe to share it with us.