Working with multiple-file scripts and packages

This section deals with the topics concerning scripts location on disk and their organization.

Where user scripts are stored?

In current version of VSScript, there is single root directory where all of the scripts are stored. You can configure the path of the directory using Preferences dialog. By default, it is a path inside VSScript configuration directory.

Inside the directory specified above, there is a set of subdirectories. Each subdirectory corresponds to a package. You can have as many packages as you want. Inside each package there are files with .vsscript extensions. These files are actual scripts written in Lua language.

Packages and scripts in the editor window

The script editor window offers a simple but effective mechanism to manage scripts and packages. There are two selection boxes on the toolbar. The first one is for package selection. The second one selects a script from current package. So, in order to edit particular script, first choose the package, then open a list in the second selection box to choose the script. The editor will load the script and switch to it.

Changing the package does not switch currently edited script, so that you can just browse available packages if you want. It also means that the package currently selected is not necessarily the one which currents script belongs to. You can determine actual parent package by looking at the title bar of the editor, as there is always current package and script name displayed.

Built-in package

VSScript implicitly defines one special package, named just Builtin. This package does not correspond to any directory on disk, it exists only in memory. There are two scripts inside it. The Library script contains a lot of utility functions defined in std and vsu namespaces. Contents of this library are always visible for each user script, without any need to import it explicitly. Second built-in script is called Recorder. This is where recorded user actions are written. It is an equivalent of a "temporary macro" from standard macro recorder. You can save it to some real script file clicking the Save button. The Recorder script also can be replayed and debugged, so you need not to save if you only want to use the macro briefly, and then discard it.

Importing script libraries

The packages feature is not only a way to organize multiple scripts. It is also a tool allowing to make complex, multi-file script programs. Each script can reference functions defined in other scripts, whether in the same or other package. In order to import a script file, you need to write require directive in the following format:

    require ( "Package/Script" );

Substitute your own package and script name. Do not write .vsscript extension, as it is assumed implicitly.

The require directive is actually a standard function defined by Lua interpreter. It works roughly like #include directive in C (but it is not preprocessor), or import in Java.

Recommended application is to divide a complex script into separate files and making a package.

Do not write a require directive to import standard Builtin/Library script, as VSScript does it automatically. Explicitly importing it will trigger an error. Also importing Builtin/Recorder is not allowed (and it does not make a sense anyway).

Creating new packages and scripts

To create a new package, click New package... option on VSScript editor menu. You will be asked for the package name. Only letters and digits are allowed.

Similar feature exists for script files. Click New script... option and enter script name without an extension. The script will be created within currently selected package. Adding new scripts to the Builtin package is not allowed.

Because packages are just subdirectories under the root script directory, you can add a package by just creating appropriate directory. The same applies to script files. Copy the files to the directory to make them visible inside the package. If you want to delete a script or package, just delete corresponding file or directory.

Custom commands and key bindings

VSScript allows to bind keyboard shortcuts to scripts. In order to make such binding, you have to create a custom command first. A custom command is a Visual Studio command which belongs to VSScript add-in, however it is not predefined but rather defined by the user. In some sense it might be called a dynamic command, because you can create and delete these commands as you wish. Each such command is associated with particular script in some package. The script is determined from the command name, which has the following format:

    SoftErgVSScript.AddIn.Custom_<package>_<script>

The first part is fixed, as it tells Visual Studio that it is a VSScript add-in command. The "Custom" word tells VSScript that it is a custom command. Next comes the package name, and finally the script name (without an extension). Executing such command in Visual Studio triggers execution of the script. You can execute the command either using the Command window (available under "View/Other windows" menu), or binding a keyboard shortcut with Customize dialog (click "Keyboard" button to show shortcuts editor). These mechanisms are all standard VS features. VSScript integrates into it by registering these dynamic commands.

Creating and deleting custom commands

You can create or delete a custom command using Custom command manager option from VSScript menu. It opens a simple dialog containing a list of currently defined commands, as well as Add and Delete options.

When adding a command, you must specify its name. Enter two words separated by a dot. The first one is the package name, and the second one is the script name. VSScript will automatically convert it to the format described above, adding necessary parts. Hence do not write "SoftErgVSScript.AddIn.Custom_" prefix, nor the file extension.

The display name is arbitrary and it is used in context where the command name is visible. Subsequent releases of VSScript will allow to add custom commands to menus, and this name will become usable there.

Custom command can also launch a multi-file script. Just name it appropriately, so that it points to the main script of the package.

To delete a command, select it on the list an click the Delete button.

Table of Contents


Copyright (C) 2012-2015 Soft-Erg. All rights reserved.