sourCEntral - mobile manpages

pdf

Padre

NAME

Padre − Perl Application Development and Refactoring Environment

SYNOPSIS

Padre is a text editor aimed to be an IDE for Perl.

After installation you should be able to just type in

  padre

and get the editor working.

Padre development started in June 2008 and made a lot of progress but there are still lots of missing features and the development is still very fast.

Getting Started

After installing Padre you can start it by typing padre on the command line. On Windows that would be Start/Run padre.bat

( TO DO ) By default Padre starts with an editor containing a simple Perl script and instructions.

You can edit the file and save it using File/Save ("Ctrl+S").

You can run the script by pressing Run/Run Script ("F5")

You can start new files File/New ("Ctrl+N") or open existing files File/Open ("Ctrl+O").

By default Padre uses the same Perl interpreter for executing code that it uses for itself but this will be configurable later.

FEATURES

Instead of duplicating all the text here, let me point you to the web site of Padre <http://padre.perlide.org/> where we keep a list of existing and planned features.

DESCRIPTION

Configuration
The application maintains its configuration information in a directory called .padre.

Files operations
File/New
creates a new empty file. By default Padre assumes this is a Perl script. ( TO DO later this default will be configurable).

File/Open allows you to browse for a file and select it for opening.

File/Open Selection, ("Ctrl+Shift+O") if there is a selected text this will try to locate files that match the selection. If the selection looks like a path Padre will try to open that path either absolute or relative. If it looks like a module name (Some::Thing) it will try to find the appropriate file Some/Thing.pm in @INC and open it. currently this feature opens the first file encountered. ( TO DO it should find all the possibilities and if there are multiple hits offer the user to choose. This will be especially important if we are working on a module that is also already installed. Padre might find the installed version first while we might want to open the development version.)

( TO DO: when the file is not of Perl type we should have other ways to recognize files from internal naming and have paths to search. Surprise, not every language uses @INC.)

File/Close − checks if the file is saved, if it is closes the current tab.

File/Close All − closes all opened files (in case they are not saved yet ask for instructions).

File/Close All but Current − closes all opened files except for the currently being edited.

File/Reload File − Reloads the file. This is interesting if you either made changes and want to discard them and/or if the file has changed on the disk. If there are unsaved changes Padre will ask you if you really want to throw them away. ( TO DO: make a backup of the file before discarding it)

File/Save "Ctrl+S" − save the current file. If the buffer is not yet saved and has no file name associated with it, Padre will ask you for a file name.

File/Save As − Offer the user to select a new file name and save the content under that name.

File/Save All − Save all the currently opened files.

File/Convert − Convert line endings to Windows, Unix or Mac Classic style.

Files/Recent Files − a list of recently opened files to open them easily. ( TO DO: update the list when we open a file, not only when opening padre) ( TO DO: allow the user to configure size of history)

File/Doc Stats − just random statistics about the current document. ( TO DO: If you miss anything important let us know!)

File/Quit − Exits Padre.

Simple editing
The simple editing features (should) provide the expected behavior for Windows users.

Edit/Undo "Ctrl+Z"

Edit/Redo

Edit/Select All "Ctrl+A", select all the characters in the current document

Edit/Copy "Ctrl+C"

Edit/Cut "Ctrl+X"

Edit/Paste "Ctrl+V"

( TO DO What is "Ctrl+D" ?, duplicate the current line?)

Mouse right click
Click on the right button of the mouse brings up a context sensitive menu. It provides the basic editing functions and will provide other context sensitive options.

Projects ( TO DO )
Padre will have the notion of a Perl project. As we would like to make things as natural as possible for the Perl developer and we think the distribution methods used for "CPAN" module are a good way to handle any project Padre will understand a project as a "CPAN" module. This does not mean that your project needs to end up on "CPAN" of course. But if your projects directory structure follows that of the modules on "CPAN", Padre will be automatically recognize it.

Module::Starter
As a first step in the direction of supporting "CPAN"−style Perl projects we integrated into Padre the use of Module::Starter

