1Padre::Document(3) User Contributed Perl Documentation Padre::Document(3)
2
6 Padre::Document - Padre Document API
7
9 The Padre::Document class provides a base class, default implementation
10 and API documentation for document type support in Padre.
11 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 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 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 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 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 Plug-in authors should not load the document classes in advance, they
37 will be automatically loaded by Padre as needed.
38 Padre does not currently support opening non-text files.
40 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 MIME types are mapped to lexers that provide the syntax highlighting.
47 MIME types are also mapped to modules that implement special features
49 needed by that kind of a file type.
50 Plug-ins can add further mappings.
52 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 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 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 A plug-in is able to add new supported MIME types. Padre should either
70 check for collisions if a plug-in already wants to provide an already
71 supported MIME type or should allow multiple support modules with a way
72 to select the current one. (Again I think we probably don't need this.
73 People can just come and add the MIME types to Padre core.) (not yet
74 implemented)
75 A plug-in can register zero or more modules that implement special
77 features needed by certain MIME types. Every MIME type can have only
78 one module that implements its features. Padre is checking if a MIME
79 type already has a registered module and does not let to replace it.
80 (Special features such as commenting out a few lines at once, auto-
81 completion or refactoring tools).
82 Padre should check if the given MIME type is one that is in the
84 supported MIME type list. (TO DO)
85 Each MIME type is mapped to one or more lexers that provide the syntax
87 highlighting. Every MIME type has to be mapped to at least one lexer
88 but it can be mapped to several lexers as well. The user is able to
89 select the lexer for each MIME type. (For this each lexer should have
90 a reasonable name too.) (TO DO)
91 Every plug-in should be able to add a list of lexers to the existing
93 MIME types regardless if the plug-in also provides the class that
94 implements the features of that MIME type. By default Padre supports
95 the built-in syntax highlighting of Scintilla. Perl 5 currently has
96 two PPI based syntax highlighter, Perl 6 can use the STD.pm or
97 Rakudo/PGE for syntax highlighting but there are two plug-ins aXX
98 Parrot and Kate aXX that can provide syntax highlighting to a wide
99 range of MIME types.
100 "provided_highlighters()" returns a list of arrays like this:
102 ['Module with a colorize function' => 'Human readable Name' => 'Long description']
104 "highlighting_mime_types()" returns a hash where the keys are module
106 names listed in "provided_highlighters", the values are array
107 references to MIME types:
108 'Module::A' => [ mime-type-1, mime-type-2]
110 The user can change the MIME type mapping of individual files and Padre
112 should remember this choice and allow the user to change it to another
113 specific MIME type or to set it to "Default by extension".
114
116 "new"
117 my $doc = Padre::Document->new(
118 filename => $file,
119 );
120 $file is optional and if given it will be loaded in the document. MIME
122 type is defined by the "guess_mimetype" function.
123 "error"
125 $document->error( $msg );
126 Open an error dialog box with $msg as main text. There's only one OK
128 button. No return value.
129 "load_file"
131 $doc->load_file;
132 Loads the current file.
134 Sets the Encoding bit using Encode::Guess and tries to figure out what
136 kind of newlines are in the file. Defaults to "utf-8" if it could not
137 figure out the encoding.
138 Returns true on success false on failure. Sets "$doc->errstr".
140 "autocomplete_matching_char"
142 The first argument needs to be a reference to the editor this method
143 should work on.
144 The second argument is expected to be a event reference to the event
146 object which is the reason why the method was launched.
147 This method expects a hash as the third argument. If the last key typed
149 by the user is a key in this hash, the value is automatically added and
150 the cursor is set between key and value. Both key and value are
151 expected to be ASCII codes.
152 Usually used for brackets and text signs like:
154 $self->autocomplete_matching_char(
156 $editor,
157 $event,
158 39 => 39, # ' '
159 40 => 41, # ( )
160 );
161 Returns 1 if something was added or 0 otherwise (if anybody cares about
163 this).
164 "write"
166 Writes the document to an arbitrary local file using the same semantics
167 as when we do a full file save.
168 "reload"
170 Reload the current file discarding changes in the editor.
171 Returns true on success false on failure. Error message will be in
173 "$doc->errstr".
174 TO DO: In the future it should backup the changes in case the user
176 regrets the action.
177 "set_indentation_style"
179 Given a hash reference with the keys "use_tabs", "tabwidth", and
180 "indentwidth", set the document's editor's indentation style.
181 Without an argument, falls back to what "get_indentation_style"
183 returns.
184 "get_indentation_level_string"
186 Calculates the string that should be used to indent a given number of
187 levels for this document.
188 Takes the indentation level as an integer argument which defaults to
190 one. Note that indenting to level 2 may be different from just
191 concatenating the indentation string to level one twice due to tab
192 compression.
193 "event_on_char"
195 NOT IMPLEMENTED IN THE BASE CLASS
196 This method - if implemented - is called after any addition of a
198 character to the current document. This enables document classes to aid
199 the user in the editing process in various ways, e.g. by auto-pairing
200 of brackets or by suggesting usable method names when method-call
201 syntax is detected.
202 Parameters retrieved are the objects for the document, the editor, and
204 the wxWidgets event.
205 Returns nothing.
207 Cf. "Padre::Document::Perl" for an example.
209 "event_on_right_down"
211 NOT IMPLEMENTED IN THE BASE CLASS
212 This method - if implemented - is called when a user right-clicks in an
214 editor to open a context menu and after the standard context menu was
215 created and populated in the "Padre::Wx::Editor" class. By
216 manipulating the menu document classes may provide the user with
217 additional options.
218 Parameters retrieved are the objects for the document, the editor, the
220 context menu ("Wx::Menu") and the event.
221 Returns nothing.
223 "event_on_left_up"
225 NOT IMPLEMENTED IN THE BASE CLASS
226 This method - if implemented - is called when a user left-clicks in an
228 editor. This can be used to implement context-sensitive actions if the
229 user presses modifier keys while clicking.
230 Parameters retrieved are the objects for the document, the editor, and
232 the event.
233 Returns nothing.
235 "guess_indentation_style"
237 Automatically infer the indentation style of the document using
238 Text::FindIndent.
239 Returns a hash reference containing the keys "use_tabs", "tabwidth",
241 and "indentwidth". It is suitable for passing to
242 "set_indendentation_style".
243 "guess_filename"
245 my $name = $document->guess_filename
246 When creating new code, one job that the editor should really be able
248 to do for you without needing to be told is to work out where to save
249 the file.
250 When called on a new unsaved file, this method attempts to guess what
252 the name of the file should be based purely on the content of the file.
253 In the base implementation, this returns "undef" to indicate that the
255 method cannot make a reasonable guess at the name of the file.
256 Your MIME type specific document subclass should implement any file
258 name detection as it sees fit, returning the file name as a string.
259 "guess_subpath"
261 my $subpath = $document->guess_subpath;
262 When called on a new unsaved file, this method attempts to guess what
264 the sub-path of the file should be inside of the current project, based
265 purely on the content of the file.
266 In the base implementation, this returns a null list to indicate that
268 the method cannot make a reasonable guess at the name of the file.
269 Your MIME type specific document subclass should implement any file
271 name detection as it sees fit, returning the project-rooted sub-path as
272 a list of directory names.
273 These directory names do not need to exist, they only represent intent.
275 "check_syntax"
277 NOT IMPLEMENTED IN THE BASE CLASS
278 See also: "check_syntax_in_background"!
280 By default, this method will only check the syntax if the document has
282 changed since the last check. Specify the "force => 1" parameter to
283 override this.
284 An implementation in a derived class needs to return an array reference
286 of syntax problems.
287 Each entry in the array has to be an anonymous hash with the following
289 keys:
290 · "line"
292 The line where the problem resides
294 · "msg"
296 A short description of the problem
298 · "severity"
300 A flag indicating the problem class: Either 'W' (warning) or 'E'
302 (error)
303 · "desc"
305 A longer description with more information on the error (currently
307 not used but intended to be)
308 Returns an empty array reference if no problems can be found.
310 Returns "undef" if nothing has changed since the last invocation.
312 Must return the problem list even if nothing has changed when a
314 parameter is present which evaluates to true.
315 "check_syntax_in_background"
317 NOT IMPLEMENTED IN THE BASE CLASS
318 Checking the syntax of documents can take a long time. Therefore, this
320 method essentially works the same as "check_syntax", but works its
321 magic in a background task instead. That means it cannot return the
322 syntax-check structure but instead optionally calls a callback you pass
323 in as the "on_finish" parameter.
324 If you don't specify that parameter, the default syntax-check-pane
326 updating code will be run after finishing the check. If you do specify
327 a callback, the first parameter will be the task object. You can run
328 the default updating code by executing the "update_gui()" method of the
329 task object.
330 By default, this method will only check the syntax if the document has
332 changed since the last check. Specify the "force => 1" parameter to
333 override this.
334perl v5.12.1 2010-06-11 Padre::Document(3)