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 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 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 Padre should check if the given MIME type is one that is in the
83 supported MIME type list. (TO DO)
84 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 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 "provided_highlighters()" returns a list of arrays like this:
101 ['Module with a colorize function' => 'Human readable Name' => 'Long description']
103 "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 'Module::A' => [ mime-type-1, mime-type-2]
109 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
115 "new"
116 my $doc = Padre::Document->new(
117 filename => $file,
118 );
119 $file is optional and if given it will be loaded in the document. MIME
121 type is defined by the "guess_mimetype" function.
122 "error"
124 $document->error( $msg );
125 Open an error dialog box with $msg as main text. There's only one OK
127 button. No return value.
128 "load_file"
130 $doc->load_file;
131 Loads the current file.
133 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 Returns true on success false on failure. Sets "$doc->errstr".
139 "autocomplete_matching_char"
141 The first argument needs to be a reference to the editor this method
142 should work on.
143 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 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 Usually used for brackets and text signs like:
153 $self->autocomplete_matching_char(
155 $editor,
156 $event,
157 39 => 39, # ' '
158 40 => 41, # ( )
159 );
160 Returns 1 if something was added or 0 otherwise (if anybody cares about
162 this).
163 "write"
165 Writes the document to an arbitrary local file using the same semantics
166 as when we do a full file save.
167 "reload"
169 Reload the current file discarding changes in the editor.
170 Returns true on success false on failure. Error message will be in
172 "$doc->errstr".
173 TO DO: In the future it should backup the changes in case the user
175 regrets the action.
176 "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 Without an argument, falls back to what "get_indentation_style"
182 returns.
183 "get_indentation_level_string"
185 Calculates the string that should be used to indent a given number of
186 levels for this document.
187 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 "event_on_char"
194 NOT IMPLEMENTED IN THE BASE CLASS
195 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 Parameters retrieved are the objects for the document, the editor, and
203 the wxWidgets event.
204 Returns nothing.
206 Cf. "Padre::Document::Perl" for an example.
208 "event_on_right_down"
210 NOT IMPLEMENTED IN THE BASE CLASS
211 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 Parameters retrieved are the objects for the document, the editor, the
219 context menu ("Wx::Menu") and the event.
220 Returns nothing.
222 "event_on_left_up"
224 NOT IMPLEMENTED IN THE BASE CLASS
225 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 Parameters retrieved are the objects for the document, the editor, and
231 the event.
232 Returns nothing.
234 "guess_indentation_style"
236 Automatically infer the indentation style of the document using
237 Text::FindIndent.
238 Returns a hash reference containing the keys "use_tabs", "tabwidth",
240 and "indentwidth". It is suitable for passing to
241 "set_indendentation_style".
242 "guess_filename"
244 my $name = $document->guess_filename
245 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 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 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 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 "guess_subpath"
260 my $subpath = $document->guess_subpath;
261 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 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 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 These directory names do not need to exist, they only represent intent.
274
276 Hey! The above document had some coding errors, which are explained
277 below:
278 Around line 103:
280 Non-ASCII character seen before =encoding in '–'. Assuming UTF-8
281perl v5.32.1 2021-01-27 Padre::Document(3)