File/New.../Perl Distribution will bring up a dialog box where you can select some of the parameters your new project has such as Name of the Project (e.g. My::Widgets), Author − that is probably your name, e−mail (your e−mail).

Builder is the tool that you project is going to use to package itself and then your user will use to install the project. Currently Module::Build and ExtUtils::MakeMaker are supported. ( TO DO add Module::Install as well).

License is one of the keywords currently listed in the META .yml spec of Module::Build. ( TO DO: update the list or make it dynamic)

Once you click OK , Module::Starter will create a new directory called My-Widgets in the parent directory you selected in the last field.

Other
On Strawberry Perl you can associate .pl file extension with C:\strawberry\perl\bin\wxperl and then you can start double clicking on the application. It should work...

Run This ("F5") − run the current buffer with the current Perl this currently only works with files with .pl extensions.

Run Any ("Ctrl+F5") − run any external application

First time it will prompt you to a command line that you have to type in such as

  perl /full/path/to/my/script.pl

...then it will execute this every time you press "Ctrl+F5" or the menu option. Currently "Ctrl+F5" does not save any file. (This will be added later.)

You can edit the command line using the Run/Setup menu item.

Please Note that you can use $ENV{PADRE_VERSION} to detect whether the script is running inside Padre or not.

Bookmarks
View/Set Bookmark
("Ctrl+B") brings up a window with a predefined text containing the file name and line number ( TO DO should be the content of the current line).

View/Go to Bookmark ("Ctrl+Shift+B") brings up a window with the list of available bookmarks. You can select one and press OK to jump to that location. If the file where the bookmark belongs to is not open currently, it will be opened and the cursor will jump to the desired place.

In both cases while the window is open you can select existing bookmarks and press the Delete button to remove the selected one or press Delete All to remove all the existing bookmarks.

Navigation

  Ctrl+G          Go to Line
  Ctrl+1          Matching Brace
  Ctrl+2          Quick Fix
  Ctrl+.          Next Problem
  Ctrl+P          Word Auto−completion
  Alt+N           Nth Pane
  Ctrl+Tab        Next Pane
  Ctrl+Shift+Tab  Previous Pane
  Alt+S           Jump to list of subs window
  Ctrl+M Ctrl+Shift+M  comment/uncomment selected lines of code
  Ctrl+H opens a help window where you can see the documentation of
  any Perl module. Just use open (in the help window) and type in the name
  of a module.
  Ctrl+Shift+H Highlight the name of a module in the editor and then
  press Ctrl+Shift+H. It will open the help window for the module
  whose name was highlighted.
  In the help window you can also start typing the name of a module. When the
  list of the matching possible modules is small enough you'll be able
  to open the drop−down list and select the name.
  The "small enough" is controlled by two configuration options in the
  Edit/Setup menu:
  Max Number of modules
  Min Number of modules
  This feature only works after you have indexed all the modules
  on your computer. Indexing is currently done by running the following command:
  padre −−index

Rectangular Text Selection
Simple text editors usually only allow you to select contiguous lines of text with your mouse. Sometimes, however, it is handy to be able to select a rectangular area of text for more precise cutting/copying/pasting or performing search/replace on. You can select a rectangular area in Padre by holding down "Ctrl+Alt" whilst selecting text with your mouse.

For example, imagine you have the following nicely formatted hash assignment in a Perl source file:

  my %hash = (
      key1 => 'value1',
      key2 => 'value2',
      key3 => 'value3',
 );

With a rectangular text selection you can select only the keys, only the values, etc..

Syntax highlighting
Padre is using Wx (aka wxPerl), wxWidgets for GUI and Scintilla for the editor. Scintilla provides very good syntax highlighting for many languages but Padre is still bound by the version of Scintilla included.

The share/styles/default.yml file is the mapping between the Scintilla defined constants for various syntactical elements of each language and the "RGB" values of the color to be used to highlight them.

Adding new syntax highlighting

