Padre::Document(3) User Contributed Perl Documentation Padre::Document(3)NAMEPadre::Document - Padre Document API
DESCRIPTION
The Padre::Document class provides a base class, default implementation
and API documentation for document type support in Padre.
As an API, it allows Padre developers and plug-in authors to implement
extended support for various document types in Padre, while ensuring
that a naive default document implementation exists that allows Padre
to provide basic support (syntax highlighting mainly) for many document
types without the need to install extra modules unless you need the
extra functionality.
Document Type Registration
Padre uses MIME types as the fundamental identifier when working with
documents. Files are typed at load-time based on file extension (with a
simple heuristic fallback when opening files with no extension).
Many of the MIME types are unofficial X-style identifiers, but in cases
without an official type, Padre will try to use the most popular
identifier (based on research into the various language communities).
Each supported mime has a mapping to a Scintilla lexer (for syntax
highlighting), and an optional mapping to the class that provides
enhanced support for that document type.
Plug-ins that implement support for a document type provide a
"registered_documents" method that the plug-in manager will call as
needed.
Plug-in authors should not load the document classes in advance, they
will be automatically loaded by Padre as needed.
Padre does not currently support opening non-text files.
File to MIME type mapping
Padre has a built-in hash mapping the file extensions to MIME types.
In certain cases (.t, .pl, .pm) Padre also looks in the content of the
file to determine if the file is Perl 5 or Perl 6.
MIME types are mapped to lexers that provide the syntax highlighting.
MIME types are also mapped to modules that implement special features
needed by that kind of a file type.
Plug-ins can add further mappings.
Plan
Padre has a built-in mapping of file extension to either a single MIME
type or function name. In order to determine the actual MIME type Padre
checks this hash. If the key is a subroutine it is called and it should
return the MIME type of the file.
The user has a way in the GUI to add more file extensions and map them
to existing MIME types or functions. It is probably better to have a
commonly used name along with the MIME type in that GUI instead of the
MIME type only.
I wonder if we should allow the users (and or plug-in authors) to
change the functions or to add new functions that will map file content
to MIME type or if we should just tell them to patch Padre. What if
they need it for some internal project?
A plug-in is able to add new supported MIME types. Padre should either
check for collisions if a plug-in wants to provide an already supported
MIME type or should allow multiple support modules with a way to select
the current one. (Again I think we probably don't need this. People can
just come and add the MIME types to Padre core.) (not yet implemented)
A plug-in can register zero or more modules that implement special
features needed by certain MIME types. Every MIME type can have only
one module that implements its features. Padre is checking if a MIME
type already has a registered module and does not let to replace it.
(Special features such as commenting out a few lines at once, auto-
completion or refactoring tools).
Padre should check if the given MIME type is one that is in the
supported MIME type list. (TO DO)
Each MIME type is mapped to one or more lexers that provide the syntax
highlighting. Every MIME type has to be mapped to at least one lexer
but it can be mapped to several lexers as well. The user is able to
select the lexer for each MIME type. (For this each lexer should have
a reasonable name too.) (TO DO)
Every plug-in should be able to add a list of lexers to the existing
MIME types regardless if the plug-in also provides the class that
implements the features of that MIME type. By default Padre supports
the built-in syntax highlighting of Scintilla. Perl 5 currently has
two PPI based syntax highlighter, Perl 6 can use the STD.pm or
Rakudo/PGE for syntax highlighting but there are two plug-ins aXX
Parrot and Kate aXX that can provide syntax highlighting to a wide
range of MIME types.
"provided_highlighters()" returns a list of arrays like this:
['Module with a colorize function' => 'Human readable Name' => 'Long description']
"highlighting_mime_types()" returns a hash where the keys are module
names listed in "provided_highlighters", the values are array
references to MIME types:
'Module::A' => [ mime-type-1, mime-type-2]
The user can change the MIME type mapping of individual files and Padre
should remember this choice and allow the user to change it to another
specific MIME type or to set it to "Default by extension".
METHODS
"new"
my $doc = Padre::Document->new(
filename => $file,
);
$file is optional and if given it will be loaded in the document. MIME
type is defined by the "guess_mimetype" function.
"error"
$document->error( $msg );
Open an error dialog box with $msg as main text. There's only one OK
button. No return value.
"load_file"
$doc->load_file;
Loads the current file.
Sets the Encoding bit using Encode::Guess and tries to figure out what
kind of newlines are in the file. Defaults to "utf-8" if it could not
figure out the encoding.
Returns true on success false on failure. Sets "$doc->errstr".
"autocomplete_matching_char"
The first argument needs to be a reference to the editor this method
should work on.
The second argument is expected to be a event reference to the event
object which is the reason why the method was launched.
This method expects a hash as the third argument. If the last key typed
by the user is a key in this hash, the value is automatically added and
the cursor is set between key and value. Both key and value are
expected to be ASCII codes.
Usually used for brackets and text signs like:
$self->autocomplete_matching_char(
$editor,
$event,
39 => 39, # ' '
40 => 41, # ( )
);
Returns 1 if something was added or 0 otherwise (if anybody cares about
this).
"write"
Writes the document to an arbitrary local file using the same semantics
as when we do a full file save.
"reload"
Reload the current file discarding changes in the editor.
Returns true on success false on failure. Error message will be in
"$doc->errstr".
TO DO: In the future it should backup the changes in case the user
regrets the action.
"set_indentation_style"
Given a hash reference with the keys "use_tabs", "tabwidth", and
"indentwidth", set the document's editor's indentation style.
Without an argument, falls back to what "get_indentation_style"
returns.
"get_indentation_level_string"
Calculates the string that should be used to indent a given number of
levels for this document.
Takes the indentation level as an integer argument which defaults to
one. Note that indenting to level 2 may be different from just
concatenating the indentation string to level one twice due to tab
compression.
"event_on_char"
NOT IMPLEMENTED IN THE BASE CLASS
This method - if implemented - is called after any addition of a
character to the current document. This enables document classes to aid
the user in the editing process in various ways, e.g. by auto-pairing
of brackets or by suggesting usable method names when method-call
syntax is detected.
Parameters retrieved are the objects for the document, the editor, and
the wxWidgets event.
Returns nothing.
Cf. "Padre::Document::Perl" for an example.
"event_on_right_down"
NOT IMPLEMENTED IN THE BASE CLASS
This method - if implemented - is called when a user right-clicks in an
editor to open a context menu and after the standard context menu was
created and populated in the "Padre::Wx::Editor" class. By
manipulating the menu document classes may provide the user with
additional options.
Parameters retrieved are the objects for the document, the editor, the
context menu ("Wx::Menu") and the event.
Returns nothing.
"event_on_left_up"
NOT IMPLEMENTED IN THE BASE CLASS
This method - if implemented - is called when a user left-clicks in an
editor. This can be used to implement context-sensitive actions if the
user presses modifier keys while clicking.
Parameters retrieved are the objects for the document, the editor, and
the event.
Returns nothing.
"guess_indentation_style"
Automatically infer the indentation style of the document using
Text::FindIndent.
Returns a hash reference containing the keys "use_tabs", "tabwidth",
and "indentwidth". It is suitable for passing to
"set_indendentation_style".
"guess_filename"
my $name = $document->guess_filename
When creating new code, one job that the editor should really be able
to do for you without needing to be told is to work out where to save
the file.
When called on a new unsaved file, this method attempts to guess what
the name of the file should be based purely on the content of the file.
In the base implementation, this returns "undef" to indicate that the
method cannot make a reasonable guess at the name of the file.
Your MIME type specific document subclass should implement any file
name detection as it sees fit, returning the file name as a string.
"guess_subpath"
my $subpath = $document->guess_subpath;
When called on a new unsaved file, this method attempts to guess what
the sub-path of the file should be inside of the current project, based
purely on the content of the file.
In the base implementation, this returns a null list to indicate that
the method cannot make a reasonable guess at the name of the file.
Your MIME type specific document subclass should implement any file
name detection as it sees fit, returning the project-rooted sub-path as
a list of directory names.
These directory names do not need to exist, they only represent intent.
perl v5.14.1 2011-06-18 Padre::Document(3)
