NAME

Padre::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 already 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 – Parrot and Kate – 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.

check_syntax

NOT IMPLEMENTED IN THE BASE CLASS

See also: check_syntax_in_background!

By default, this method will only check the syntax if the document has changed since the last check. Specify the force => 1 parameter to override this.

An implementation in a derived class needs to return an array reference of syntax problems.

Each entry in the array has to be an anonymous hash with the following keys:

• line

  The line where the problem resides

• msg

  A short description of the problem

• severity

  A flag indicating the problem class: Either 'W' (warning) or 'E' (error)

• desc

  A longer description with more information on the error (currently not used but intended to be)

Returns an empty array reference if no problems can be found.

Returns undef if nothing has changed since the last invocation.

Must return the problem list even if nothing has changed when a parameter is present which evaluates to true.

check_syntax_in_background

NOT IMPLEMENTED IN THE BASE CLASS

Checking the syntax of documents can take a long time. Therefore, this method essentially works the same as check_syntax, but works its magic in a background task instead. That means it cannot return the syntax-check structure but instead optionally calls a callback you pass in as the on_finish parameter.

If you don't specify that parameter, the default syntax-check-pane updating code will be run after finishing the check. If you do specify a callback, the first parameter will be the task object. You can run the default updating code by executing the update_gui() method of the task object.

By default, this method will only check the syntax if the document has changed since the last check. Specify the force => 1 parameter to override this.

cpanm Padre

perl -MCPAN -e shell
install Padre