To set up a custom syntax highlighting scheme, you create a .yml file that defines the mappings described above. The easiest way to create your own scheme is probably to copy an existing .yml file (for instance, default.yml) from the share/styles/ folder, put it in ~/.padre/styles, and then modify it. Padre checks this folder on start-up and adds any styles in the .yml files there to the "View −> Style" menu.

TO DO does this stuff below really belong here?

Need to define constants in Padre::Util to be in the "Padre::Constant" namespace.

Need to add the color mapping to share/styles/default.yml

Need to implement the "Padre::Document::Language" class.

Need to define the MIME type mapping in Padre::Document

For examples see Padre::Document::PASM, Padre::Document::PIR, Padre::Document::Perl.

Syntax checking
Depending on a corresponding support in the respective "Padre::Document::Language" class, Padre supports real time syntax checking capabilities:

Syntax errors or warnings are displayed in a side bar (usually at the bottom of the Padre window). By double-clicking a list entry you can navigate to the position in the file.

Additionally, there is a symbol column on the left side of the editor where colored symbols mark the code lines with problems.

WARNING NOTE

Syntax checking for Perl5 documents comes bundled with Padre. It is implemented using "perl −c". This means that parts of the code actually get executed (e.g. "BEGIN" blocks). Malicious software might used this fact to damage your system ("BEGIN { system('rm −rf ~') }") or suck up your resources ("BEGIN { while(1) { } }"). Syntax checking is currently disabled by default and has to be enabled manually after every start of Padre. This somewhat increases security when doing "padre some_unknown_file.pl". However, it does not protect you when you open a file from within Padre while syntax checking is turned on. The most secure solution would require a really fast non-executing syntax checker which unfortunately is currently not available.

Preferences

There are several types of preferences we can think of. There are the current view printed preferences such as Show newlines or Show Line numbers and there are the project and file oriented preferences such as the use of tabulators or white space for indentation.

We would like to achieve that the

Currently some of the preferences are accessible via the Edit/Preferences menu options, others via the View menu option.

We have to make sure that when changing the preferences via the GUI it change for the correct things.

E.g. when changing the Use Tabulators preference it currently applies to all the files open currently or in the future. It should probably apply to the current file and/or the current project. Such options − when changing them − might even be applied "retroactively". That is when I change the tabulator/space mode of a file or a project it should ask if I want to reflow the file with the new method of indentation?

On the other hand the "Tabulator display size" is purely a local, editor oriented preference. It should probably apply to all files currently open.

There are other aspects of preferences as well that might not exactly overlap with the above set:

The developer might work on the same project on different machines. In such case some of the personal preferences should apply only only on one computer while others apply in both places.

In particular if Padre is installed in a Portable Perl it might run on machines with different parameters. Screen size and resolution might be different along other parameters. We would like to make sure the relevant preferences are separated from those that are constant even when moving between computers.

Editor or view oriented preferences
Size and location of windows
Show/Hide various windows, Status bar, Toolbar
Files recently opened
Files that were open last time, cursor location
Show newlines
Show Line numbers
Show indentation guide

View/Show Indentation Guide

When set, Padre will display a thin vertical line at every indentation level on every row with are indented more than one level.

Highlight indentation guide ( TO DO )

This should be a separate option available only if the "Show indentation guide" and brace matching is on.

If "SetHighlightGuide" is set to 8 then when the user reaches one side of a pair of braces the indentation guide − if there is one on column 8 − will be highlighted. (in green).

As I understand Padre should constantly adjust the "SetHighlightGuide" so that in every block the "correct" indentation guide is highlighted.

Show Call Tips
Tabulator display size
Allow experimental features

In order to allow the experimental features one needs to manually turn on the experimental flag to 1 in config.yml. As Padre keeps overwriting this file you’ll have to make this change with another editor and while Padre is not open.

The config.yml file is in ~/.padre/ on Linux/Unix and in general in your home directory on Windows. In any case the Help/About box will show you the path of the .padre directory of Padre.

Once you set the experimental flag when you start Padre you will see a new menu on the right side of the menu bar called Experimental.

Open file policy

What files to open when launching Padre? nothing, new, those that were open last time?

