1Padre::Document(3)    User Contributed Perl Documentation   Padre::Document(3)
2
3
4

NAME

6       Padre::Document - Padre Document API
7

DESCRIPTION

9       The Padre::Document class provides a base class, default implementation
10       and API documentation for document type support in Padre.
11
12       As an API, it allows Padre developers and plug-in authors to implement
13       extended support for various document types in Padre, while ensuring
14       that a naive default document implementation exists that allows Padre
15       to provide basic support (syntax highlighting mainly) for many document
16       types without the need to install extra modules unless you need the
17       extra functionality.
18
19   Document Type Registration
20       Padre uses MIME types as the fundamental identifier when working with
21       documents. Files are typed at load-time based on file extension (with a
22       simple heuristic fallback when opening files with no extension).
23
24       Many of the MIME types are unofficial X-style identifiers, but in cases
25       without an official type, Padre will try to use the most popular
26       identifier (based on research into the various language communities).
27
28       Each supported mime has a mapping to a Scintilla lexer (for syntax
29       highlighting), and an optional mapping to the class that provides
30       enhanced support for that document type.
31
32       Plug-ins that implement support for a document type provide a
33       "registered_documents" method that the plug-in manager will call as
34       needed.
35
36       Plug-in authors should not load the document classes in advance, they
37       will be automatically loaded by Padre as needed.
38
39       Padre does not currently support opening non-text files.
40
41   File to MIME type mapping
42       Padre has a built-in hash mapping the file extensions to MIME types.
43       In certain cases (.t, .pl, .pm) Padre also looks in the content of the
44       file to determine if the file is Perl 5 or Perl 6.
45
46       MIME types are mapped to lexers that provide the syntax highlighting.
47
48       MIME types are also mapped to modules that implement special features
49       needed by that kind of a file type.
50
51       Plug-ins can add further mappings.
52
53   Plan
54       Padre has a built-in mapping of file extension to either a single MIME
55       type or function name. In order to determine the actual MIME type Padre
56       checks this hash. If the key is a subroutine it is called and it should
57       return the MIME type of the file.
58
59       The user has a way in the GUI to add more file extensions and map them
60       to existing MIME types or functions. It is probably better to have a
61       commonly used name along with the MIME type in that GUI instead of the
62       MIME type only.
63
64       I wonder if we should allow the users (and or plug-in authors) to
65       change the functions or to add new functions that will map file content
66       to MIME type or if we should just tell them to patch Padre. What if
67       they need it for some internal project?
68
69       A plug-in is able to add new supported MIME types. Padre should either
70       check for collisions if a plug-in wants to provide an already supported
71       MIME type or should allow multiple support modules with a way to select
72       the current one. (Again I think we probably don't need this. People can
73       just come and add the MIME types to Padre core.) (not yet implemented)
74
75       A plug-in can register zero or more modules that implement special
76       features needed by certain MIME types. Every MIME type can have only
77       one module that implements its features. Padre is checking if a MIME
78       type already has a registered module and does not let to replace it.
79       (Special features such as commenting out a few lines at once, auto-
80       completion or refactoring tools).
81
82       Padre should check if the given MIME type is one that is in the
83       supported MIME type list. (TO DO)
84
85       Each MIME type is mapped to one or more lexers that provide the syntax
86       highlighting. Every MIME type has to be mapped to at least one lexer
87       but it can be mapped to several lexers as well.  The user is able to
88       select the lexer for each MIME type.  (For this each lexer should have
89       a reasonable name too.) (TO DO)
90
91       Every plug-in should be able to add a list of lexers to the existing
92       MIME types regardless if the plug-in also provides the class that
93       implements the features of that MIME type. By default Padre supports
94       the built-in syntax highlighting of Scintilla.  Perl 5 currently has
95       two PPI based syntax highlighter, Perl 6 can use the STD.pm or
96       Rakudo/PGE for syntax highlighting but there are two plug-ins – Parrot
97       and Kate – that can provide syntax highlighting to a wide range of MIME
98       types.
99
100       "provided_highlighters()" returns a list of arrays like this:
101
102           ['Module with a colorize function' => 'Human readable Name' => 'Long description']
103
104       "highlighting_mime_types()" returns a hash where the keys are module
105       names listed in "provided_highlighters", the values are array
106       references to MIME types:
107
108           'Module::A' => [ mime-type-1, mime-type-2]
109
110       The user can change the MIME type mapping of individual files and Padre
111       should remember this choice and allow the user to change it to another
112       specific MIME type or to set it to "Default by extension".
113

METHODS

