WinPTE is integrated with Perl 5.1 and has full access to Perl from macros and the command line. Perl scripts also have access to WinPTE commands, functions and files. The integration is achieved by the following:
-
[perl] function which takes a string argument which is evaluated using Perl's eval function (in the PTE package) and returns the result returned by eval.
-
perl command which takes the rest of the command line text and executes it using the perl eval function (again in the PTE package by wrapping it in { package; PTE; ...... } )
-
tied variables to expose internal state of WinPTE to perl.
-
classes to represent the WinPTE Cursor, Mark (a selection) and a tied hash of all currently open files in WinPTE.
-
functions in the PTE package that allow perl to invoke WinPTE functions and commands.
-
File I/O integration allows perl to open and perform file operations on a files open in WinPTE as if they were disk files. All modifications through perl's file I/O are part of the standard WinPTE undo facility and can be undone just like all other file modification in WinPTE. If you prefix the file name passed to perl open command with 'PTE:' then the file handle will refer to that file currently open in WinPTE. Write operations will modify text, read will read the current content, seek will change the location for the read/write current position.
-
if you happen to have a copy of ActiveState Perl Debugger for perl 5.1 then WinPTE integrates with the installed debugger allowing you to single step and examine variables for perl code that is being executed by WinPTE. Print debugging is the other option.
-
STDOUT and STDERR output goes to .stdout and .stderr files in WinPTE. These files are created automatically when output is generated.
Perl support functions are included in the installation directory in the perl subdirectory. Files PTE.pm and PTE.pl contain the perl PTE package and initialization files. This subdirectory also contains a PTE subdirectory with msdev.pm and commands.pm files. The former contains a perl script to sync a WinPTE active file to VC6 and the latter defines some perl subs.
Of particular interest is the eachline sub which takes a single argument and will execute the string or the code reference passed on every line of the current file's selection or if no selection is present in the current file then on every line of the file. The $_ variable refers to the contents of the current line during the execution. So the customary perl defaults for most functions and operators that use $_ will be operate on the line contents of the file.
Another is the run command. Executing 'perl run' from the WinPTE command line will execute the current file's content in perl.
The perl subdirectory also has a few perl source files that are used in WinPTE:
- todo.pl is used to parse the file or files and generate an HTML page for use as the ToDo pane contents.
- MSDevPrj.pl is used to parse a VC6 C/C++ project file and creates a project in the WinPTE project pane from it.
- dirPrj.pl is used to create a WinPTE project from a directory on disk.
- codesnippets.pl is a new addition and implements the code fragment template functionality (added after release 3.00.441).
Ask for help if you need it
This is a first run at the Perl integration documentation. If you have specific functionality in mind and need help in implementing it, just e-mail support and I will guide you through the process and explain whatever is not clear here. This documentation is a starting effort and will improve as I get a chance to complete missing parts.
Much more can be exposed to Perl than is currently the case. I stopped adding to it after discovering the memory leak and only add what is absolutely necessary to get something accomplished. However, that does not mean I won't add to it if you need to implement functionality currently cumbersome or impossible without adding exposing more of WinPTE to perl. So once again the lesson is: don't hesitate to ask.
File I/O functions for WinPTE files have extended seek parameters that allow to seek relative to the current cursor position in the file and to seek by lines instead of character offsets. There is also a mechanism for HTML dialogs to pass data back to perl script for two way communication between HTML script content and WinPTE perl. All this is left to be documented when I get a chance or when someone communicates a need, whichever comes first.
Tied Variables (PTE package)
To access add 'use PTE;' to the perl script.
Variable |
Type | R/W | Description |
|---|---|---|---|
| $Debug | int |
R/W |
Debug level. Perl scripts read this setting and in some cases generate verbose progress trace to STDOUT. |
| $DebugPerl | int |
R/W |
Perl Debug level, used to enable debugging of built-in WinPTE scripts (requires Active State perl debugger unfortunately it is no longer in distribution) |
| $clipType | int |
R |
Returns the WinPTE selection type of text currently on the clipboard. CHAR - 1, LINE - 2, BLOCK - 3 |
| $col | int |
R/W |
Current text cursor column position 1..4093. |
| $commandLine | string |
R/W |
Contents of the command line. |
| $commandMode | int |
R/W |
Get/Set current cursor command mode. |
| $cursorLine | string |
R/W |
Get/Set the text of the cursor line, if the cursor is in the command line then same as $commandLine if cursor is in the file then this is the same as $textLine |
| $cwd | string |
R/W |
WinPTE's current working directory . |
| $defaultTabSize | int |
R |
Default size of tab character expansion . |
| $fileEOL | string |
R/W |
Current file's EOL string used during file save. |
| $fileLines | int |
R |
Total number of lines in the current file. |
| $fileName | string |
R |
Full path of the current WinPTE file. |
| $files | hash ref |
R |
Tied hash of all files open in WinPTE keyed by file name. The value associated with the key is also a hash ref. name => 'file path', wrEOL => 'EOL', rdEOL => 'rdEOL', totalLines => totalLines in file. |
| $fileVars | hash ref |
R |
Hash used to allow scripts to store values associated with the current file. These are not persisted and are there to be used as a cache. For example the todo script caches the generated HTML for the file and will re-use instead of re-generating it if the file has not changed. |
| $iniFile | string |
R |
Full path of the WinPTE.xml file used to persist session state. |
| $isBlankLine | int |
R |
true if current text cursor line is blank. Ignores leading/traling blanks. This is $lineEnd==$lineStart |
| $keyNames | int |
R |
maximum currently user defined keys. |
| $lineEnd | int |
R |
end of line of the current textLine. |
| $lineStart | int |
R |
Position of the first non-blank character of the current textLine. |
| $markBottom | int |
R |
Line number of the bottom of the current selection or 0 if there is no selection. |
| $markFileName | string |
R |
Full path of the file name that is selected by the current selection |
| $markTop | int |
R |
Line number of the top of the current selection or 0 if there is no selection. |
| $markType | int |
R |
Type of current mark: CHAR - 1, LINE - 2, BLOCK - 3 |
| $ptePath | string |
R/W |
WinPTE's current search path. Note: in WinPTE the path is not a list of directories but a list of transformations that are applied to a file name in an attempt to find it. This allows trying to append default extensions, append sub-directories, etc. |
| $row | int |
R/W |
Line number of the current text cursor line. croaks if attempting to set <1 or >$fileLines. |
| $selectionType | int |
R |
Selection type. Usually the same as markType but if the current selection is "Persistent" then selectionType will return 0 while markType will return a non-zero type number. |
| $sourceNames | int |
R |
Maximum defined language templates. |
| $sourceVars | hash ref |
R |
Hash associated with the current file's language template. Use for cacheing values for the current session. Not persisted. |
| $textLine | string |
R/W |
text of the current text cursor line. |
| $typingMode | int |
R/W |
0 - Overtype, 1 - Insert, 2 - Flex Insert |
Constants (PTE package)
Variable |
Type | Description |
|---|---|---|
| $ANCHOR | ||
| $BEGIN_LINE | ||
| $BEGIN_MARK | ||
| $BLOCK | ||
| $BOTTOM | ||
| $CHAR | ||
| $END_LINE | ||
| $END_MARK | ||
| $FF_DIROK | ||
| $FF_DIRONLY | ||
| $FF_ONDISK | ||
| $FF_SUBDIRS | ||
| $FF_UNCOK | ||
| $FF_USEPATH | ||
| $FIRST_NONBLANK | ||
| $INDENT | ||
| $INSIDE_MARK | ||
| $LAST_NONBLANK | ||
| $LEFT_MARGIN | ||
| $LINE | ||
| $LINE_SEEK_CUR | ||
| $LINE_SEEK_CURSOR | ||
| $LINE_SEEK_END | ||
| $LINE_SEEK_SET | ||
| $MARK_CONFLICT | ||
| $RIGHT_MARGIN | ||
| $SEEK_CUR | ||
| $SEEK_CURSOR | ||
| $SEEK_END | ||
| $SEEK_SET | ||
| $TOP | ||
| $PT_NETWORK_PATH |
1 |
bit or value returned by PTE::pathType($) function if the argument appears to be a network path. |
| $PT_WILDCARDS | 2 |
bit or value returned by PTE::pathType($) function if the argument contains wildcard characters in the file name part. |
| $PT_NONEXISTENT_DRIVE | 4 |
bit or value returned by PTE::pathType($) function if the argument has a drive letter reference to a non-existent drive. |
Functions (PTE package)
To access add 'use PTE;' to the perl script. Most functions return 1 for success and 0 for failure. They also croak if a failure occurs in a void context. So if you don't want your script to abort just assign the return value to a variable or perferably check for failure in an if statement.
Function |
Returns |
Proto |
Description |
|---|---|---|---|
| &IsObjectRunning | int | $ |
String arument is a GUID of the com object to test to see if it is currently in the ROT (Running object table) used to see if VS6 is running for synchronization of WinPTE active file to VS6, but can be used for any com class. |
| &MainWindow | 1 | $ |
Manipulations of the main window. Optional argument values: 0 - send window to back 1 - to front 2 - minimize 3 - restore 4 - maximize 5 - on 2000 or higher, allow switching focus to another window. If not used then the new focus window will just flash its explorer button but won't come to the foreground. |
| &addProject | |||
| &findProject | |||
| &delProject | |||
| &setProject | |||
| &todoHtml | |||
| &todoShow | |||
| &todoIsVisible | |||
| &todoScrollTop | |||
| &todoUpdate | |||
| &todoRaise | |||
| &keyName | |||
| &keyTip | |||
| &startKeyTip | |||
| &nextKeyTip | |||
| &commentLead | |||
| &findFile | |||
| &fullPath | |||
| &generateName | |||
| &findFiles | |||
| &edittingFiles | |||
| &lastEditTime | |||
| &doesProfileExist | int |
$;$ |
returns 1 if the string argument refers to a data store node that exists, else 0 |
| &setProfile | $$;$ |
$$ version sets a node path given by first arg to string value of the second arg. $$$ version uses the first two arguments as paths (if second is a relative path it will be relative to the node given by first arg) to the value of the third argument. The only reason for the 3 argument function is for backward compatibility when this used to save values to the .INI file. Now you can just "nodepath1" . "/" . "nodepath2" to get the same effect. | |
| &getProfile | string | $;$ |
get string data stored in node given by arg 1. Arg 2 if provided and is a relative path will be relative to the node given by arg 1. If the node does not exist returns an empty string which could also be the value of that node use doesProfileExist to distinguish the two. |
| &isValidProfile | int |
$;$ |
tests the arguments to see if they generate a valid data store node path, can use them to pass to get/setProfile. The only node path that is not legal is one that contains two consecutive / path separators. If a node path ends on a / the / is ignored. |
| &deleteProfile | $;$ |
delete node given by arg 1. Arg 2 if provided and is a relative path will be relative to the node given by arg 1. | |
| &emptyProfile | $;$ |
set node value to null and delete all children of node given by arg 1. Arg 2 if provided and is a relative path will be relative to the node given by arg 1. | |
| &fileMode | |||
| &fileEOL | |||
| &isPTEKey | |||
| &isNormalKey | |||
| &fullKeyName | |||
| &alarm | |||
| &openUndo | int |
;$$ |
opens an undo transaction in the current scope. All file modifications (current file and all other files) will be grouped into a single undo/redo operation. Returns the frame ID that can be used to manually close or discard the undo transaction. Undo Transactions are automatically closed when the current scope is exited. If you don't wrap modifications made by your script into an undo transaction then each individual modification will be separately undoable. Which could be a benefit in some cases. In others it could be a disaster if the script does a 1000 mods with a single key click. You will be forced to undo changes by stuffing paper wads to keep the Ctrl+Z keys stuck in auto repeat to undo all of them separately. Second argument if INT then <=1 will take the cursor snapshot of the current file, if >1 will take the snapshot of all files. Normally the cursor snapshot is used to restore the cursor position for undo. The snapshot is taken when the file is modified. However, if your script moves the cursor before modifying the file the snapshot for the undo will be different than what it was before your script ran. Passing a parameter of >1 at the start of the script avoids this problem. If second argument is a string it is used as the caption for the undo operation. Will display in the toolbar undo button tooltip. If second argument is an int then the caption can be passed in the third argument |
| &execute | int |
$;$ |
Execute the first arg as a WinPTE command, optional second 0: don't store command for recall, <0 store only if it is not the same as the top of command stack, >0 always store command at top of stack. Returns true if command successfully executed else had errors. croaks if failure occurs in a void context. This command lets you execute any WinPTE command or macro function. So whatever is not exposed in perl can be accessed here. To execute WinPTE macro functions use "execute ..... " WinPTE command which compiles a temporary macro and executes it. |
| &clearCommand | |||
| &clearMacros | |||
| &clipCopy | |||
| &clipLine | |||
| &clipPaste | |||
| &closeUndo | int |
$ |
Closes the transaction ID given by the integer argument. Also closes any open nested transactions open after the transaction being closed. Returns 1 on success 0 if transaction was already closed. croaks in void context on failure. |
| &discardUndo | int |
$ |
Undoes changes done since the transaction ID given by the first argument was open and discards the information. No redo is generated for the discarded transactoin. Returns 1 on success 0 on falure. Croaks if failure occurs in a void context. |
| &unDo | int |
;$ |
Undo the last operation. Optional argument if true then undo only the current file's last operation otherwise all files that were modified in the last transaction on the undo stack will be undone. Fails if nothing to undo or file is read-only |
| &reDo | int |
;$ |
Redo what was last undone. Optional argument if true then redo only the current file's last undone operation otherwise all files that were undone in the last undo. |
| &canUndo | string |
;$ |
Return the caption for the next operation that will be undone with an undo. Optional arg if true then just the current file's undo op, otherwise all files. If the next undo does not have a caption then a string of " " is returned. An empty string means nothing can be undone. |
| &canRedo | string |
;$ |
Same as canUndo except applies to next operation that would be redone with a reDo |
| &insertLine | int |
... |
Insert a single line below the current cursor line (no argument version). If the first argument is numeric then it is interpreted as a bit mask of or'ed values: 1 - insert above current cursor position, else insert below. 2 - means cursor does not follow insertions and remains on the same line of text it was before anything was inserted. Otherwise cursor will be on the first line inserted if inserted above and last line inserted if inserting below. The rest of the arguments are strings and provide contents for the inserted lines. Any imbedded tabs will be left unexpanded and \n \r are also inserted. WinPTE only expands tabs and parses EOL on file open not during text operations (with some exceptions provided for convenience, but not in this function.) To expand tabs you can use my $t = ' ' x $PTE::defaultTabSize; $s =~ s/\t/$t/g; before passing a string for insertion to this function. |
| &deleteChar | |||
| &deleteLine | int |
;$ |
delete a single line (no arguments) or number of lines passd in the argument. Fails if file is read only or not enough lines left in the file to delete. |
| &unmark | |||
| &deleteMark | |||
| &deleteWord | |||
| &dialogCoord | |||
| &dialogPrepCoord | |||
| &dialogPrepSizing | |||
| &dialogShowParent | |||
| &dialogSizing | |||
| &showModal | |||
| &showModeless | |||
| &sourceName | string | $ |
returns the language template's caption that corresponds to the integer index passed as the first argument. 0 is always the default template. |
| &eraseLeft | Erase line contents from cursor to the begining of line. Erased characters are relplaced with spaces. | ||
| &eraseRight | Erase line contents from cursor to the end of line. Line is truncated at the cursor position. | ||
| &insertString | int |
$;$ |
Will insert the passed first argument string as if it was typed at the keyboard. This is slower than just modifying the current line's text but gives access to comment and margin reflowing, undo grouping of spaces, word characters and non-word characters and will pop-up the auto statement completion list if applicable. Optional second argument is an int with bit ored flags: 1 - allow auto reflowing. 2 - allow generation of the WinPTE 'key-release' which does language template specific post processing after every user typed insertable key. (VB/Lotus script do END key word completion and others) Much slower but fully simulates the user typed keys at the keyboard. |
| &joinLines | |||
| &splitLine | |||
| &backspace | |||
| &backspaceWord | |||
| &backtab | |||
| &backtabWord | |||
| &beginLine | |||
| &beginMark | |||
| &bottomOfFile | |||
| ¢erMark | |||
| ¢erRow | int | ;$ | scroll the display to center the current text line in the view. Optional argument is an int if < 100 then provides the position for the line 1 being top of screen 100 being bottom. If > 100 then provides the line count for the position offset by 100. 101 is top and screen size is bottom. If > screen size then the display will be scrolled to put the line at the bottom. |
| &down | |||
| &endLine | |||
| &endMark | |||
| &endWord | |||
| &firstNonBlank | |||
| &indent | |||
| &lastChange | int | Move cursor to the line last typed on, in the current file. | |
| &lastNonBlank | |||
| &left | |||
| &mousePointer | int | Move the cursor to the mouse pointer position. Only works when called while processing a mouse key operation. | |
| &nextBlankLine | |||
| &nextBookmark | |||
| &nextMacro | |||
| &nextNonBlankLine | |||
| &pageDown | |||
| &pageUp | |||
| &prevBlankLine | |||
| &prevBookmark | |||
| &prevMacro | |||
| &prevNonBlankLine | |||
| &right | |||
| &scrollDown | |||
| &scrollUp | |||
| &tab | |||
| &tabWord | |||
| &topOfFile | |||
| &up | |||
| &updateScreen | int | ;$ |
Update the WinPTE window. Normally WinPTE only updates the window when no macros or scripts are running. Use this function to update the screen while in a script. Optional argument >1 does a bit more updating like updating the state of the toolbar buttons. Not really need because this is done when the script stops running and the only time that the toolbar buttons can actually be pressed. |
| &inputDialog | string | $;$$ | First argument is either the data store archive XML string or a path to the data store node to use for configuring the input dialog. Second argument true (default value) if XML content in first variable. Third is debug setting, if true then the XML content of the node is dumped to .stdout |
| &toXml | string | $ |
converts characters in passed string to XML entity names. Used to build input dialog XML definitions. |
| &pathType | int |
$ |
returns 0 if the string parameter is not a legal file name, bit or of $PT_NETWORK_PATH,
$PT_WILDCARDS If the file path is not valid the return value is 0. |
| &generateGuid | string |
generates a GUID and returns it in the form: 0745936E-E1C8-4F41-9D13-3500CD63510D |