Max/Min number of modules to display in POD viewer
Auto-indentation

Possible values: no/same level/deep

There are at least two levels of auto-indentation:

1) when ENTER is pressed indent to exactly the same level as the previous line

2) if there is an opening brace { on the previous line, indent one level more

Brace matching

When the cursor reaches an opening or closing brace { }, square bracket [ ] or parentheses ( ), Padre automatically highlight the pair of the braces.

TO DO make this optional, let the user set the color

Auto-save on/off?

File and Project oriented preferences
Indentation should be by tabulators or spaces
In case of using spaces for indentation, the width of every
indentation level

Other features

Auto-backup (Planned)
See Padre::Autosave

When Padre opens a file it automatically creates a copy of the original in ~/.padre/backup/PATH where PATH is the same PATH as the full PATH of the file. On Windows the initial drive letter is converted to another subdirectory so c:\dir\file.txt will be saved as ~/padre/backup/c/dir/file.txt.

When a new file is created no need for auto-backup.

When a remote file is opened the backup will probably go to ~/padre/backup_remote/

Configurable options: on/off

Auto-save files (Planned)
Every N seconds all the files changed since the last auto-save are saved to a temporary place maybe ~/.padre/save.

When the user closes the file, the auto-saved file is removed.

Configurable options: on/off, frequency in seconds

SQLite

Padre is using an SQLite database (~/.padre/config.db) for two things. Part of the preferences/configuration information is kept there and it is used for the POD reader.

Documentation POD reader

Padre currently can index (the names of) all the modules on your system and it was planned to have a search capability for modules/functions/etc.

Plug-ins

There is a highly experimental but quite simple plug-in system.

A plug-in is a module in the "Padre::Plugin::*" namespace.

At start-up time Padre looks for all such modules in @INC and in its own private directory and loads them.

Every plug-in must be a subclass of Padre::Plugin and follow the rules defined in the Padre::Plugin API documentation.

See also Padre::PluginManager and Padre::PluginBuilder

While Padre is running there is a menu option to show the plug-in configuration window that shows the list of all the plug-ins.

TO DO: What to do if a newer version of the same plug-in was installed?

TO DO: What to do if a module was removed ? Shall we keep its data in the configuration file or remove it?

TO DO: Padre should offer an easy but simple way for plug-in authors to declare configuration variables and automatically generate both configuration file and configuration dialog. Padre should also allow for full customization of both for those more advanced in Wx.

Editing tools

Case Changes
Change the case of the selected text or if there is no selection all the text in the current file.

Change all characters to upper or lower case

Change the first character of every word to upper/lower case leaving the rest as they were.

Tab and space conversion
Tab to Space and Space to Tab conversions ask the number of spaces each tab should substitute. It currently works everywhere. We probably should add a mode to operate only at the beginning of the lines or better yet only at the indentation levels.

Delete All Ending space does just what it says.

Delete Leading Space will ask How many leading spaces and act accordingly.

Search, Find and Replace

(planning)

Search
"Ctrl+F"
opens the search window, if something was selected then that is given as the search text. Otherwise the last search string should be displayed.

Provide option to search backwards

Limit action to current block, current subroutine, current file (should be the default) current project, current directory with some file filters.

When the user presses Find

1.

We find the first hit and the search window disappears. "F3" jumps to next one.

2.

The first match is highlighted and focused but the window stays When the user clicks on the Find button again, we jump to the next hit In this case the user must be able to edit the document while the search window is on.

3.

All the matches are highlighted and we go to the first match, window disappears. "F3" jumps to next one

4.

All the matches are highlighted and we go to the first one, window stays open user can edit text

Find and Replace
Find − find the next occurrence

Replace all − do just that

Replace − if currently a match is selected then replace it find the next occurrence and select it

TO DO describe what to do if we have to deal with files that are not in the editor
if "Replace all" was pressed then do just that
1) without opening editors for the files.
2) opening an editor for each file and keep it in unsaved state (sounds crazy having 1000 editors open...) if Search or Replace is clicked then we might show the next location in the lower pane. If the user then presses Replace we open the file in an editor window and go on. If the user presses Search then we show the next occurrence. Opened and edited files will be left in a not saved state.