115   "new"
116         my $doc = Padre::Document->new(
117             filename => $file,
118         );
119
120       $file is optional and if given it will be loaded in the document.  MIME
121       type is defined by the "guess_mimetype" function.
122
123   "error"
124           $document->error( $msg );
125
126       Open an error dialog box with $msg as main text. There's only one OK
127       button. No return value.
128
129   "load_file"
130        $doc->load_file;
131
132       Loads the current file.
133
134       Sets the Encoding bit using Encode::Guess and tries to figure out what
135       kind of newlines are in the file. Defaults to "utf-8" if it could not
136       figure out the encoding.
137
138       Returns true on success false on failure. Sets "$doc->errstr".
139
140   "autocomplete_matching_char"
141       The first argument needs to be a reference to the editor this method
142       should work on.
143
144       The second argument is expected to be a event reference to the event
145       object which is the reason why the method was launched.
146
147       This method expects a hash as the third argument. If the last key typed
148       by the user is a key in this hash, the value is automatically added and
149       the cursor is set between key and value. Both key and value are
150       expected to be ASCII codes.
151
152       Usually used for brackets and text signs like:
153
154         $self->autocomplete_matching_char(
155             $editor,
156             $event,
157             39  => 39,  # ' '
158             40  => 41,  # ( )
159         );
160
161       Returns 1 if something was added or 0 otherwise (if anybody cares about
162       this).
163
164   "write"
165       Writes the document to an arbitrary local file using the same semantics
166       as when we do a full file save.
167
168   "reload"
169       Reload the current file discarding changes in the editor.
170
171       Returns true on success false on failure. Error message will be in
172       "$doc->errstr".
173
174       TO DO: In the future it should backup the changes in case the user
175       regrets the action.
176
177   "set_indentation_style"
178       Given a hash reference with the keys "use_tabs", "tabwidth", and
179       "indentwidth", set the document's editor's indentation style.
180
181       Without an argument, falls back to what "get_indentation_style"
182       returns.
183
184   "get_indentation_level_string"
185       Calculates the string that should be used to indent a given number of
186       levels for this document.
187
188       Takes the indentation level as an integer argument which defaults to
189       one. Note that indenting to level 2 may be different from just
190       concatenating the indentation string to level one twice due to tab
191       compression.
192
193   "event_on_char"
194       NOT IMPLEMENTED IN THE BASE CLASS
195
196       This method - if implemented - is called after any addition of a
197       character to the current document. This enables document classes to aid
198       the user in the editing process in various ways, e.g. by auto-pairing
199       of brackets or by suggesting usable method names when method-call
200       syntax is detected.
201
202       Parameters retrieved are the objects for the document, the editor, and
203       the wxWidgets event.
204
205       Returns nothing.
206
207       Cf. "Padre::Document::Perl" for an example.
208
209   "event_on_right_down"
210       NOT IMPLEMENTED IN THE BASE CLASS
211
212       This method - if implemented - is called when a user right-clicks in an
213       editor to open a context menu and after the standard context menu was
214       created and populated in the "Padre::Wx::Editor" class.  By
215       manipulating the menu document classes may provide the user with
216       additional options.
217
218       Parameters retrieved are the objects for the document, the editor, the
219       context menu ("Wx::Menu") and the event.
220
221       Returns nothing.
222
223   "event_on_left_up"
224       NOT IMPLEMENTED IN THE BASE CLASS
225
226       This method - if implemented - is called when a user left-clicks in an
227       editor. This can be used to implement context-sensitive actions if the
228       user presses modifier keys while clicking.
229
230       Parameters retrieved are the objects for the document, the editor, and
231       the event.
232
233       Returns nothing.
234
235   "guess_indentation_style"
236       Automatically infer the indentation style of the document using
237       Text::FindIndent.
238
239       Returns a hash reference containing the keys "use_tabs", "tabwidth",
240       and "indentwidth". It is suitable for passing to
241       "set_indendentation_style".
242
243   "guess_filename"
244         my $name = $document->guess_filename
245
246       When creating new code, one job that the editor should really be able
247       to do for you without needing to be told is to work out where to save
248       the file.
249
250       When called on a new unsaved file, this method attempts to guess what
251       the name of the file should be based purely on the content of the file.
252
253       In the base implementation, this returns "undef" to indicate that the
254       method cannot make a reasonable guess at the name of the file.
255
256       Your MIME type specific document subclass should implement any file
257       name detection as it sees fit, returning the file name as a string.
258
259   "guess_subpath"
260         my $subpath = $document->guess_subpath;
261
262       When called on a new unsaved file, this method attempts to guess what
263       the sub-path of the file should be inside of the current project, based
264       purely on the content of the file.
265
266       In the base implementation, this returns a null list to indicate that
267       the method cannot make a reasonable guess at the name of the file.
268
269       Your MIME type specific document subclass should implement any file
270       name detection as it sees fit, returning the project-rooted sub-path as
271       a list of directory names.
272
273       These directory names do not need to exist, they only represent intent.
274

POD ERRORS

276       Hey! The above document had some coding errors, which are explained
277       below:
278
279       Around line 103:
280           Non-ASCII character seen before =encoding in '–'. Assuming UTF-8
281
282
283
284perl v5.32.1                      2021-01-27                Padre::Document(3)
Impressum