The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Padre-0.33
River stage two • 56 direct dependents • 56 total dependents
40 ++
/ Padre::Document

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 plugin 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.

Plugins that implement support for a document type provide a registered_documents method that the PluginManager will call as needed.

Plugin 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.

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

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 could not figure out the encoding.

Currently it autoconverts files with mixed newlines. TODO we should stop autoconverting.

Returns true on success false on failure. Sets $doc->errstr;

reload

Reload the current file discarding changes in the editor.

Returns true on success false on failure. Error message will be in $doc->errstr;

TODO: 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.

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.

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.

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 arrayref 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 arrayref 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 param 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.