NppEventExec

A handy Notepad++ plugin which allows you to automatically execute NppExec scripts on Notepad++ events. Compatible with recent Notepad++ and NppExec versions; see Compatibility for supported older versions.

Introduction
Installation
Usage
Releases
Compatibility
Supported Events
Compilation
Known issues
Help and support
License

Introduction

NppEventExec supports the creation, management and automatic execution of rules. A rule embodies an NppExec command to be executed for the currently active document in Notepad++ on an event. Whether the rule is executed for the current document is governed by a regular expression which the absolute file path is checked against whenever the desired event occurs. An intuitive example of a rule is: "execute the NppExec command 'Format C/C++ source' when the current file is about to be saved and it has the extension .c, .h, .cpp or .hpp."

The supported Notepad++ events are listed under Supported Events.

Installation

The prefered way to install NppEventExec is through the Notepad++'s plugin manager. However, if you wish to install it without using the plugin manager, download the latest binaries for your platform – x86 or x64 – from this repository and extract the contents to Notepad++'s plugins directory, e.g. C:\Program Files\Notepad++\plugins. For the plugin to be usable, NppExec needs to be installed as well.

Usage

Defining commands

This documentation assumes you're acquainted with NppExec. This is because NppEventExec's purpose is the automatic execution of commands which were previously defined in NppExec or the path to a file containing an NppExec script on Notepad++ events, e.g. a document is about to be saved, a new document was created etc. For additional control, you can define a regular expression which the absolute path of the active document is checked against before the execution takes place. To specify what gets executed when, NppEventExec supports the creation of rules.

Managing rules

To create or edit rules, select Plugins->NppEventExec->Edit rules... from Notepad++'s main menu. This opens the rule management dialog. To edit a specific rule either select the rule and then click on the edit button in the toolbar or double-click on the rule in the list. The rule attributes are as follows:

Attribute	Meaning
Enabled?	When true, the rule is considered active and will be executed when the conditions are met. Otherwise the plugin will ignore the rule. Useful for example if you want to prevent the rule from executing for a short while, but don't want to delete it permanently.
Event	The Notepad++ event the rule will be executed on.
Name	The name of the rule. It cannot be empty and cannot begin or end with white-space characters. The rules are named solely for convinience.
Regex	The regular expression that the file system path of the currently active document is checked against before executing the rule.
Command	The name of the NppExec command or the absolute path to a file containing an NppExec script to execute when the conditions are met.
Background?	When true, the rule is executed in the background, i.e. it will allow the user to continue working in Notepad++ normally while the rule is executing. Otherwise the user will be prevented from interacting with Notepad++ until the rule finishes which makes sense for example when the document's content should not be changed during the rule's execution.

The modifications are only written to the disk when you click on the Save button. If any rules are executing, the plugin will wait until they finish or you abort them. Clicking on Reset will reset all changes you've made to the rules.

Execution queue and aborting rules

To see the rule which is currently executing as well as all scheduled rules, select Plugins->NppEventExec->Execution queue... from Notepad++'s main menu. This opens the queue dialog which allows you to abort all rules except for the rule that NppExec is currently executing.

The queue dialog opens automatically in the following cases:

when a non-background rule is executed; the dialog is shown and cannot be closed to prevent you from interacting with Notepad++;
when rule modifications are being saved, but a rule is still being executed or a number of rules are queued for execution;
when Notepad++ is closing, but a number of rules are queued for execution.

Examples

A good usage scenario for NppEventExec is auto-formatting source code files. Assuming you want to use uncrustify to auto-format for C/C++ source and you've defined your preferences in a config file somewhere. The first step is to create an NppExec command called Format C/C++ source with content similar to this. Then, open the rule managent dialog and create a new rule with the name Format C/C++ source (or any other name), the command Format C/C++ source and the regular expression .*[^.]\.(c|cpp|h|hpp). It makes sense to execute the rule before the file is saved so select NPPN_FILEBEFORESAVE and it definitely makes a lot of sense to prevent the user from modifying the contents while the rule is executing so make sure the option to block the UI is checked. Finally, enable the rule and try to save a C/C++ source file.

Technical

The executed NppExec scripts receive 2 arguments from NppEventExec, in $(ARGV[1]) and $(ARGV[2]) respectively: the buffer ID and the absolute path of the document for which the rule was executed. Bear in mind that this might not be the active document at the time the rule is actually executed.

Releases

The latest version of NppEventExec is 0.9.0. You can install it from Notepad++'s plugin manager or grab the binaries from this repository; see Installation for installation instructions. Although the plugin has grown in features since previous releases, they are yet to be put to a trial by the broad public. Therefore, please be vigilant and report any issues you encounter. Any feedback is much appreciated – share your thoughts, wishes, ideas and problems.