Code layout

Padre.pm

is the main module.

Padre::Autosave

describes some of our plans for an auto-save mechanism. It is not implemented yet. (There is also some description elsewhere in this document).

Padre::Config

reads/writes the configuration files.

There is an SQLite database and a YAML file to keep various pieces of information. The database holds host related configuration values while the YAML file holds personal configuration options.

The SQLite database holds the list of modules available on the system. It will also contain indexing of the documentation Looking at the "" entries of modules List of functions

Padre::DB

The SQLite database abstraction for storing Padre’s internal data.

Padre::Document

is an abstraction class to deal with a single document.
Padre::Document::PASM
Padre::Document::PIR
Padre::Document::Perl

Padre::PluginBuilder
Padre::PluginManager

locates and loads the plug-ins.

Plugin

Should be the base class of all plug-ins.

Padre::Pod2HTML
Padre::PPI
Padre::Project

Abstract class understanding what a project is.

Padre::Project::Perl

Is a Perl specific project. These are work in process. Not yet used.

Padre::TaskManager

Managing background tasks.

Padre::Task

Background tasks.

Padre::Util

Various utility functions.

Wx GUI
The "Padre::Wx::*" namespace is supposed to deal with all the Wx related code. Outside of that the code is not supposed to know about Wx, but currently it still does.
Padre::Wx
Padre::Wx::Ack

Implementation of the ack integration in "Edit/Ack" menu item. It probably should be either under Dialog or moved out to be a plug-in.

Padre::Wx::App

is the Wx::App subclass. Does not really do much.

Padre::Wx::Dialog

is the parent class of all the major dialogs that are all implemented in modules in the "Padre::Wx::Dialog::*" namespace. It is actually a plain subclass of Wx::Perl::Dialog.
Padre::Wx::Dialog::Bookmarks
Padre::Wx::Dialog::Find

Current Find and Replace widget.

Padre::Wx::Dialog::ModuleStart

Module::Start integration. Maybe it should be moved to be a plug-in.

Padre::Wx::Dialog::PluginManager
Padre::Wx::Dialog::Preferences
Padre::Wx::Dialog::Search

This is the newer Firefox like search box. Not yet integrated.

Padre::Wx::Dialog::Snippets

Padre::Wx::FileDropTarget

The code for drag and drop

Padre::Wx::Editor

holds an editor text control instance (one for each buffer/file). This is a subclass of Wx::StyledTextCtrl also known as "STC" or Scintilla.

Padre::Wx::History::ComboBox
Padre::Wx::History::TextEntryDialog
Padre::Wx::Main

This is the main window, most of the code is currently there.

Padre::Wx::Menu

handles everything the menu should know and do.

Padre::Wx::Output

the output window at the bottom of the editor displaying the output of running code using "F5".

Padre::Wx::HtmlWindow
Padre::Wx::PodFrame
Padre::Wx::Popup

not in use.

Padre::Wx::Printout

Implementing the printing capability of Padre.

Padre::Wx::SyntaxCheck

Implementing the continuous syntax check of Perl code.

Padre::Wx::ToolBar

handles everything the toolbar should know and do.

BUGS

Please submit your bugs at <http://padre.perlide.org/>

SUPPORT

I hope the <http://www.perlmonks.org/> will be ready to take upon themselves supporting this application.

See also <http://padre.perlide.org/>

COPYRIGHT

Copyright 2008−2010 The Padre development team as listed in Padre.pm. <http://padre.perlide.org/>

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE , THERE IS NO WARRANTY FOR THE SOFTWARE , TO THE EXTENT PERMITTED BY APPLICABLE LAW . EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE " AS IS " WITHOUT WARRANTY OF ANY KIND , EITHER EXPRESSED OR IMPLIED , INCLUDING , BUT NOT LIMITED TO , THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE . THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU . SHOULD THE SOFTWARE PROVE DEFECTIVE , YOU ASSUME THE COST OF ALL NECESSARY SERVICING , REPAIR , OR CORRECTION .

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER , OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE , BE LIABLE TO YOU FOR DAMAGES , INCLUDING ANY GENERAL , SPECIAL , INCIDENTAL , OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE ( INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE ), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES .

