Perl Oasis -- A Perl Dev Tool for Windows
If you use something other than UltraEdit, go to ``File | Preferences...'' and select your editor there.
Now take it for a spin!
Perl Oasis is a POD/source/class browser tightly integrated with (currently) UltraEdit, gVim, EditPlus, and PFE (Programmer's File Editor).
It makes it easy to navigate source code, POD, modules and your files.
Perl Oasis is in beta currently, but feel free to download and spread the word. I'm very interested in comments and bug reports.
2003-06-01
The Perl license applies.
http://www.bahnhof.se/~johanl/perl/Oasis/
Oasis_source.zip contains the entire source tree.
Oasis_binary.zip is the end-user distribution, a freestanding GUI PerlApp application. You will not need any particular module installed.
Start UltraEdit or some other supported editor (it works without those editors but not nearly as smoothly). Start Perl Oasis. If you have a file opened in the editor, it is loaded into Oasis. You may have to configure which editor you use in ``File | Preferences...''.
Always, the file you currently have open in the editor should appear in the topmost text field in Oasis. Click the ``Load'' button to bring the file into Oasis.
File | Open... works for opening a file, but you can also ``Copy'' a file in the Explorer, move to Oasis and ``Paste'' it into the text field, or drag-n-drop files from the Explorer (useful if you don't have any of the supported editors).
The file is parsed and the contents is displayed.
Explore!
Try opening a few of your own files, the Oasis source files and modules on your system. Oasis doesn't ever change any source files.
The location combo box can contain file names and directories.
This is NOT the currently loaded file (you can see that in the status bar). When Oasis isn't active, the combo box is set to the current file in the editor.
Click ``Load'' to load the entered file into Oasis. Or, if you entered a directory name (ending with a \), click ``Load'' to add the entered directory to the Projects list.
There are two tabs to the left; Module and Folders. The Module tab contains information pertaining to the curretly loaded file/module. The Folders tab contains things to help you navigate between files and modules.
The source of the currently loaded file is parsed in a simplistic but useful way to extract meta-information which is displayed in the Module tab to the left. Select a node in the tree to display the corresponding text in the right pane. Double click to go to the editor or to open the selected module or file.
Parsing Perl code correctly is difficult in the extreme. So I don't do that. I take the easy way and assume a lot of coding convention. If it bites you, please let me know and I'll see what I can do without breaking anything.
A thread about parsing Perl code:
http://www.perlmonks.org/index.pl?node_id=44722
If you run Perl Oasis using the Perl source, you'll need to patch and rebuild your Win32::GUI module for the drag-n-drop feature to work. If you run the binary, everything will work just fine.
Look at the Win32::GUI::DragDrop module for more information.
The POD is parsed using POD::Parse. =head1 and =head2 items are displayed in the tree. Both the POD tab and the source tab are positioned at the correct location when you select a node.
Subroutines are defined as lines that start with ``sub something'', or BEGIN, END, etc. blocks.
``Used modules'' are defined as lines that start with ``use'' or ``require''. Double click to load that module. Oasis will find the file if it's in a project of yours or in an @INC directory.
``@ISA modules'' is an inheritace tree, defined as the module's parent modules as specified in the @ISA array. Double click to load that module.
A Bookmark is a custom pattern used to identify certain parts of the code. You can define your own by editing the config file resource/oasis.xml.
Example -- The bookmark ``Todo'' is defined as lines that contain ``##todo'' (load the file lib/PDE/App.pm to see an example of this).
Example -- The bookmark ``Debug_print'' is defined as lines that start with ``print'' something. This is a personal coding practice of mine; all flush-left tprint statements I put in the code tends to be debug print output, so it's very useful to indicate it. You may want to change/remove this in the config file.
I'd appreciate suggestions for useful default Bookmark patterns.
``Projects'' are folders that have been found to be base directories for modules or required files.
A Project directory may contain other directories. When you click on a directory, the directory will be displayed.
When you load a new file, it's added to the top of the Recent files list.
@INC is the default include directories.
The usual stuff.
Note that you don't have to open files with the File | Open... menu item. You can drag-n-drop files from the Explorer, and you can also copy a file and paste it into the combo box.
When View | Toolbar is checked, a small toolbar is visible when you are using your editor.
The help text you are reading now, as well as practical links to the local HTML perldoc pages.
Check the menu item View | Toolbar to have a floating toolbar appear when you are using the editor.
Oasis provides a number of useful locations for the toolbar, or you can place it freely. The buttons on the toolbar provides useful functions:
Copy the name of a sub and ``Find Sub'' will take you to where it is declared in the current file (todo: or in the inheritance tree, or in any recently opened file)
new()``Find Sub New'' will take you to where the sub new() is
declared in the current file.
Copy some text and ``Find POD'' will take you to where it is documented (in a =head1 or =head2) in the current file (todo: or in the inheritance tree, or in any recently opened file)
Open the currently edited file in Perl Oasis (or reload it if it's already there).
Double-click on the location icon at the bottom. When you are satisfied, move to the editor and watch the toolbar move to it's new location.
The toolbar can snap to any outside corner, the left or right side, or in a clever place inside the editor window that won't obscure anything important (well, most of the time). You can also place it wherever you like on the screen.
It all started with UltraEdit because... well... that's what I use. The complete list is slightly longer:
If you need support for another editor, please e-mail me (mailto:johanl@bahnhof.se)
Note that not all editors have the capacity to be integrated with Perl Oasis.
What's needed is basically a) a way for Perl Oasis to determine which file is being edited, and b) a way to open a file in the editor (without starting a new instance if the file is already being edited) and go to a particular line.
UltraEdit lists the file name in the window title, and accepts file name + line number on the command line.
PFE reveals the file name through DDE, and accepts file name + line number on the command line.
Editors I have tried to do, but failed include
Some things can be configured using File | Preferences... For some things you have to edit the config file resource/oasis.xml. Be careful. Keep a backup copy.
The entire config should eventually be managed through Edit | Preferences...
Add support for EditPlus.
Use Win32::GUI::Scintilla for source code display.
Add support for gVim.
Add alpha (unstable, but hey it works if you're careful) support for PFE.
Inital public release
Larry Wall - for Perl
Aldo Calpini - for the Win32::GUI GUI toolkit
The people at http://www.scintilla.org/ScintillaHistory.html
Laurent Rocher - for the adapting Scintilla to Win32::GUI
Johan Lindström, johanl@bahnhof.se