Compatibility

NppEventExec has been tested on 32-bit and 64-bit Notepad++. The minimal Notepad++ versions known to work are v6.9.2 (32-bit) and v7.4.2 (64-bit). Earlier versions should be compatible as well. The minimal NppExec versions known to work are v0.5.3 (32-bit) and v0.5.9.9 (64-bit). Theoretically, all versions starting with v0.2.5 should be compatible.

Every test report with other versions is greatly appreciated! Just like Notepad++, the plugin is Unicode only. ANSI versions will not be provided due to the huge effort to ensure correct operation. The only tested OS so far is Windows 7 64-bit, though the plugin also works in Wine.

Supported Events

Event	Meaning
NPPN_READY	Notepad++ was fully initialized
NPPN_FILEBEFORECLOSE	A file is about to be closed
NPPN_FILECLOSED	A file was just closed
NPPN_FILEBEFOREOPEN	A file is about to be opened
NPPN_FILEOPENED	A file was just opened
NPPN_FILEBEFORESAVE	A file is about to be saved
NPPN_FILESAVED	A file was just saved
NPPN_FILEBEFORELOAD	A file is about to be loaded
NPPN_FILELOADFAILED	A file failed to load
NPPN_FILEBEFOREDELETE	A file is about to be deleted
NPPN_FILEDELETEFAILED	The deletion of a file failed
NPPN_FILEDELETED	A file is about to be deleted
NPPN_FILEBEFORERENAME	A file is about to be renamed
NPPN_FILERENAMECANCEL	The renaming of a file was canceled
NPPN_FILERENAMED	A file was renamed
NPPN_BEFORESHUTDOWN	Notepad++ is about to shutdown
NPPN_CANCELSHUTDOWN	Notepad++'s shutdown was canceled
NPPN_SHUTDOWN	Notepad++ is shutting down
NPPN_BUFFERACTIVATED	A buffer was just activated
NPPN_LANGCHANGED	A document's language was changed
NPPN_WORDSTYLESUPDATED	A change was initiated using the word style dialog
NPPN_SHORTCUTREMAPPED	A command shortcut was remapped
NPPN_READONLYCHANGED	A read-only status was changed
NPPN_DOCORDERCHANGED	The document order was changed
NPPN_SNAPSHOTDIRTYFILELOADED	An unsaved file was restored on startup

Compilation

NppEventExec can be compiled with Visual Studio 2013 and Mingw-w64. MinGW would also work, the only problem being the missing strsafe.h header, which is essential for NppEventExec. The Mingw-w64/MinGW makefile supports the same configurations and platforms as the VS project:

make CONFIGURATION=Debug PLATFORM=Win32
make CONFIGURATION=Debug PLATFORM=x64
make CONFIGURATION=Release PLATFORM=Win32
make CONFIGURATION=Release PLATFORM=x64

The default configuration and platform are Debug and Win32 respectively. To be fully compatible with the regular expression format of Notepad++, NppEventExec depends on Boost.Regex. If you use Mingw-w64 or MinGW, edit the makefile to set the correct path and library name for Boost.Regex. When using Visual Studio, you can quickly obtain precompiled binaries with NuGet. An executable for quick testing is generated in the debug configuration, but only when using the makefile.

Known issues

Currently, there are issues when foreground rules are triggered from NppExec scripts or from the console, e.g. by saving or opening a file. Depending on the circumstances, a rule might not get executed and will be stuck in the state Waiting until it's aborted. In another case, the user may experience that rules are executed out of order. This is partly due to the single threaded nature of NppExec and partly due to unfilled gaps in the scheduling semantics of NppEventExec.

Please report any abnormal or counter-intuitive behaviour you encouter while using the plugin or just share how you are using the plugin. Any information on the patterns in which users are using NppEventExec is valuable.

Help and support

The best place to discuss the plugin and to receive help is the Notepad++ Community. You can also submit issues through the community's website or use the issues section of this repository (you need to sign in). Of course, you can also contact me privately.

Credits

The plugin is using modified icons from the set 16x16 free application icons from Aha-Soft. The said icon pack is distributed under the license Creative Commons Attribution 3.0 United States (CC BY 3.0 US). Aha-Soft makes awesome icons.

License

Distributed under the GNU General Public License, Version 3 (GNU GPLv3)

Notepad++, NppExec and the icon set "16x16 free application icons" from Aha-Soft are distributed under their respective licenses.

MIvanchev / NppEventExec