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.

File to MIME-type mapping

Padre has a built-in hash mapping the file exetensions 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 funtions. 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 plugin 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 plugin is able to add new supported mime-types. Padre should either check for collisions if a plugin already wants to provide an already suported 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.)

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

The mime-types are also mapped to modules that implement special features needed by that kind of file.

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

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.