1
------------------------------------
2
Quick reference on Perl engine's API
3
------------------------------------
5
All the packages that form the perl interface to Aegisub are automatically
6
loaded, however none of their symbols are exported initially. If you want to
7
import them you can use the usual 'use' mechanism; if you call it without a
8
list of imports it will import more or less everything in your script's
9
package. Wether they are exported or not is indicated in the following
10
reference by <--EXPORTED--> (exported by default within a plain 'use'
11
statement) and <--EXPORTABLE--> (can be imported specifying them explicitely in
12
the 'use' statement) tags. Finally, <--NOT EXPORTABLE--> indicates symbols that
13
can't be exported through 'use'.
16
====================================
19
------------------------------------
30
Log levels, to be used with the 'log' function.
33
Flag to force logging through wxWidgets facilites.
35
------------------------------------
39
text_extents STYLE, TEXT
40
Computes the metric for a string of text, based on a specific style.
42
STYLE The style to use, as a string or ref to a style line.
43
TEXT Text for which to compute the metrics.
45
WIDTH The width of the text (if called in scalar context, only this is returned).
46
ASCENT The ascent, i.e. the distance from the baseline to the top of the letters.
47
DESCENT Descent, i.e. the distance from the baseline to the bottom.
48
EXTLEADING External leading, i.e. the distance between to lines of text.
53
These are shortcuts for 'log(LOG_FATAL, LIST)' to 'log(LOG_MESSAGE, LIST)'
60
Prints a log message inside the progress window, if LEVEL is less or equal
61
to the tracelevel set inside automation options. If called from outside a
62
callback (i.e. during script loading) prints through the wxWidgets logging
63
mechanism. 'log(LIST)' is equal to 'log(Aegisub::LOG_MESSAGE, LIST)'. The
64
short form is used whenever there are at least two arguments and the first
65
one cannot be read as an integer; it is always used when given only one
66
argument. This function is not exported by default (review man perlfunc to
70
LEVEL The debug level, may be one of the following (the descriptions are
72
0 Fatal error, for vital errors;
73
1 Error, for serious but not too much threatening errors;
74
2 Warning, for something that's apparently going wrong;
75
3 Hint, for indicating something peculiar is happening;
76
4 Debug, for debugging!
77
5 Trace, for really verbose debugging;
78
6 Message, always printed.
79
If you OR one of these values with the flag LOG_WX the log message will
80
be delivered though wxWidgets regardless of wether there is a progress
81
window displayed (you won't normally need this feature, though).
82
LIST List of arguments to print.
85
Prints a warning through the GUI log facilities (it is equivalent to
86
'log(Aegisub::LOG_WARNING, LIST)'). It is automatically hooked to the
87
global 'warn' function during script execution, thus it is not exported by
90
LIST List of arguments to print.
96
Similar to 'log', but with the LOG_WX flag implicitely set. This function
100
====================================
101
package Aegisub::PerlConsole
102
------------------------------------
103
This package contains the perl console, a debug tool not intended for normal
104
use by normal users (it's not even enabled in release builds). They are shown
105
here for completeness.
107
------------------------------------
112
Prints a list of arguments on the console, or on STDOUT if no console is
113
registered, a trailing \n is printed too.
115
LIST List of arguments to print.
117
register_console NAME, DESC
118
Registers an instance of the console, as a macro. You don't want to know
119
any more because in fact you'll never have to do with this. >:)
121
NAME Set the name for the macro. (optional)
122
DESC Set the macro's description. (optional)
125
====================================
126
package Aegisub::Progress
127
------------------------------------
128
This package provides an interface to the progress window automatically showed
129
during the execution of a feature. Its functions are somewhat different to
130
those available in lua because of clarity, however aliases are given.
132
------------------------------------
137
Sets the value of the progress bar. It accepts values comprised in [0, 1]
138
OR (1, 100] (for instance, a value of 0.86 is equivalent to a value of 86:
139
they both represent '86%'). You should really always use values in the
140
range [0, 1] if you don't wanna be mocked by your friends and relatives
141
(and normally they're more immediately computable).
143
VALUE The value for the progress bar.
146
Sets the description for the current task inside progress window (just
147
below the progress bar).
149
DESC The description for the current task.
152
Sets the title for the progress window (which is not actually the window's
153
title, but a flashier label below it). The default title is 'Executing ...'
154
(with the ellpsis possibly replaced by the feature's name).
156
TITLE The title to set.
159
Returns: A boolean indicating wether the cancel button on the progress
160
window where pressed in the near past.
165
Synonym for 'set_progress(VALUE)'.
168
Synonym for 'set_desc(DESC)',
171
Synonym for 'set_title(TITLE)'.
174
====================================
175
package Aegisub::Script
177
------------------------------------
181
register_macro NAME, DESC, PROC_SUB, VAL_SUB
182
Register a new macro.
184
NAME The name of the macro.
185
DESC A description for the macro.
186
PROC_SUB A ref to a subroutine to be used as the macro processing function
187
(see the callbacks section). Please, really use a reference and not
188
just the name of the sub, because of the script 'pacakging' described
190
VAL_SUB A ref to a subroutine to be used as the macro validation function
191
(see callbacks)(optional, if not defined will be considered as always true).
193
set_info NAME, DESC, AUTHOR, VERSION
194
You can set all of the script's info values with a call to this
195
function. (Otherwise you can set the corresponding predefined script
196
variables individually.)
197
Arguments: see the parts about script variables, anything is optional.
200
====================================
201
package Aegisub::Script::pxxxxxxxx
202
------------------------------------
203
Every script that's loaded gets its code evaluated inside a different package -
204
whose name is chosen at 'random' - whereas the perl interpreter is unique, so
205
all the scripts see the same global package, and can possibly access other
206
scripts' packages. Therefore is recommended to ALWAYS declare all of the
207
script's local variables with 'my', and of course to 'use strict' to check on
208
this. You can still declare another package for your script; the script's
209
predefined variables should be still visible from it without any change in the
210
code (they're declared as 'our'), however this is discouraged.
212
------------------------------------
216
Holds the script author's name. Default is the user executing aegisub.
219
Holds a description for the script. Default is 'Perl script'.
222
Holds the script's name. Default is the script's filename.
225
Holds the script's version. Default is current aegisub version.
228
The full path to the script's file. Any change to this variable is ignored
232
The full script package as a string. Any change to this variable is
233
currently ignored and overwritten, and may be so forever.
236
------------------------------------
239
macro_processing_function LINES, SELECTED, ACTIVE
240
A function to be used as a callback for Aegisub::Script::register_macro().
241
This function will be called when the user selects the corresponding macro
242
in the Automation menu. The first two arguments can be modified, and the
243
modifications will be reflected in the subtitles file.
245
LINES A reference to the list containing the subtitle file lines.
246
Each element of the list is a reference to a hash that represents a
247
single subtitle line. For the hash keys refer to lua documentation,
248
they are basically the same.
251
my $lines = $_[0]; # DON'T shift @_ (unless you reconstruct it
252
# afterwards) or you'll break everything and
253
# your hard disk be erased >:)
254
# The first selected line's index
255
my $first = $_[1][0];
257
my $l = $lines->[$first];
258
# The text field of a dialogue line
259
my $text = $lines->[$first]->{"text"};
261
SELECTED A ref to an array of ints, showing the currently selected
263
ACTIVE Index of the currently active line in the subtitle file (sic).
265
macro_validation_function LINES, SELECTED, ACTIVE
266
A function to be used as a callback for Aegisub::Script::register_macro().
267
This function will be called whenever the Automation menu is opened to
268
decide what macros are applicable to the current script.
269
Arguments: same as macro_processing_function; however any change to the
270
first two ones will be ignored upon function return.
272
VALID A 'boolean' value to indicate if the macro is applicable to this
273
particular subtitles file.
added
removed
automation/v4-docs/perl-api.txt