ACKNOWLEDGEMENTS

The Padre development team
The developers of Padre in alphabetical order:

Aaron Trevena ( TEEJAY )

Ahmad Zawawi XXXX XXXX XXXXX ( AZAWAWI )

Adam Kennedy ( ADAMK ) <adamk AT cpan DOT org>

Breno G. de Oliveira ( GARU )

Brian Cassidy ( BRICAS )

Burak Guersoy ( BURAK ) <burak AT cpan DOT org>

Cezary Morga ( THEREK ) <cm AT therek DOT net>

Chris Dolan ( CHRISDOLAN )

Claudio Ramirez ( CLAUDIO ) <padre.claudio@apt−get.be>

Fayland Lam ( FAYLAND ) <fayland AT gmail DOT com>

Gabriel Vieira ( GABRIELMAD )

Gabor Szabo − XXXXX XXX ( SZABGAB ) <szabgab AT gmail DOT com>

Heiko Jansen ( HJANSEN ) <heiko_jansen AT web DOT de>

Jerome Quelin ( JQUELIN ) <jquelin AT cpan DOT org>

Kaare Rasmussen ( KAARE ) <kaare AT cpan DOT org>

Keedi Kim − XXX ( KEEDI )

Kenichi Ishigaki − XXXX ( ISHIGAKI ) <ishigaki AT cpan DOT org>

Mark Grimes <mgrimes AT cpan DOT org>

Max Maischein ( CORION )

Olivier Mengue ( DOLMEN )

Patrick Donelan ( PDONELAN ) <pat AT patspam DOT com>

PaweX Murias ( PMURIAS )

Petar Shangov ( PSHANGOV )

Ryan Niebur ( RSN ) <rsn AT cpan DOT org>

Sebastian Willing ( SEWI )

Steffen Mueller ( TSEE ) <smueller AT cpan DOT org>

Zeno Gantner

Translators
Arabic

Ahmad M. Zawawi − XXXX XXXX XXXXX ( AZAWAWI )

Chinese (Simplified)

Fayland Lam ( FAYLAND )

Chinese (Traditional)

BlueT − Matthew Lien − XXX ( BLUET ) <bluet AT cpan DOT org>

Chuanren Wu

Dutch

Dirk De Nijs (ddn123456)

English

Everyone on the team

French

Jerome Quelin ( JQUELIN )

Olivier Mengue ( DOLMEN )

German

Heiko Jansen ( HJANSEN )

Sebastian Willing ( SEWI )

Zeno Gantner

Hebrew

Omer Zak − XXXX XX

Shlomi Fish − XXXXX XXX ( SHLOMIF )

Amir E. Aharoni − XXXX X. XXXXXX

Hungarian

Gyoergy Pasztor ( GYU )

Italian

Simone Blandino ( SBLANDIN )

Japanese

Kenichi Ishigaki − XXXX ( ISHIGAKI )

Korean

Keedi Kim − XXX ( KEEDI )

Russian

Andrew Shitov

Polish

Cezary Morga ( THEREK )

Portuguese (Brazilian)

Breno G. de Oliveira ( GARU )

Spanish

Paco Alguacil (PacoLinux)

Enrique Nell ( ENELL )

Czech

Marcela MaXlaXova (mmaslano)

Norwegian

Kjetil Skotheim ( KJETIL )

Turkish

Burak Guersoy ( BURAK ) <burak AT cpan DOT org>

Thanks
Mattia Barbon for providing wxPerl. Part of the code was copied from his Wx::Demo application.

Herbert Breunung for letting me work on Kephra.

Octavian Rasnita for early testing and bug reports.

Tatsuhiko Miyagawa for consulting on our I18N and L10N support.

pdf