Both WebScripter and PascalGladiator’s editor share the same macro system but it has not been documented in PascalGladiator. The following explanation is modified from the WebScripter manual and please note there is no graphical editor in PascalGladiator. You can however edit the .plist manually (no problem since you’re a Mac programmer) in PascalGladiator.app/Contents/CodeSense/Pascal.macros.plist.
Topics
- 5.0 Using Macros
- 5.1 Using The Contextual Menu
- 5.2 Macro Editor
- 5.3 Macro Syntax
- 5.4 Variables
- 5.5 UNIX Shell Macros
- 5.6 Output Methods
5.0 Using Macros
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.
Parameters
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.
Below is the macro definition for the previous 2 examples. More information on the syntax can be found here.
function $1 ([$2]) {
$CURSOR
}
|
Pipes
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]
|
5.1 Using The Contextual Menu
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).
5.2 Macro Editor
No graphical macro editor in PascalGladiator for now, sorry!
5.3 Macro Syntax
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.
- Empty Parameter.
- Default Values.
- Optional Parameters.
- Interpolated Shell Code.
- Positioning the cursor.
- Built-in Variables.
|
Parameters
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">
|
Optional Parameters
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">
|
Interpolated Shell Code
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.
|
Empty Parameters
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.
Default Values
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"]>
|
Positioning the cursor.
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.
Built-in Variables
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:
- $FILE. The name of the current document.
- $PATH. The absolute path of the current document.
- $SUPPORT. The absolute path of the SharedSupport folder in the application package.
|
5.4 Variables
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:
- Click the popup button with the gear icon in the macro editor.
- Select Add Variable from the menu.
|
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.
5.5 UNIX Shell 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.
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.
5.6 Output Methods
When editing macros you can choose from a list of output methods which control how the results from the macro are displayed.
- Default. Output is written to the open document at the cursor offset or replacing the current the selection.
- Popup. Output is displayed in a floating help window.
- URL. If the output is a valid URL it is opened in the default web browser.
- Replace. Output replaces the contents of the document.
- Console. Output will open in a built-in terminal split view.
- Error List. Output is displayed in list form from a built-in split view. Note that output must be formatted properly.
|
Formatting Error Lists
There is not error list feature is PascalGladiator.
