Macros provide a powerful system for inserting commonly used patterns of code into documents and a gateway to UNIX and other script functionality into the editing process.
To invoke macros from the editor (using the contextual menu is also possible) type the macros command enclosed by [ and ] brackets (they are auto-paired by default so this is 1 key motion) and press the Tab key. Depending on the macros output method the results will be inserted into the document or otherwise.
The PHP macro shown below (with the command name func) will insert an empty function into the document and move the cursor to the proper location.
[func] |
Optionally macros support parameters which give the macro additional information and make them dynamic. Parameters are placed within ( and ) characters and separated with commas ",". As explained in the section Macro Syntax parameters are defined as $1, $2, $3 etc... respectively. Not all macros support parameters so you should inspect the macros you intend to use in the editor window before using them. Also note that by holding the cursor over a macro in the menu and it's syntax will be shown in a floating help window.
The example shown below expands upon the previous PHP macro but with parameters. The first parameter DoSomething is used for the functions name.
[func(DoSomething)] |
Below is the macro definition for the previous 2 examples. More information on the syntax can be found here.
function $1 ([$2]) { $CURSOR } |
It is possible to override the output method of a macro by using pipes (named after the UNIX feature). To use pipes insert the > character after the full command.
Consider the example below that prints the output of the link macro to the console instead of the default location.
[link(www.web-scripter.com) > console] |
Macros can be inserted into the open document by using the contextual menu. When using the contextual menu it will take the current selection from the document and pass it to the macro as the first parameter ($1). This has the effect of wrapping the selection with the macro (providing the macro contains the $1 parameter).
The macro editor is where you can create new macros, edit existing macros and change global macro variables. Open the macro editor from the Tools menu.
The list is filtered by language which can be changed in the popup button above the macro list. Macros in the Common category will be available to all files at all times, otherwise you can only use macros from a specific language in a file of that type.
Macros consist of the following details:
|
Macro editor window.
Macros follow a simple syntax that is easy to learn so you can start writing macros right away.
Macros have the following syntax concepts:
|
Parameters allow the user to send data into the macro while typing and really are what makes macros a powerful feature. Parameters take the form of the $ character followed by a number representing the index of the parameter.
The Macro: <a href="$1"> Typed: [link(www.apple.com)] Becomes: <a href="www.apple.com"> |
Text wrapped in [ and ] brackets (a parameter must be within the brackets also) are optional on condition that the parameter inside the brackets is not empty. This feature is useful if you want your macro to omit certain information if the user has not specified a parameter.
For example take the link macro below (for printing an HTML link) which will omit the name attribute if the second ($2) parameter is not present.
The Macro: <a href="$1" [name="$2"]> Typed: [link(www.apple.com)] Becomes: <a href="www.apple.com"> |
You can include shell code (explained here) into macros which execute the command like from the shell. To interpolate shell code into macros place the code inside back ticks (`).
For example this trivial macro which uses the UNIX command whoami which prints the name of the logged in user.
The Macro: Hello world, this is `whoami`. Becomes: Hello world, this is macuser. |
Some times you might be using a macro that contains multiple parameters and would like to use the second parameter but not the first. To tell the parser to ignore the parameter you can insert the ^ character instead of a value.
As an example we will expand on the macro shown in Optional Parameters. Note that if the empty parameter was not used the second would become the first and you would not get the results you were expecting.
[link(^,Apple.com)] |
If you leave a parameter for a macro blank a default value can be inserted instead. Default values are within { and } curly brackets and must follow directly after the parameter.
In the following example if the first parameter ($1) was omitted the text "www.domain.com" would be inserted instead.
<a href="$1{www.domain.com}" [name="$2"]> |
If the macros output method is default then you can specify where the cursor is to be set in the document by using the $CURSOR variable.
There are a number of built-in variables that provide dynamic information which are mainly used for shell macros. Built-in variables follow the same syntax as parameters and are prefixed by the $ character.
Currently the supported variables are:
|
In the macro editor you can add variables which are global to all macros. Variables are useful for including dynamic values which could affect multiple macros.
To add new variables:
|
For the following example assume you have created a variable named SERVER with the value "web-scripter.com" and defined the fictional macro connect which opens a FTP connection. Note that you should not include the dollar sign ($) before the variable name.
The Macro: ftp_connect("$SERVER", "$1", "$2"); Typed: [conn(user,****)] Becomes: ftp_connect("web-scripter.com", "user", "****"); |
Using the variable $SERVER will now insert the proper value into all macros.
WebScripter allows you to script macro functionality by executing the text like a command from the shell. Using shell macros is the gateway to UNIX and will allow you to add dynamic functionality to WebScripter.
To use shell macros set the action in the macro editor to Shell and the text will be treated like that typed at the command line.
As an example take the following simple UNIX command which will take the path of the document and sort it's contents. To make the command useful you would set the output method to replace which would override the document with the results from the command.
cat < $PATH | sort |
The HTMLTidy integration in WebScripter is implemented as a shell macro. Here's how the command looks:
$SUPPORT/tidy -i -q -wrap 0 -mac "$PATH" |
Using the $SUPPORT variable it finds the tidy program in the application package, sets some options then passes the documents path in. Because the output method is replace the output overwrites the current document.
When editing macros you can choose from a list of output methods which control how the results from the macro are displayed.
|
By formatting the output of a shell macro and selecting the error list output method WebScripter can open a graphical error browser used for navigating the items in the list. Error lists can be used to add custom error handling for various languages.
The format is as follows. Note that each error must be seperated by a line break.
message|line|column|file |
WebScripter implements HTML Tidy syntax check by using errors lists. Tidy is executed from a PHP script then it parses the results from tidy and prints them to STDOUT in the proper format.
As an example this script can be found at: WebScripter.app/Contents/SharedSupport/tidy.php