Click here for the perlwiz.biz documentation home page
|Contents||Prior Page||Next Page|
This section gives basic guidance as to how different aspects of PerlWiz function. It is the primary reference used for context-sensitive help within the PerlWiz application.
Alternatively, click on the Start menu at the bottom-left hand side of the Windows Desktop, followed by the Programs menu, followed by (typically) the PerlWiz programs folder, followed by the PerlWiz program icon.
Alternatively, if you chose to allow Perl programs to be associated with PerlWiz, you can double-click any single Perl program (ending with .pl, .cgi or .pm) from within Windows explorer to launch the default project, and add the selected program to the project. This effectively opens the program file using PerlWiz to enable you to view it, edit it, syntax check it, or execute it.
If you have any unsaved files, then you will be asked if you wish to save each of them. If you choose Cancel in response to any of these dialog boxes, then the program will not exit.
Note that if you are using the Default project, then any changes to the project will be automatically saved without any user intervention.
To add an existing file to the currently active PerlWiz project, you can use one of the following options:-
Select a single file using the standard open dialog box, and click on the Open button. Note that if a file ends with .pl, .cgi or .pm, it is assumed to be a Perl program and options relating to Perl programs become available to the file (e.g. execution, form parameters, syntax highlighting etc.), files ending with .htm or .html are assumed to be HTML documents, and files ending with .sql are assumed to be SQL scripts. These endings are used to syntax-highlight accordingly. Any other files are assumed to be text files, and are treated accordingly.
When a file is opened, a new tab appears in the work area to the right of any existing tabs, with the filename displayed. The full file path is displayed at the right of of the status bar. The file will also appear in the FTP page of the Project Organizer as unchecked and with the default path, and no access rights assigned. No form fields will be assigned to the file, and any environment variables are inherited from the project by default.
Note that if you try to open a filename that does not exist, you will be asked whether you wish to create a new file with this name - this is a good way of creating a file with a specific file-type rather than the default Perl type associated with temporary files. The file is not initially saved to disk, so if it is immediately closed (in case of error), it will never really be created.
To close a file (take it out of the project if it no longer needs to be part of the application), click on the File menu and select the Close option. Alternatively, you can hold down the Alt key and press X.
If you wish to close down several files at once, try using the project manager by pressing the F12 key. Ensure you have the General tab selected. Select all files that you wish to close (remember hold down Ctrl to select a number of individual files, or Shift to select a range of files) and then click on the Remove File button (or press Alt+R), or right-click over the selected file, and choose the Remove From Project option from the pop-up menu.
Note that if you close a temporary file, then it will be lost permanently. If you close a non-temporary file, then any settings associated with that file in the project will be lost - e.g. FTP settings, form field values etc. A dialog box will pop up to warn you of this when you try to close the file, at which time you have the option of cancel closing the file.
If you want to maintain the settings for another time, but do not wish the file to be included in the default project, then you could save the project under a different name to recall later. Click on the Locked as Default project option under the Project menu if the project items are greyed out. Then choose the Project | Save As... option to save the project under a different name to use later. If you wish to grey out the options again afterwards, then you will need to open the default project again (it marked as default under the Project | Recent menu) and then click on the Locked as Default project option again.
To create a new blank file, click on the File menu and select the New option or use the key combination Ctrl+N. You can also click on the button on the toolbar. The default file type to be created is Perl, but you can create a different type of temporary file (PHP, HTML, Text, SQL, or DOS Batch) by clicking on the downward arrow next to the button, and selecting the appropriate type of file from the drop-down list. Next time you create a new temporary file, it will automatically be of the same type that you just selected (until the program is closed down).
This will create a new blank tab at the right of any existing tabs with a name of <tempn> where n is a number from1 upwards for each new file that has been included in the project.
At this stage, the file has a temporary status. It will be kept with the project, but if it is closed, it will be lost permanently. You will need to save the program using File | Save As... or Ctrl+S to save the file as a permanent file with an existence separate (but still linked to) the project.
Temporary files can be useful, as they are stored both in a temporary storage area (which can get overwritten) and in the project file itself. This means that temporary files can be used for uses such as "to do" lists and scrap-pads for project notes, with the knowledge that the file will be copied with the project file should you wish to use it on another computer, or overwritten by another project. Note that it is also possible to include other files linked to the project in this way if required - see the section on transporting a project and its files later.
Temporary files are most often used to try out Perl or PHP programs, which may later be saved as permanent files if they prove to be useful. They are also ideal for learners of Perl or PHP that wish to try out aspects of the language without littering their hard disk with test programs.
When you have created your new file, a default piece of text will be placed in the project, which is taken from the code template with an alias of new.
If you do not wish to use this, simply delete the text. A quick way of doing this is to use the two key-combinations Ctrl+A and the Delete key.
You could tailor the contents of the code template used for each new file to some text that you would find useful to start each file of different types with - e.g. comment text (like the versn code template) or standard use clauses. You could also add code templates for different file types if you wish to include different types of files in your project for editing (perhaps .csv or .js files).
Note that if you selected the wrong file type, you can always change it to another temporary file type by selecting the File menu, the Change Temp File Type submenu, and the type of file you wish to convert the temporary file to. Any standard header will also be changed at the same time, even if you have started typing text after it.
To save changes to both the project and also all files linked to the project (permanent and temporary), simply click on the button. Alternatively, you can use the key combination of Ctrl+Alt+A or use on of the menu combinations File | Save All or Project | Save All. These all have the same function.
Note that when a file needs to be saved, a small asterisk (*) appears to the left of the filename name in editor's tab. Also, the current file that is selected will show with the word Modified in the status bar at the bottom of the screen in the second box along. If a change has been made to either the project or a file (i.e. something has changed that needs saving), then an asterisk (*) will appear to the left of the project name in the title bar of the PerlWiz window. Finally, the options for saving will be greyed out when there are no changes that need to be saved.
To save the currently selected file (if it is a permanent file), use the Ctrl+S key combination, or the File | Save menu option. This will save the file, and any modification indicators will be removed. If you try to save a temporary file, then as this unncessary, PerlWiz will assume that you are trying to save to a permanent file, and a dialog box will pop up.
To save the currently selected file to a different filename or different directory location (or both), click on the File menu and choose the Save As... option. A dialog box will pop up for you to select either a different name or location or both. Click on the Save button to continue the save. This will not remove the original file. However, the project will now be linked to the new file. If you changed the filename, and you wish to upload using this filename, you will also need to change the upload filename to match the new name.
Note that if you change the file type when you Save to a different file, then the default header for the old filetype will be swapped for the new file type.
Finally, if you have chosen to save the file contents with the project as well as on disk, so that files linked to the project can be transported (e.g. by emailing or by disk) to another computer in one compressed file, then make sure that you save the file to a location that is either in the same directory as the project file, or in a subdirectory. If you try to save anywhere else, then the project linking option will be disabled. This is a security measure to ensure that you cannot open a malicious project file that may try to save the file over important system files.
Both the File and Project menu have a recent files list (known in some applications as a Most Recently Used or MRU list). These are available under a submenu called Recent.
Every time you open or save a file, it is placed at the top of the list, and other files are shuffled down. Up to ten recent files can appear on the list. After this time, they are removed from the list as newer files are opened or saved.
Any files that have been removed will appear in grey rather than not being included at all, to highlight that they are files that have been recently used, but have been removed - this highlights any unexpected removals from the list. Greyed filenames can be removed from the list by selecting the Clear Deleted Files From List option.
If the list is becoming cluttered, you can clear it out by using the bottom-most option in the list: Clear Recent Files list.
Note that the MRU list is kept in the Windows Registry rather than with the project itself, and is therefore machine (and login) dependent.
A project is a way of grouping together a number of commonly related files, and storing information about these files, and also about the environment in which you wish to manipulate these files. It is typically used to group together files that are used in the development of a single project - e.g. a specific application, or perhaps a specific task within an application that is covered by a number of different source files (programs).
Many users - especially those who are learning a language - do not wish to be tied down by the complexities of using a new project for every new program that is written. This is a failing of many high-end IDEs.
For this reason, PerlWiz has the concept of a default project, which is used to hold all the details associated with a project, including remembering which files you had open the last time you were using PerlWiz. This is locked in place so that you cannot easily switch to another project by mistake, if you wish to stick to using one project most of the time. You can easily unlock the project again to open another project, or keep the project unlocked if you are switching projects regularly.
So if you wish to create new Perl, PHP, SQL or Batch programs, and try them out without wishing to worry about how to fine-tune things, or even where the files are being saved, then you can do this. This makes PerlWiz great for beginners and for trying things out, or for advanced commercial project-based work when you get to that stage of development.
It also means that by having a default project, then you have a standard set of options that you are working from every time you launch PerlWiz.
As well as having a number of settings about how the editor works, how colo(u)rs for different languages appear in the editor, file locations, FTP server details etc., a project also holds details about each file that is linked to the project - for example, whether it is to be uploaded to your FTP server, any form fields / environment variables you wish to simulate being entered and passed to the program, location of bookmarks within each editor window etc.
Changing the default project
The default project does not need to be the one supplied with your application. You can easily change it:-
Going back to the Default Project
If you have been using another project, and wish to go back to the default project quickly, then from the Project menu, select the Use PerlWiz Default Project option. This locks the default project in place too.
Resetting default project to "factory settings"
If you have changed your default project beyond recognition, and want to revert back to the original settings as supplied upon installation (i.e. "factory settings"), then ensure you are currently in the default project, and from the Project menu, choose the Reset to PerlWiz Defaults option.
This opens a project called default_original.pwp and saves it over the existing default.pwp file. If you have a project of this in the same directory as your project, then this will be utilised, otherwise the one from the default PerlWiz project directory will be utilised.
If this option appears to be greyed out, then check that the file exists in the directory - you may have inadvertently deleted it at some point.
To open a previously saved project:-
The project will not be treated as the default project (i.e. not automatically opened when you first start PerlWiz), unless you click on the Project | Locked as Default Project option or press Ctrl+D on the keyboard.
When you are using the default project, then details of the project are automatically saved at various times, including when you quit PerlWiz, automatically. If you are using (unlocked) non-default projects, then you will need to save any changes to a project.
You can do this by using the Project | Save menu option, or save the project along with any changes to files using the Project | Save All menu option (or the Ctrl+Alt+A keystroke, or by clicking the icon on the toolbar).
If you wish to save the project under a different name, or at a different location, then use the Project | Save As... menu option.
Note that any links to files are stored in the project as relative links, so it is important that if you wish to move the project file to a different location, but keep the linked files in the same place, you should use this option rather than moving the file using an external application such as Windows Explorer.
When you start using a number of files within your project for testing - not uncommon as a programming or web site project progresses - it becomes quite useful to be able to organize aspects of these files quickly and easily.
To aid with this process, PerlWiz has the Project Organizer which lists the files in the project, and shows many pertinent features of how these are linked to the project so that you can easily amend these values. You can even select multiple files and perform actions on several files at once.
To access the project organizer, do one of the following:-
Note that the project organizer works cooperatively with the editor screens. You can click back into the editor and continue working on your program whilst the project organizer is still on the screen.
Note that any changes you make in the project organizer are immediate - there's not a cancel button to roll back any accidental changes (except reloading the project).
To close (i.e. hide) the project organizer when you are clicked into it, either click on the close button (cross) at the top-right hand corner of the Project Organizer, or simply press the Esc key on the keyboard.
To select a file to use, click on a file in the left-hand portion of the screen. Notice that as soon as you do this, if the file is editable, the editor switches to that editor page.
You can select multiple files to change at once by clicking on the first file, holding down the Ctrl key and click on any number of other files in the list. Alternatively, you can click the first file, hold down the Shift key and click on the last file in order to select a range of files at once.
Note that many options are also available by right-clicking over the file list.
There are currently two tabs in the project organizer - General and FTP.
In the general section, the following options can be applied to the highlighted file(s):-
In the FTP section, the options relate to setting up the file to send to another server. Check out the FTP Upload section of this page for more information on the options available here.
Do a syntax check on the program currently being viewed by doing one of the following:-
This invokes the ActivePerl program in Syntax Check mode, which will look throughout the program and ensure it complies with the Perl language structure. If it does, then a message saying Syntax OK is displayed in the green messages box at the bottom of the screen.
Otherwise one (or several) error messages will show in this green box. If you wish to jump to the line on which the error occurs, simply double-click on the error message inside the green box.
If you wish to take a copy of one of the lines of error text in the green box, then just click on the line, and right-click over the line to copy it to the clipboard. This will be reflected in the status bar to show this has been achieved. You can then paste the error message into whichever application (e.g. an email / forum message in your browser) if you wish to get some advice from somebody etc.
A text box is displayed with a light-yellow background, which shows the output of the program. If your program is a CGI program (i.e. designed to output text to STDOUT formatted for a web browser to pass on to a browser), then the HTML tags will be highlighted using the colour scheme currently defined for HTML files.
So why are there two ways of outputting text? Generally, you would use the options, which lets you use debugging. If you want to avoid using debugging (e.g. you have a number of breakpoints, but do not wish to clear them all in order to avoid using them), or wish to see how the program would perform in a non-debugging environment, then you might want to use the option.
If you wish to see the program again, click on the Source tab to the left of the text output window.
If you wish to re-execute the program, then use one of the methods listed above, or you can right-click over the Text Output or Browser Output folder tabs.
Note that if you flip back-and-forth between the Source and Text Output tabs, the program will not be re-executed. This is useful when doing comparisons during debugging. Use any of the other methods described above to execute the program again.
PerlWiz interprets the console in order to simplify the largely text-based Perl environment.
If you wish to type text in at the screen and send this text input to a program, you will need to switch to the Text Output tab, possibly click into the window, and type out the text to be sent to the program. The text will appear as highlighted, and will only be sent to the program when you press the Enter key.
Alternatively, you can copy text from another source (e.g. from a text file or a spreadsheet containing test data) by right-clicking over the Text Output window, and selecting the "Paste as Keyboard Input" option.
Note that your program will not use this text until it specifically requests data from the standard input (STDIN) stream.
For example, in Perl, this might be:-
print "Enter text: "; $text=<STDIN>; chomp($text);
print "\nYou typed \"$text\"";
When the program gets to the <STDIN> instruction the computer will wait until you have input some text in the Text Output windows and pressed Enter before continuing. The new line is removed by the chomp command, and the text you typed is output inside a print statement.
You can also copy a selection of text appearing in the output window to the clipboard by highlighting a section of text in the output window, right-clicking in the window, and selecting the "Copy Selected Text" option.
Note that if you wish to input text into an array using multiple lines of input, the user will need to press Ctrl+Z on the keyboard (on an empty new line) to terminate input and send the data to the standard input - e.g. you could try this out using the program below:-
print "Enter lines of text: "; @lines=<STDIN>;
foreach $item (@lines)
print "\nYou typed \"$item\"";
Ctrl key combinations are passed to the console program "as is" - so they have immediate effect.
Please note that at the time of writing, this only works on builds for ActivePerl 5.6. Higher than this seem to handle Ctrl key input in a different way.
A browser instance is displayed showing the output of the program, resolving all HTML tags if applicable.
If you wish to see the program again, click on the Source tab to the left of the text output window.
This option does not interact with debugging tools - it will ignore any breakpoints. If you wish to type text in response to a request for STDIN input in the program, you will need to use Text window to provide the input.
If you flip-and-forth between the Source, Text Output and Browser Output tabs, the program will not be re-executed. This is useful when doing comparisons during debugging. Use any of the other methods described above to execute the program again.
Note that the browser window has several controls at the top in a toolbar to allow you to go back a page (e.g. after posting a form), forward a page, cancel loading the page, refresh the page, print the page, and see the page's URL.
You can also navigate to another page by either typing a new URL in this text box and pressing Enter or tabbing away, or by selecting one of the recently used pages in the drop-down listbox. These recently used pages are stored with the project so you can re-use commonly used web pages for each editor page in your project.
To launch the new browser window, click on the Do menu and select the Execute Locally in a browser window menu option. If this option appears greyed-out, you do not have the PerlWiz web server running. Enable the web server by clicking on the button in order to use this option.
Note that this facility does NOT pass any form fields or environment variables that you have defined for your program in the Params tab.
A breakpoint is a marker (or flag) to show a line at which you would like the program to pause execution. You would typically want to do this if you suspect a part of your program is not functioning correctly, and wish to check to see what is happening in the program on a line-by-line basis by executing the lines from the breakpoint onwards one at a time, and examining the variables to see how they are changing, as well as checking that execution is following the path you would expect given this information.
To set a breakpoint, click in the gutter margin (on the little raised dot) to the left of the line where you would like execution to pause. This places a small red-background check in the margin, and a light red highlighter on the line to make it easy to spot. You can place several breakpoints in your program if you have a number of areas you would like to examine - e.g.
If you click on the check again, the breakpoint will be removed, and the program will not stop at this point.
Note that not all lines can have a breakpoint set against them. Obvious ones such as comment lines and blank lines do not have dots in the margin, so cannot have a breakpoint set against them. However, some lines such as use lines that do not call a specific library function will ignore a breakpoint set against them.
To start the program, you will need to execute the program in debug mode, which can be accessed through one of the following methods:-
Note, if you wish to break at the very first executable line in your program, you can click on the Step button - - this saves you having to set a breakpoint on the line.
Also note that it is important not to change your program whilst debugging, as it will no longer reflect the program being debugged - especially, do not add or delete lines, otherwise the wrong line will be highlighted, making the debugging rather confusing to follow! Any breakpoints you set / clear whilst you are in the process of debugging will be ignored until the debugging session has finished.
The program will execute until the first line with a breakpoint marker is encountered, at which point execution pauses, and a bright red highlighter shows over the breakpoint line, which looks like this:-
This means that the program has stopped running just before this line is to be executed, so the variable has not yet been changed. If you wanted to execute the line and then stop, you would need to set the breakpoint on the next program line down.
To execute the above line, but only the one line, you can use the Step option, which you can do in one of three ways:-
After a short pause, the next line in your program will be highlighted in red, showing the next line to be executed.
If you now place your mouse cursor over the variable name (in the above example $abc) anywhere in your program listing, a yellow tooltip will display showing the current contents of that variable. You can hover your cursor over any variable in the program to see the contents of any variables that have been created. If no tooltip appears, this will probably mean that the variable has not yet been created in the program. In the example above, the tooltip would look like this:-
You can step through your program line by line by using the Step option and follow how the variables change. This is really a trace tool rather than a step tool, as it will also follow the lines of code inside any subroutines you have created inside the program.
Note that you can see a full list of variables in a dialog box by clicking on the Debug menu and choosing the Show Variable List Window menu option. This will list the variables in the order they appear in memory, and also the debugger output that identifies these variable. Future versions will extend this functionality to allow for variables to be altered in situ:-
If you wish to continue executing your program as normal (until the end, or until another breakpoint is reached), simply click on the button again or press the F9 key - this option acts as a Continue function during debugging.
Note that you can follow how output from the execution is progressing by clicking on the Text Output window. If execution has reached a <STDIN> or <> Perl file function, you can go to this window, type in some text, and press Enter to feed keyboard input into your program. You may need to click into the window first on some occasions.
Advanced Perl Users: If your program is paused, you can type Perl debugger commands directly into the text output window to perform some bespoke debugging. For example, you could type exit and press Enter to quit debugging immediately (a potentially cleaner exit then terminating the process using the button).
From the above dialog box, the light-red area shows Perl debugger output since the last debugger command execution. To show the full history of output since initial program execution, double-click anywhere in the light red area. This should only be done when the program is paused, or the program has terminated, as it will be overwritten at the next command execution. Right-clicking in this box will cause the full text of the box to be copied to the clipboard.
If you suspect your program has gone into an infinite loop, or is just taking too long to complete, you can stop and finish the program immediately at any point by one of the following methods:-
This works with any of the options that execute to the local environment - e.g. execute to text, browser, and whilst debugging.
A bookmark is a marker that remembers a specific location (i.e. row and column) in your source code, so you can hop back and forth between different parts of your program easily.
Bookmarks are stored with the project file, and are individual for each source file in the project, so once you have set them, you can forget about them until you need them.
You can have up to ten bookmarks (labelled from 0 to 9) for each source file.
Boomarks are easy to set too. Locate the cursor at the place in your program that you wish to bookmark, and do one of the following:-
To go to a bookmark that has previously been set, do one of the following:-
To go to a specific line number, use on of the following methods:-
Once you have done this, a dialog box appears showing the current row number where the cursor is sitting. Overtype this with the new line number to jump to another row number.
Note that you can also jump to a number indicated by an error message by double-clicking on that error message line.
You can also see what the line numbers are for each line by changing the project option found by clicking on the button on the toolbar, clicking on the Editor heading (if necessary), selecting the Visibility Options sub-heading, and clicking on the Show Line Numbers option. Click on the OK button to accept setting changes and close the Project Properties dialog box.
If you wish to search for specific text within the selected file, you can do so by doing the following:-
Click on the OK button when you are happy that you have the settings you require. The computer will beep if no items have been found matching your criteria, otherwise the first found occurrence will be highlighted.
To find the next occurrence after this one, select the Search | Find Next menu option, or press the F4 key.
To find the prior occurrence before this one, select the Search | Find Previous menu option, or press the Shift+F4 keys together.
If you wish to search for occurrences of text within a file, and replace some or all of those occurrences with alternative text, then use the Replace option as follows:-
Click on the OK button when you are happy that you have the settings you require. The computer will beep if no items have been found matching your criteria, otherwise the replace operation will take place according to the options you selected in the dialog box.
To find/replace the next occurrence after this one, select the Search | Replace Next menu option, or press the F6 key.
To find/replace the prior occurrence before this one, select the Search | Replace Previous menu option, or press the Shift+F6 keys together.
To find/replace all occurrences, select the Search | Replace All menu option, or press the Shift+Ctrl+F6 key combination.
Replacing text is often useful in applications where you named a variable, and wish to rename it to something else when you realize its meaning isn't as clear as you intended.
The following is a list of keystrokes that are commonly helpful when editing text using the text editor:-
|Up Arrow||Move cursor up a row||Shift + End||Select to the end of the row|
|Shift + Up Arrow||Select to a row above||Ctrl + End||Go to end of document|
|Ctrl + Up Arrow||Scroll up a row||Shift + Ctrl + End||Select to end of document|
|Down Arrow||Move cursor down a row||Insert||Toggle Insert/Overstrike modes|
|Shift + Down Arrow||Select to a row down||Ctrl+Ins or Ctrl+C||Copy selected text to clipboard|
|Ctrl + Down Arrow||Scroll down a row||Shift + Delete or Ctrl+X||Cut selected text to clipboard|
|Left Arrow||Move cursor left one column||Shift + Insert or Ctrl+V||Paste text from clipboard|
|Shift + Left Arrow||Select to prior column||Delete||Delete character to right of or under cursor|
|Ctrl + Left Arrow||Move cursor to prior word||Backspace||Delete character to left of cursor|
|Shift + Ctrl + Left Arrow||Select to prior word||Ctrl + Backspace||Delete previous word|
|Right Arrow||Move cursor right one column||Alt + Backspace or Ctrl+Z||Undo|
|Shift + Right Arrow||Select to next column||Shift + Alt + Backspace or Shift+Ctrl+Z||Redo|
|Ctrl + Right Arrow||Move cursor to next word||Enter / Ctrl + M||Break line at cursor position|
|Shift + Ctrl + Right Arrow||Select to next word||Tab||Tab to next tabstop|
|PgDn||Move cursor one page down||Shift+Tab||Tab to prior tabstop|
|Shift + PgDn||Select to one page down||Ctrl + A||Select All|
|Ctrl + PgDn||Move cursor to last line on screen||Shift + Ctrl + I||Block Indent|
|Shift + Ctrl + PgDn||Select to last line on screen||Shift +Ctrl + U||Block Unindent|
|PgUp||Move cursor one page upwards||Ctrl + T||Delete word|
|Shift + PgUp||Select to one page upwards||Ctrl + Y||Delete line|
|Ctrl + PgUp||Move cursor to first line on screen||Shift + Ctrl + Y||Delete to end of row|
|Shift + Ctrl + PgUp||Select to first line on screen||Ctrl+0 .. Ctrl+9||Go to bookmark 0 .. 9|
|Home||Move cursor to left of row||Shift+Ctrl+0 .. Shift+Ctrl+9||Set / Reset bookmark 0..9|
|Shift + Home||Select to start of row||Shift+Ctrl+N||Normal selection mode|
|Ctrl + Home||Go to start of document||Shift+Ctrl+C||Toggle Column selection mode|
|Shift + Ctrl + Home||Select to start of document||Shift+Ctrl+L||Select this row (line)|
|End||Move cursor to end of row||Shift + Ctrl + B||Match bracket|
There are a number of special functions that the editor can perform to help your programming. These are detailed below:-
You can also copy the filename that shows in the status bar to the clipboard by double-clicking on the filename. This will show that it has been copied to the clipboard, which you can then within your program / documents.
When you move to a file for editing, either by switching tabs, or when you switch back to using PerlWiz after using another application, PerlWiz will perform a check to see whether your file has changed since you last saved it.
This is in case another process or person has changed your file before you have had a chance to save it, in which case your version may be overwriting important changes that someone else has made.
You will be warned with a dialog box that the file you are working on has been changed by another program, and PerlWiz checks to see whether you wish to open the amended file and lose any changes you have made. Note that if you chose No and save your program, and have backups enabled, then the updated version will be backed-up first anyway, so you can look at the backup file to see what's changed without losing any information from either your version or the other updated version.
This is also a useful way of detecting changes in log files that may be updated constantly by a process. Just flick back into PerlWiz at regular intervals, and you will be warned if any changes have been made to the log file, in which case you can load the latest version into the editor for viewing.
The program will also detect when an external program has removed the file you are editing from the disk. You will be given the option to wipe out the text in the text editor for the file you are editing. Click on NO if you want to keep the contents of the editor. You are advise to save your file at this point too!
PerlWiz keeps a history of changes that you have made in its undo buffer for each file that you are editing. This is of limited size, and only lasts for the life of the instance of PerlWiz that you are using.
Often, you may want to refer back to a copy of a program that you saved previously. Perhaps you decided to program something a different way, and now wish to retrieve that method having changed you mind back to your original method.
Or worse, perhaps you deleted over a part of your program and saved it to disk, thus committing it. Argh!
The way around these situations is to keep backups. The bulk method is to save copies of your work periodically - e.g. copy your whole project directories to CD or Backup Tape. This only captures changes at the point where you take the backup - which may means that you have saved the required file several times in the intervening time between bulk backups.
A better way that PerlWiz adopts is to give you the option to save a copy of a file when you save it. You can save a history of your file at points where it is saved - up to ten per file. For example, let's say we have a file called myprog.cgi
The first time we save a change, the old version gets moved to myprog.cgi.bak and the new version gets saved to myprog.cgi.
The next time we save a change, the version in myprog.cgi.bak gets moved to myprog.cgi.bak.1 and the version inf myprog.cgi gets moved to myprog.bak and the new version gets saved to myrpog.cgi etc. etc. Backups can go all the way up to myprog.cgi.bak.9 if we wish to to keep that many backups. This means that the most recent backup is always myprog.bak, the second most recent myprog.bak.1 etc.
To recall a backup, use the Restore menu option under the File menu. The backups are then listed in reverse chronological order with their file dates to help identify the file you require. Just click on the appropriate file to recall it into the editor.
Note, that bulk backups are still a good idea, as they mean you can keep your data off-site in case of any disaster - e.g. computer blows-up, comet hits, fire etc.
Backups are generally kept in the same directory as the original source file. If you choose to use version control, you can control where backups are kept. So what is version control?
Once you have started to produce more complex web applications that are changing continually, you may wish to keep a history of the changes that you have made.
You could employ the use of a "check-in / check-out" style version-control system - there are plenty on the market, many of them freely available. These are ideal where teams of people are sharing the same code, and you do not wish anyone else to change a program whilst you are working on it.
However, if you only wish to maintain a history so that you can identify what changes were made, when they were made, and how the program has changed between different version or 'releases', then the version control available within PerlWiz will probably be fine.
Each project (including the default project) can have a version control root directory associated to it. This means that any files saved using the project will be stored under a version-specific subdirectory under the version control root directory. Furthermore, any backups will be stored under this subdirectory.
For example, view the project properties tab (click on the button on the toolbar), click on the Files heading, and select the Backups & Versions sub-heading. You can select the number of backups to keep of any file using these options. For example if this was set to 3, then myprog.pl would be moved to myprog.pl.bak when it is changed and saved, and then shuffled into myprog.pl.bak.1 when it is saved again, and then moved to myprog.pl.bak.2 when saved again, and then deleted the next time it is saved, so that myprog.pl.bak always contains the most recent backup. You can restore from these backup using the File | Restore option, which shows the original creation date of each backup file. Note that backups are not stored with a project if you choose to store files inside a project for transporting.
Next, choose a versions path to be the root path - e.g. projects/backups
If you are making relatively minor changes and saving them (e.g. to test them) regularly, you may not wish a backup to be made with every change, as you would quickly lose your more significant changes. You can set a time to wait before backing up the file again (i.e. after the date / time of the last backup). To use this, set the value in the No backups within ... seconds of last saved backup text box to the number of seconds between backups - e.g. 60 seconds for a minute, or at the extreme, 86400 for a full day between performing a backup!
Next, click on the Identifications heading in the project properties dialog, and select the About sub-heading. This shows the current version number. This is used to create the subdirectory under which all files will be kept.
The directory under which a second copy of the latest source file, plus any backups, is kept is made up of the versions path and the version number, where each dot is converted to a subdirectory, so if the version path is c:\temp\backups and the version number is 1.3, then backups / source copy are kept under c:\temp\backups\1\3. Then, if the version number is changed at any time, when you start working on the next version of the application, all you have to do is change the version number of the project, and any changes are then saved to another directory. Any directories that need to be created are created automatically by PerlWiz. Note that if you wish to restore from a previous version, you will need to change the version number to the old version first, and then restore the file from the File | Restore menu afterwards, and then change the version number back to the current version number if necessary.
Note that to turn off backups to the versions path, just delete the versions path from the Files >> Backups & Versions heading. Any backups will then be stored in the same directory as the source file. If you do not want to keep any backups, then simply set the Backups / File option to 0 (zero).
Normally, when you open files into a project, the files are simply linked to the project so that the project can gain easy access to the file and store information relating to the file. The file itself is a separate entity. Were you to copy the file and put it onto another computer, then the files would be left on the original computer.
PerlWiz has an option which enables you to store any files linked to the project inside the project file itself. These are compressed so that they take up less space than the individual files would in their own right.
You are then free to transport that file (e.g. via an email attachment, or via floppy disk) to another computer that has the PerlWiz IDE installed.
When you open the project on the destination computer, the files will extracted from the project and stored on the destination computer automatically, as if they were always on the computer! If the files were stored in subdirectories from the project directory, they will be extracted into the correct location. File dates and times will also be maintained from the original files.
Sounds great? It can save a lot of time archiving / unarchiving project files when moving from location to location.
So what are the drawbacks? Well, you need to make sure you save your project files in the right place on the destination computer. It doesn't have to match the location of the source computer, but the files will be recreated relative to the project file in the same way. As a security precaution, you can only transport files that are either in the same directory as the project file, or in a subdirectory. Files held on a different drive, in an absolute location, or in a parent directory to the project cannot be included. This to ensure that you don't inadvertently open a file created by someone else that wipes over important system files, or worse, replace them with Trojans. Finally, the files are extracted unconditional to what is already on the disk - note that with more recent versions of PerlWiz, any existing file will be backed up first (if the file date is within the backup timeout period). Also, backup files are not taken with the archive - only the originals.
So how do we switch on this feature? Click on the button to view Project Properties dialog box and click on the Files heading, and the Portability sub-heading. There is a checkbox labelled Save Editor Files with Project... - check this to enable this feature. Click on the OK button to confirm the changes and close the Project Properties dialog box. If any of the files in the project are not in the same or a child directory to the project, then this option will automatically be switched off again before saving the project.
You can be selective about which files you wish to include in the project. For example, if you are including a file (e.g. a settings file) which needs to be different on each computer you use the project from, but still be able to edit it from the project, then you may wish to keep it linked into the project, but not save it with the project. Similarly, for large files you may not wish to save them with the project if the file will be the same on each computer the project is to be used from.
To do this, launch the Project Organizer whilst in the editor screen. You can do this by clicking on the button on the toolbar or pressing the F12 key.
Ensure that you are looking at the General tab. Click on it if you are not.
Now click on each file that you do not wish to save to the project. You can click on several at the same time by clicking on the first, holding down the Ctrl key and clicking on the others.
Now, click on the Save File With Project checkbox to remove the check from the box. The file will now only be linked to the project, and will not be saved with the project. Project-related file settings will still be saved with the project though.
Note that temporary files are ALWAYS saved with the project as they are transient, and could be overwritten by other projects, so you cannot change them to be linked only.
If you are wishing to use your Perl scripts from a server - typically a remote (i.e. on another computer) web server - then you will want to copy your programs to the server to allow people to execute your scripts.
To do this, you would typically transfer your programs using something called the File Transfer Protocol or FTP. An FTP server on your remote web server will listen out for requests by any FTP clients to transfer files to or from the server.
The PerlWiz program can acts as an FTP client, and can connect to your server using FTP to transfer files that you have changed. You can set PerlWiz up so that performing this action takes only a single button-click. You can even test your script and see the results from your web server in one step!
First, you need some basic information about your remote web server, which you should be able to get from your service provider:-
To specify these to the PerlWiz program so that you can start uploading files to the server, click on the Properties button () on the toolbar, and click on the FTP / Upload heading, and the Server / Login sub-heading.
Type the details detailed above into the appropriate boxes, and (from the Miscellaneous sub-heading) typically also the Upload only files that have changed since the last transfer option too so that only files that have changed will be uploaded each time the upload button is pushed.
You can also check the Keep connection open between transfers option if you are uploading very regularly (e.g. effectively testing on the server itself) and do not wish to wait for the server to connect every time an upload takes place. If the connection is dropped in between uploads, it will be automatically re-established the next time the upload takes place.
To test that the connection works OK, click on the Test Connection button. Make sure you are connected to the Internet before you click on the button.
Results of the test, which consists of logging onto the server, and changing to the start directory, are displayed in the status bar a the bottom of the dialog box. If there were any problems, then the status bar changes to a light-red colour.
Note that these details are stored with the Project. As we are using the default project at the moment, they will be stored automatically - you do not need to type them again once they are set up.
Also note that if you do not wish to save the password of your server for security reasons, you can leave this box blank. You will be prompted for the password each time you need to log onto the FTP server.
Once you are satisfied that the details are correct, click on either the OK button if it is highlighted, or otherwise the Cancel button to exit the dialog box.
Click on the button on the toolbar to try to upload any files that have changed to the web server. As we have not uploaded anything before, the FTP page of the Project Organizer will pop up so that we can select which files we wish to upload.
Click on the name of the file to be uploaded in the list box at the left of the organizer. To specify that the files is to be uploaded to the FTP server, click on the Use this file for uploading to Server checkbox to put a check in it. Notice that the grey arrow next to the name in the list box turns red to show that this is a file that needs uploading. When the file has been uploaded, the arrow turns to green and won't be uploaded again until the file has changed.
We can choose an offset directory if the file is to appear anywhere but the root web server directory (specified previously). E.g. if we had selected /public_html as our root directory for all FTP files, and CGI scripts are kept in /public_html/cgi-bin, then we would select this as cgi-bin
We could change the filename to be stored on the web server here if we wish, but this would be unusual (unless you are uploading a temporary file).
Note that if you hover the cursor over the File Name text box, you will see the full path where the file will be stored on the web server given the current settings. Hovering the cursor over the Offset Destination Directory text box will show the full directory path into which the file will be placed.
We can store a file as ASCII (typical for text, Perl source and HTML files) or Binary (typical for pictures / images), or leave this up to PerlWiz by choosing Auto.
The Change File Permissions option sets the file permissions for the file to be uploaded. This is not available on all web servers, but most Unix servers allow for this. Click on the checkbox, and choose a file permission (typically 755 for Perl scripts). Click on the ellipses (...) button to select the options in more detail using checkboxes for public, group and local permissions. Note that not all servers accept permission changes in this way.
The Project Organizer FTP page should now look something like this:-
Click on the cross to close the window (or press the Esc key on the keyboard). Note that all changes to settings in the Project Organizer update the project immediately. You may wish to save the project at this point using Ctrl+Alt+A.
The file is now set up for uploading. Any changes you make will be detected, and whenever you click on the button in the future, they will uploaded automatically without any further setting up or intervention. This button now acts as a 'Save All' button to your web server for all changed files.
When PerlWiz opens a file, it checks the letters after the period (.) in the file name. It uses this to determine the type of file that is being opened. For example, a filename ending with .pl would indicate that the file is a Perl file, and a filename ending with .htm or .html would indicate that the file is a HTML or web document.
This ending is used for a number of purposes in PerlWiz:-
You can view a list of file types available in PerlWiz, which you can add to or amend as you wish (although the main essential default file types will be left available even if you try to remove them).
To access this list, view the project properties dialog by doing one of the following actions:-
Then click on the Files >> File Types heading to see the screen below:-
This shows a list of the different file types down the left hand side. Click on any of these to highlight the row, and place the values displayed in the columns into the editable area at the right.
You can sort this list by any of the columns by clicking on the appropriate column heading.
For each file type definition, there are four elements:-
If you open a file in PerlWiz that is not on the list of file types that are editable (or is checked as ineditable on the list), then it will not be shown as a page in the editor. However, it is shown in the Project Browser, so can be FTPed (copied) to your web site, and linked / included in your project.
You can add a new file type to the list by clicking on the button, and remove the currently selected file type by clicking on the button.
Click on the Clear button to clear the entire list and leave a single entry to add details into. Note that when the project is updated any default file-types will be added in again as necessary.
Click on the Reset to Defaults button to replace the displayed list with the list of PerlWiz default file types.
When debugging a program, it is often useful to capture the input, output, and error information from your program (and possibly from PerlWiz too), and examine the sequence of events to attempt to determine the root of the problem.
PerlWiz has a facility to help you do this, by capturing specified types of information into a file of your choice. The is also useful for reporting problems to PerlWiz support to show the status of the system, and the sequence of events when you encountered a specified problem.
Each line on the log shows a date and time when the event took place.
To set up how to capture this information, click on the button or select the Project | Properties menu. Now select the heading labelled Logging.
You can change the log file location by clicking on the ... button next to the Log File Location text box to select a new file, or just type the new filename into the text box. The default filename is perlwiz.log and can be found in the default projects directory.
A list of logging options is given which you can select from to decide what to include in the log. These can be found in the sub-headings below the Logging heading.
Note that console logging takes place for any application executed - Perl, MySQL, or Dos Batch.
The options are as follows:-
To select every option, click on the Select All button. You can then uncheck anything you don't want to log.
To uncheck every option, click on the Clear All button. You can then check anything you want to specifically log.
It is advisable to click on the Apply button before turning logging on if making changes to the logging options. None of the changes to logging will take affect until either the Apply or Ok button is pressed.
To switch logging on, click on the Logging is Off button and the button stays depressed, and changes to Logging is On. To switch logging off again, click on the Logging is On button.
To clear the contents of the log (i.e. remove the log file and start logging again), click on the Clear Log button. Note that anything check under the Information section will be placed in the log immediately after selecting this option. Useful for getting a general overview of the state of the system / project.
Click on the Log to Clipboard option to take a copy of the log and place it as text onto the clipboard - useful for pasting to another document, or into an email for support purposes.
Click on the View Log button to view log the log in a notepad session.
If you see a serious error in PerlWiz and wish to report it, it would be helpful if you could provide a logging of what is happening inside PerlWiz at the time the error takes place.
To do this, select the Project Properties dialog box (press the F11 key from the editor), and select the Logging heading and then the PerlWiz Internals sub-heading.
Now click on the Start Logging PerlWiz Internals after specified interval option, and set the time to start logging (the default is set for 10 seconds from when the dialog box was opened), and the likely amount of duration of the operation before the error takes place (typically no longer than 5 seconds, so the default should be fine).
Click on the OK button and you will be taken back to the editor screen. Go to the point just before the error takes place, and wait for the main editor screen to start showing a digital countdown timer as follows
Start the operation that causes the error message and when the error message shows, leave it at this point, until the countdown timer disappears again (i.e. gets to 0).
Then copy the log file as an emailed attachment to support staff. To get the log file name, look in Project Properties (F11 key) under the Logging heading, and copy the text from the Log File Location edit box. You can then create an email attachment, and when you open the file, paste this filename in the file name dialog box.
This will give detailed information about what was happening before the problem took place, and where in the PerlWiz program the error occurred, thus enabling the solution to your problem to be resolved much more quickly than guessing where the problem may have occurred.
When you use syntax checking or execute a Perl program, the program is being compiled into a form that is more easily readable to the machine on which Perl is hosted first.
You can change the way that Perl interprets the instructions that you give, and the corresponding warnings and error messages that it gives in return, by changing a few Compiler Options.
To access these options globally throughout your project, click on the button access the Project Properties dialog box and click on the Language >> Perl >> Compiler / Tools heading.
On this page, there is a Perl Warnings box with three radio button options - None, Selective and All. By default, this is set to Selective so that you can see normal compiler warnings. If you select None then compiler warnings are turned off, even if they are explicitly turned on inside a program (or any of the programs in the use list of the program). Similarly, if you select All, then compiler warnings are turned on, even if they are turned off inside a program (or any of the programs in the use list of the program).
Taint mode checking can also be checked here for security reasons. This picks up any possible security loopholes that your program may have that could allow hackers into your program and cause your program to execute undesirably, or even gain access to part of the system / delete files / execute programs etc. that they shouldn't. It's a good idea to turn this on if you plan to use your program for web applications.
Notice that on this page, there is also the option to specify where the version of ActivePerl that you wish to use is located on your system. This is normally picked up automatically by PerlWiz, but if you wish to test your programs on different installed versions, you could do this by having multiple installs, and changing the location of the compiler here.
You can see details of the installed version of Perl by clicking on the Version Details button. If you click it a second time, you will see extended version information.
If you are using PerlWiz to create a web form-based application, you may wish to test a program several times without having to continually re-type form field details. Alternatively, you may not have a web server installed on your computer (or prefer not to use the inbuilt PerlWiz Web Server if you do not have a firewall installed), so manually testing a form may not work properly, as there will be nowhere locally to submit the data to.
In both of these scenarios, it would be useful to be able to list the form fields to be submitted to a form and their accompanying test values, and see the results.
You can do this quite easily by clicking on the Params tab at the left of the editor window.
We use the details in this tab to list the parameters that are to be passed into the Perl program as if form fields had been filled in (either from the same Perl program, or from any other source).
There are two send types we can use to pass data in - Get and Post. Get passes data using data tagged onto the end of the URL as & separated name/value pairs. Post passes data in the body of the request in a similar format, but does not show in a browser's address bar, and is not typically restricted in size as much as a Get request.
We select which method we wish to use using the Form Send Type radio box. Note that the Get + Post option send data in both ways simultaneously (this would not happen normally) in case you wish to test that both ways work OK. The post method would be picked up by the CGI library in this case. If we do not want to send any data, we can disable this by choosing the None option here.
It may be that you wish to test a command-line driver Perl script for use on your server, that has nothing whatsoever to do with CGI processing.
It would be useful to be able to pass a list of parameters to the perl program via the command line, simulating someone typing in a list of options.
To do this, click the Data only for params option in the Form Send Type radio box. The data part of any checked option listed will be sent to the Perl program as a command line option upon execution of the program. The name part is not sent to the program, and is used for identification purpose only.
To simulate entry of the text Simon Huggins into the text field that we called name, we would add a new form field by clicking on the button. Under Form Field Name, enter the name name and then press the Tab key to move to the Form Field Data, and enter the value for the field, Simon Huggins in this case. Notice this appears in the listbox with a tick next to it. The tick means the field will be sent to the program when it is executed (so long as Form Send Type is not None). Click on the tick to ensure the field data will not be sent. This allows you to add several different versions of the same field, and tick the version that you want according to what you are trying to test.
The example given here shows two more form fields, one called pay_method with a value of Visa and another called offers with a value of yes.
If you wish to delete any of the fields at any time, just click on the field in the list box, and click on the button.
Note that this data is saved with the project. Thus, if you close the file, it will be disconnected from the project, and consequently, this information would be lost.
It is also possible to enter environment variables if you wish to simulate passing in values according to the environment of the computer on which you will be executing the program. These are entered in a similar way in the Environment Variables section. By default, environment variables are loaded from the project defaults, but can be overridden by taking the check out of the box labelled Use Standard Project Environment Variables.
The standard project environment variable, shared by all files unless overridden in individual files, can be amended by clicking on the button, selecting the Environment heading and Variables sub-heading, and adding to / removing / editing the environment variables from this location.
You can also use default environment variables, in case you do not define them yourself inside the project or for a specific file in the project - these can be found under the Options heading page.
You can choose to use the environment variables defined for your computer as default (anything that you define inside your project will override these defaults).
To do this, put a check in the Use existing environment as a default checkbox. Two extra options are then available to you:-
Finally, you can choose to use the project's TEMP directory as the environment's TEMP directory by checking the Set TEMP and TMP to be project's temporary directory option.
Typically, to be on the safe side, you would select the following three options in a project:-
The key environment variables brought through by the Only include key environment variables option are as follows:-
CommonProgramFiles, COMSPEC, OS, PATH, ProgramFiles, PROMPT, SYSTEMROOT, TEMP, TMP, and WINDIR.
Any environment variables in this list not found on the computer will be ignored, and the case of original keys will be preserved (although matching is case-insensitive).
When you have been using PerlWiz for a while, you may wish to change the appearance of how text is coloured / looks, or any number of ways that the editor functions. You can do this by clicking on the button to look at the Project Properties dialog box, and click on the Editor heading.
These are split into several sub-categories as follows, with each page holding a number of options that you can use to customize how the editor operates. Here's a summary:-
Tabs & Indentation
If you wish to change the colours that the editor uses to display and print text, select the Project Properties dialog box by clicking on the button, and click on the Language heading, followed by the language type you wish to change the colour for (e.g. Perl) and Font + Colors heading.
You can also utilise a number of standard colour schemes by choosing one of the drop-down schemes in the Scheme drop-down edit box. Try different schemes to suit your taste.
Note that as soon as you start changing the colours etc. for a file type attached to a specific scheme, then this becomes a custom scheme, and the Scheme drop-down edit box will be blanked.
If you set your colours for a file type, and wish to save them for use by any other file types (or if you wish to switch between different schemes for the same file type), then you can add a new scheme by simply typing in a new name into the Scheme edit box, and tabbing / clicking away from the edit box. A prompt will check that you wish to create a new scheme.
If you wish to delete a scheme, then choose a file type that uses the scheme, and delete the text from the edit box, and tab / click away from the edit box. A prompt will check that you wish to delete the scheme. If you do not, then this will become a custom scheme with no name.
If you wish to change a scheme, ensure the scheme is selected in the edit box, make the changes you require to the scheme, and then click on another tab to move away from the colour details of the file type. A prompt will check that you wish to change the scheme. If you do not, then this will become a custom scheme with no name.
Background color and Editor Font
The Editor Background option is particularly useful as a means by which to identify specific file types at-a-glance. Note that when you change the editor background colour, any elements that share this background colour will also be changed at the same time. This saves you time when you are trying out different background colours.
You can also choose the Font Type and Font Size (in points) of the text in the editor - e.g. if you want a change from Courier New, or if the size seems a little small for you as standard (or you wish to see more of a line of code at one time - in which case, make the size smaller).
Changing Syntax-Highligting Colours
Under the Fonts & Colors heading, there is a sub-heading of Syntax Highlighting which allows you to change the colours / background / Font Style for different text elements for this particular language type.
A Code Template is simply a snippet of a program, or a skeleton of part of a program, that you may wish to use regularly, or wish to use as a reminder of how to complete a particular action.
For example, you may wish to retrieve form parameters from a HTML form using the CGI module, but do not remember the particulars. You could create a template with all the basics of how to do this and give it a name and shortcut so that you can easily retrieve it when you need it.
PerlWiz has over a hundred of these templates pre-defined with commonly used Perl, HTML and MySQL actions. For example, there is a template for producing a pre-defined sample HTML form.
To utilise one of the existing templates, type out the shortcut name (called an alias) and press the F6 key. In the above example, typing the word form in the editor and pressing F6 would replace the word form with the template relating to how to retrieve form parameters in a Perl program.
Alternatively, many of the templates are available by clicking on the Templates menu and selecting an option from one of the sub-menus. Template items are listed with their alias in brackets for easy future reference, if you wish to use the F6 key method.
If the code template has parameters (i.e. pops up dialog boxes to put text in appropriate places within the template), you can avoid using dialog boxes by following the alias with a : and then a comma-separated list of values to plug into the template (make sure you select the alias and the list of values before pressing F6. If you use particular templates all the time, this can speed up the process quite a lot - and seems quite magical the first time you do it!
So how do you go about adding new code templates to the existing ones?
Click on the Templates menu and choose Organize Code Templates option, or alternatively press Ctrl+F6.
The Code Template Explorer has a number of sections. At the top-left is an explorer section which has a hierarchical list of templates, split into sub-sections. Note that although it is possible to assign a code template to a section heading, it is not advised, as it is not possible to access the heading by clicking on a menu item this way (although you can still use the F6 method).
To open up the items under a heading, click once on the button to the left of the heading. To make the items under the heading disappear again, click on the button to the left of the heading.
Note that this hierarchy follows the menu hierarchy that you see under the Template menu in PerlWiz. You can see this reflected in an arrow-separated route beneath the tree. You can click on this path to copy it to the clipboard, if you wish to use it in documentation.
To find a specific code template, use the Find button, and type in either an alias or description. A match is made on the contents of a description, and a full-match of an alias (both are case insensitive).
The first match will expand the tree and select the appropriate node in the hierarchy. Click on the Find Next button to find any subsequent matches.
Finally, you can rearrange the structure of the code template hierarchy by dragging individual nodes around the tree. You can drag and drop a node anywhere you like, taking all of its child nodes with it.
Note that dragging a node and dropping it on top of another node will insert it before that node as a sibling node (i.e. insert it before the target node). If you wish to drag a node and make it a child of the target node, then hold down the Shift or Alt key before you drop the node by releasing the mouse button.
To amend one of the existing templates, click on any of the titles in the explorer section.
The alias and description (name) of the template will appear to the right of the explorer section in two text boxes. You can amend the alias, which is the shortcut used with the F6 key, and description (as appears in the menu) in these boxes.
The yellow window below this shows the code template itself - i.e. the snippet of code that you wish to keep. This can also be amended to your requirements.
There are also two buttons at the bottom - the Clear Text button which clears the snippet without removing it from the tree, and the Insert From Clipboard option, which takes the contents of the clipboard and places it at the current cursor position in the snippet window (e.g. if you copied a piece of text from elsewhere and wish to use it for, or as part of, the snippet).
You can also drag in files from Windows Explorer, which will copy the contents of the files into the text editor window, each headed with a Perl-comment style heading giving the file name from which the text originated.
If you wish to add a new code template, click on the location where you wish to place the code template. If you wish to add the template as a child of the template you have clicked on, click on Add Child. If you wish to make the template a sibling (i.e. at the same level) of the template you have clicked on, click the Add button. Then type in the details as if you were amending the template.
If you wish to make a template very similar to an existing template, click on the template you wish to copy, and then click on the Duplicate button. A new template with the same details will be created as a sibling to the selected template. Change the details as if you were amending the template to adjust the details to suit the new or revised template.
To delete the currently selected template from the structure, click on the Delete button and confirm the confirmation dialog box that pops up.
If you do not wish the template (or any of its children) to show in the menu hierarchy (e.g. if you are adding a large number of templates, and you do not wish to create too many submenus to avoid over-stretching system resources), then prefix an exclamation mark (!) before the Description of the template.
If you wish to add a divider bar into the menu structure, just add a code template that has only a single dash (-) as Description, and nothing as an alias.
If you wish to break the menu into more than one column, prefix the Description of the template at which point you wish the new menu column with either a > or a | if you wish to separate the previous and new column with a vertical bar. The bar will not show in the description on the menu.
Code templates are stored on the computer, and not with the project. If you wish to copy the code template to take to another computer, you can find its location by clicking on the menu and clicking on the Statistics heading. Look under the Code Templates sub-heading to see the filename under which the code templates are stored. Note that this file is compressed so that you can get a large quantity of text data in a relatively small file size - good for transporting to other computers.
Note that also under this section, you can find code template statistics - specifically showing how many nodes are in the code template tree, and how many of these are leaf nodes (i.e. non-headings) that are code templates.
Normally, the cursor will be placed at the end of the text after it has been inserted.
If you wish to place the cursor within the template (e.g. ready to do some editing at a specific point within a block), then insert the code ##CURSOR## within the text of the template. This will be removed, and cursor put in its placed when the code template is used.
You can do this by placing the cursor at the place in the template where the cursor is to be placed at the end of the code template being inserted, and right-click, and choose the Place Cursor here at end pop-up menu option. Any prior cursor placements will be deleted before putting the new code in.
If you wish to select some of the text within the code template ready to be replaced (or just for highlighting purposes) then put ##CURSOR## before the text to be highlighted and ##SELECT## at the end of the text to be highlighted.
You can get PerlWiz to do this, and remove any previous cursor placements / selections, by selecting the text you wish to be selected after the template is inserted, right-clicking and choosing the Finish off with this selected pop-up menu option.
You can make PerlWiz pop-up one or several dialog boxes for one or a series of parameters to place text from the pop-up into specific points of a template.
To pop-up a dialog box and insert text that the user types into the dialog, at a certain point in the template, place the following at the appropriate point:-
##PROMPT:prompt text:default value##
Where prompt text is the prompt to display in the dialog box to inform the user what needs to be typed, and default value is the default value to place in the dialog box if a specific value is commonly used.
You can have multiple prompts within the same template. Each one is numbered internally by the order in which it appears - i.e. the first prompt is numbered 1, the second 2 etc.
If you wish to place the value collected by the prompt elsewhere within the template (e.g. if you collected a variable name which is to be used in several places in the template) then use the following command at the place where the variable is to be inserted:
Where the prompt number is the number of the prompt (e.g. 1 for the first one in the template etc.) to be inserted at this point.
When testing your CGI scripts using PerlWiz, the output is sent to a temporary file and shown in an inbuilt web browser window in order to preview the results.
For most purposes, this is fine. However, if you wish to interactively test the submission of data from a form to one of your CGI scripts, you will need a web server installed on your computer so that the data is picked up, interpreted correctly to be submitted to a Perl program, and then executed in the Perl program, with the results sent back to the web browser.
Setting up a web server on your computer is not a trivial matter, and can deter many people from writing more complex CGI scripts. If you wish to do so, you may like to try the Apache web server, which is used by many ISPs, so would be a close match to how your program would work in reality.
However, if you just wish to test your Perl programs to make sure the forms are working correctly, then you may wish to utilise the Web Server built in to PerlWiz.
This has very limited functionality - i.e. it is only designed to execute Perl CGI and HTML pages, and only copes with straight page retrieval and GET / POST. However it is adequate for most people's testing requirements.
One point to note - if you are working on a computer that is constantly attached to the internet (e.g. if you have broadband or are connected via a cable operator) then you may wish to invest in a firewall to avoid the possibility of anyone connecting to your computer and executing your (possibly less-than-secure) Perl programs. The likelihood of this happening is slim, but it pays to be cautious. You might like to try the free (for personal use) Kerio Personal Firewall which seems to be very stable compared to some other well-branded products.
To turn the web server on or off, click on the button on the toolbar to switch between the server being active and inactive. Note that this changes the way that web pages are viewed from Perl and HTML documents - if viewed when the web server if turned off, then the file will be displayed directly. If the web server is turned on, the document will be requested from the PerlWiz web server using the domain name of localhost (equivalent of 127.0.0.1) - defined as your local PC.
If another program is using this port number (e.g. another web server, or another copy of PerlWiz), then you will be offered another port number to use instead. If you choose Yes then the new port number will be changed in the project, and used instead. If you choose No then the web server will not be started, but the port number will stay as before, to give you the chance to close whichever other server is operating before trying again.
Whilst this local web server is switched on, you can access it outside of PerlWiz using a normal web browser by typing http://localhost/cgi-bin/myprog.pl for example (assuming you chose the location of your Perl programs to be represented by the logical directory called cgi-bin and that you have kept the port to be 80 - the default for web servers).
Note that debugging features such as stepping, variable inspection and breakpoints are unavailable when executing a program through a web browser using a web server. The auto-detection of a down MySQL server is also disabled when the PerlWiz web server is enabled and the program is executed through a browser.
When executing a temporary file, its directory is not available to the web server for security reasons (temporary files from other projects could build up in this directory and pose a security threat). PerlWiz will automatically execute the program locally instead (i.e. not using the PerlWiz web server). For the purposes of a temporary file, this should not pose a problem for most people. Consequently, you cannot execute a temporary Perl program using a separate browser session.
In general, the following web server configuration details would be available automatically from the defaults, so you should be able to use the web server without any need for setting it up.
To set up the PerlWiz Web Server, select the Project Properties dialog box by clicking on the button, and opening the Web Server heading and clicking on the General sub-heading.
The first check box turns the web server on or off (once you have clicked either the Apply or OK button). This performs the same function as the button on the toolbar.
The Base Path refers to the place where the root of the web server is to be located. This means that when you type (for example) http://localhost/welcome.htm with the base path at c:\program files\perlwiz\projects, then the web server would look for the file at c:\program files\perlwiz\projects\welcome.htm
The base path is normally set to be the same directory as your project file. If you leave this box blank, this is where it will default to.
The Default Filename is the filename to look for if no filename is given in the browser URL. For example, if this is set to be index.htm then typing out http://localhost would retrieve the file held at c:\program files\perlwiz\projects\index.htm
The Port number is the port or socket number which the browser and web server use to communicate. The default is 80 for web server, but if you have another web server on your computer, you may want to change this - e.g. to 8080.
To amend CGI related settings (which relate to executing Perl / PHP programs utilising the inbuilt web server), click on the CGI (eg. Perl) sub-heading under the Web Server heading:-
For example, if the base path was c:\program files\perlwiz\projects\source, the logical path was cgi-bin and the document requested by the web browser was http://localhost/cgi-bin/app/welcome.cgi then the Perl program found at c:\program files\perlwiz\projects\source\app\welcome.cgi would be executed, and the output sent back to the web browser.
Perl can interact with various different types of database types through the DBI module. One such database management system is MySQL, popularly used by Internet Service Providers as it is distributed through the Open-Source GPL license, which means it is free to download and use for uses where MySQL will not be changed and/or re-distributed commercially.
To find out more information on downloading MySQL, click here, and for information on setting up PerlWiz to work with MySQL, click here.
You can create lists of SQL instructions for creating, amending, and even querying databases, and save them into files ending with .sql which will then be syntax-highlighted appropriately.
If you try to execute a file ending with .sql (or view it using the Text Output window), PerlWiz will attempt to execute that script using the version of MySQL that is currently set up to work with PerlWiz. If the appropriate option is set, and the script fails due to the database server not being in operation (i.e. not being up) then PerlWiz will prompt you to see if you wish it to bring the server up automatically. It will choose the best version / connection method for your operating system. You can then execute the script again. Note that this will also work for Perl programs that use the DBI with MySQL.
Note that if you only want to execute a portion of the script, highlight those commands that you wish to execute in the Editor window, and then run the script. Only those commands highlighted will be executed.
One problem with this is that you may have certain commands in the script that you wish to execute every time, irrespective of whether they are highlighted or not.
For example, you may wish to insert some rows into a table, but before you can use the table, you need to select the database where the table is situated, which is probably towards the beginning of your script.
You can identify a list of commands that must be executed every time, whether or not you have selected only some of the commands to execute in the script. To do this, you must start the list of commands with something like this:-
#PERLWIZ-HEADER-START USE mydb; #PERLWIZ-HEADER-END
So the bits in bold identify the start and end of the section to execute. They must be typed exactly as shown in UPPER CASE. This can be located anywhere in the program, and will be executed before the command(s) you have highlighted (but only if you have something highlighted). You can access this through a code template by typing out sqlhdr and pressing F6.
Less likely, you may wish to execute something after any commands that you highlight. You can define this as follows:-
#PERLWIZ-FOOTER-START SHOW TABLES #PERLWIZ-FOOTER-END
In this example, whatever command(s) you selected, a list of the tables in the current database will be shown. You can access this through a code template by typing out sqlftr and pressing F6.
The results of the process will be shown in the Text Output window. Note that if the process is taking too long, you can stop the process with the button on the toolbar, although the MySQL server may continue to process the currently executing operation in the background.
You can change the location of the MySQL database tools, and change various MySQL-related settings through the Project Properties dialog box.
You can do this by clicking on the button to look at the Project Properties dialog box, and then open the Language heading, open the SQL heading, and click on the MySQL Tools sub-heading.
There are a number of options here that you can use to customize how PerlWiz operates with MySQL. Here's a summary:-
If you navigate to the sub-heading Login Details, you will find the following options:-
Text files from different sources can denote line endings using different character combinations. For this reason, PerlWiz will automatically detect the file source as one of PC (Dos or Windows format - lines end with CR+LF), Unix (lines end with CR) or Macintosh (lines end with LF).
You may wish to save the file again as a different format - for example, if you were uploading to a Macintosh remote Web Server, it may expect text or html files to be in Macintosh text file format.
To change the way the file is stored, click on the File menu, click on the Line Endings option and choose one of the three formats - PC (the native text file format for Dos and Windows based systems), Unix (typically used for ISP web servers), or Macintosh.
The original format of the file when you put it into the project is also stored within the project, in case you need to change back to this later. You can also select this as an option.
Note that clicking one of these file format options will immediately save the file onto disk in the new file format.
Note that if you store your file in PC based format, then if you select the ASCII mode of transfer when uploading to a web server, then it will automatically be converted to the appropriate format on the server- i.e. to Unix format on a Unix server - and left as native PC format on your computer. If you wish to save files in non-PC format on your PC, you should use the Binary mode of transfer.
Note that you may not be able to satisfactorily open the text file using other text editors on your computer if you change the format to anything other than PC (Dos/Windows) format - if you find this is the case, just change the format to PC (Dos/Windows) format from within PerlWiz.
Finally, temporary files are stored within the project file (in case different projects are opened and the temporary files are overwritten in between times). Thus if you change the line-ending format of a temporary file, the project file will be in a modified state, waiting to be saved with the temporary file in the new format.
You can insert the contents of another file at the current cursor position in the editor using one of two methods:-
This can be useful as an alternative 'code template' facility, or if you wish to copy the contents of a previous program to be part of a new program.
You may wish to save your Perl program to show it "as is" on a web page - e.g. if you have a Perl-based web site that gives advice on Perl programming, or even if you wish to view a Perl programming complete with syntax-highlighting colours outside of the PerlWiz program.
To do this, click on the File menu, select the Export menu, and choose the to HTML... option, and choose a filename to save the program to. Note that this will be a HTML file, and cannot now be used to execute the Perl program.
You can use this to export HTML files and their associated syntax-colouring too, if you wish.
You may also wish to export data to Rich Text Format, which can be opened directly using Word Processor programs such as Microsoft Word and WordPad (which comes with the Windows operating system).
To do this, click on the File menu, select the Export menu, and choose the to RTF... option, and choose a filename to save the program to. Note that this will be a Rich Text file, and cannot now be used to execute the Perl program.
To print the currently selected program, click on the File menu and choose the Print option (or use the keyboard shortcut of Ctrl+P).
You can choose a different printer to print to, or print multiple copies. You can also choose a page-range to print, or just print the currently selected text only.
Click on OK to confirm printing.
Note that printing to a colour printer will maintain the syntax highlighting that you have set up for the editor.
To obtain help on the currently selected part of the program (i.e. to obtain Context help), hold down the Ctrl key and press the F1 button (or click on the Help menu and click on Context Help).
For help contents (i.e. the contents section with hyperlinks to various parts of the PerlWiz Help), press the F1 key, or click on the Help menu and choose the Contents menu option.
To view this reference section, describing the various functions of the PerlWiz application, click on the Help menu and choose the Reference menu option.
Currently, there are five tutorials available, designed as an introduction to using the functionality of PerlWiz for real-life programming scenarios. These are available through the Tutorials menu option on the Help menu:-
To launch your default browser, and view one of the more commonly utilised pages on the PerlWiz web site at http://www.simonhuggins.com/arctan/perlwiz click on the Help menu and choose the PerlWiz Web Site menu option.
A sub-menu will be shown giving key pages available from the PerlWiz web site, including the Home Page, Orders / Registration Page, Support Page, Download Page, and URL links to related web sites.
To launch the ActivePerl help documentation, which includes details about your Perl installation, as well as help on various aspects of the Perl language, and any installed perl modules, click on the Help menu and choose the ActivePerl Documentation menu option. This option is greyed if ActivePerl is not installed.
To launch the MySQL help documentation, which gives a lot of useful advice on how to use the MySQL utilities that come with MySQL server, as well as information on how to use the data query / manipulation language for working with databases, click on the Help menu and choose the MySQL Documentation menu option. This option is greyed if MySQL is not installed, or if the documentation cannot be found at the standard location.
To view details about how to register your product online, and the benefits of doing so, click on the Help menu and select the How To / Why Register menu option. Note that this option is disabled once you have registered the product. You can still see the page via the main Help Contents page described above.
To view details about which version of PerlWiz that you are using, as well as About text and License Agreement (Copyright) text, click on the Help menu and select the About... menu option.
Finally, you can browse / change the help pages available by clicking on the Help menu and selecting the Designer option. This will show a hierarchical arrangement of help options that you can browse. You can click on any of the nodes to find their location. The buttons at the top of the window allow you to save any changes, add a new child node to the currently selected item, Delete the currently selected node, Launch the node file (typically a HTML page), print the page (if it has an associated print action defined in the Windows Registry), or edit the page (ditto the print option).
Note that the PerlWiz program uses the name path of the nodes to determine which file should be launched for different contexts when using the context help option. It will launch the root node, which must be called contents when the Contents option is selected or F1 is pressed.
If you wished to use a different contents page, you could change the filename of the page to launch - e.g. you may wish to launch the Reference page instead, if you refer to it often.
You could also introduce your own manual pages into the hierarchy if you prefer, rename the original that you wish to stop using, and give them the new file a name that matches the original, to get context help to refer to your own notes.
If you wish to use subdirectories under the help folder, you can use the rel option to refer to relative file - e.g. a subdirectory name.
If you wish to check to see if there is a newer copy of PerlWiz available, you can either manually check the web site at http://www.simonhuggins.com/arctan/perlwiz/download.html or use the auto-update facility built into PerlWiz, described here.
To check for the latest update, ensure first that you are connected to the internet either through your network, using a cable modem, or using a dial-up adaptor (i.e. connected to a telephone line via an internal modem). Note that at present, this will not work with firewalls that require a userid / password to gain FTP access - check first, as some internal networks only restrict web access, but allow client access to external FTP servers.
To start the auto-update process:-
The ActivePerl tools have a few utilities designed to keep your installation of Perl up-to-date. One of these is the PPM tool, which PerlWiz utilises in order to provide you with an easy-to-use method of keeping your Perl modules up-to-date.
Perl can be extended by adding extra modules, some of which come with documentation that automatically gets put into the ActivePerl help file. Many modules are included as part of the standard installation of Perl.
If you wish to install any new modules to gain extra functionality, or if you wish to remove any of the modules if they are not longer required, or if you wish to update existing modules in order to keep up-to-date with the latest version, then you can use the PerlWiz Module Installer to streamline the task for you.
Important: At the time of writing, if you wish to use the Module Installer, it will be necessary to have ActivePerl version 5.6.1 or lower installed. This is due to a problem with ActivePerl which should be rectified in a future release of ActivePerl (currently 5.8.0 which gives a problem).
Note that you cannot be in the process of debugging or executing any Perl programs or MySQL scripts when you execute the Module Installer - the option will be greyed.
To launch the PerlWiz Module Installer, click on the Tools menu and click on the Module Installer... menu option.
A dialog box pops up in the middle of the desktop.
To see what is currently installed, leave the Module Name blank, and click on the Search Local button.
After a few seconds, a scrollable list will appear in the orange listbox as so:-
Each line on the display represents a Perl module installed by PPM on the ActivePerl installation.
This is split into three columns - the module name, the version, and a description of the module.
Notice that when you click on one of the lines, the full description pops up as a yellow tooltip.
If we now wanted to check whether the selected module was up-to-date (i.e. the latest version), we would click on the module that we wish to upgrade, and click on the Upgrade button. In the example below, the DBI module is up-to-date already.
If you think that there is a problem with the installed module - e.g. it has become corrupted, or you have changed aspects of it during testing, and wish to reinstall the original, click on the Force Upgrade option prior to clicking on the Upgrade button. This will disable the checking to see if the module is up-to-date, and the module is reinstalled irrespective of its current version.
If you wish to upgrade every module on your system, then click on the Search Local button first, and make sure you DON'T click on any module. Click on the Upgrade button and a dialog box will appear saying No Module Specified. Upgrade all out-of-date modules?
Click on the OK button to check every installed module on this installation of ActivePerl and upgrade it if necessary, or click on the Cancel button if you have changed your mind.
Note that this process could take a long time, especially over a slower (e.g. dialup) internet link. Be prepared for a wait of between five minutes and an hour - best to do it just before a favourite TV programme!!
If you wish to reinstall everything irrespective of whether it is up-to-date (e.g. if you suspect some sort of corruption) then click on the Force Upgrade option prior to clicking on the Upgrade button. This will disable the checking to see if a module is up-to-date, and all modules will be reinstalled irrespective of their current version. As you can imagine, this could take a very long time compared to just upgrading out-of-date modules, so be prepared for a wait of between half an hour and the whole afternoon!!
If you wish to install a module, then you must first find it. To do so, you first search for available updates by typing in the name of the module in the Module Name text-box, and then clicking on the Search CPAN button (or press Enter). Note that you must be connected to the Internet in order to do this. See later if you have a firewall.
In the example below, there is a short delay, and a list of modules with mysql in the module name appears. The DBD-mysql line has been clicked to install MySQL use within Perl, and then the Install button. When the process has finished, a dialog box pops up to inform you of this.
Note that the last typed module name is stored with the current project in case you wish to use it again later.
If you have finished with a module installed on the system, and have no further use for it - e.g. if you had previously installed it, but it did not fit y our needs, then you can remove it from the Perl installation. After doing a Search Local, just click on the module to remove, and click on the Remove button. In the example below, the DBD-mysql module has been successfully removed. If you wish to ensure it has been removed, click on Search Local again to ensure it does not appear in the list.
If you are behind a firewall, you will need to set up three environment variables (either outside the program, or in the project environment options) - HTTP_proxy which give the proxy server host name - often an IP address (e.g. 22.214.171.124) - specify the protocol (http://) followed by the URL/IP address, and if necessary the port number (a colon followed by the number) - the default for HTTP being 80, HTTP_proxy_user to give your proxy user login name, and HTTP_proxy_pass to give your proxy user login password. To get to the screen to change these, click on the button on the toolbar, choose the Environment heading, select the Variables sub-heading, and enter the three options on this page - see the example to the right for an example.
File associations are links into the Windows operating system, to enable you to browse files in Windows Explorer, and double-click on a file with a specific ending, and execute an associated application to open that file automatically.
PerlWiz will by default associate itself with common file types that it is able to edit - for example, Perl files, SQL files and PWP (project) files. It does not attempt to link to HTML files, as these are typically better associated to a web browser.
If the file associations are changed by another application, you will see this box automatically when you first start PerlWiz, to give you the opportunity to switch the settings back again. Any changes are highlighted in red.
If you are happy to allow another application to be associated instead of PerlWiz, accept the settings by clicking on the OK button, and the dialog box will not show again (unless there are any other changes). If you do not wish to make up your mind at this time, just click on the Cancel button to continue on to using PerlWiz.
If however, you wish to keep the association with PerlWiz, tick the box marked in red, and click on the OK button. You can make any other changes to associations at the same time, if you wish.
If you aren't interested in file associations, and you don't want the box to come up again, irrespective of whether another application has taken over any file associations, check the Do not check for changes in the future option and click on the OK button. If you wish to change any of the associations, or re-enable the check in the future, you can view this dialog box and make any changes from inside PerlWiz by clicking on the Tools menu and choosing the File Associations... menu option.
(c) Copyright 2003-8
Arctan Computer Ventures Ltd. All Rights Reserved.
If you have any issues regarding this on-line help, please contact the author by clicking here.
Alternatively, you can leave a voice message on +44(0)7050-618-297 or fax on +44(0)7050-618-298
This Page was last updated: 01 February 2007 00:45