Aegisub/automation/v4-docs/perl-api.txt
shb 8e7f84c818 Fixed perl-api.txt further.
Originally committed to SVN as r1860.
2008-02-09 17:18:28 +00:00

273 lines
9.9 KiB
Text

------------------------------------
Quick reference on Perl engine's API
------------------------------------
All the packages that form the perl interface to Aegisub are automatically
loaded, however none of their symbols are exported initially. If you want to
import them you can use the usual 'use' mechanism; if you call it without a
list of imports it will import more or less everything in your script's
package. Wether they are exported or not is indicated in the following
reference by <--EXPORTED--> (exported by default within a plain 'use'
statement) and <--EXPORTABLE--> (can be imported specifying them explicitely in
the 'use' statement) tags. Finally, <--NOT EXPORTABLE--> indicates symbols that
can't be exported through 'use'.
====================================
package Aegisub
------------------------------------
Constants defined:
<--EXPORTABLE-->
LOG_FATAL == 0
LOG_ERROR == 1
LOG_WARNING == 2
LOG_HINT == 3
LOG_DEBUG == 4
LOG_TRACE == 5
LOG_MESSAGE == 6
Log levels, to be used with the 'log' function.
LOG_WX == 8
Flag to force logging through wxWidgets facilites.
------------------------------------
Subroutines defined:
<--EXPORTED-->
text_extents STYLE, TEXT
Computes the metric for a string of text, based on a specific style.
Arguments:
STYLE The style to use, as a string or ref to a style line.
TEXT Text for which to compute the metrics.
Returns:
WIDTH The width of the text (if called in scalar context, only this is returned).
ASCENT The ascent, i.e. the distance from the baseline to the top of the letters.
DESCENT Descent, i.e. the distance from the baseline to the bottom.
EXTLEADING External leading, i.e. the distance between to lines of text.
log_fatal LIST
...
log_message LIST
These are shortcuts for 'log(LOG_FATAL, LIST)' to 'log(LOG_MESSAGE, LIST)'
(see below).
<--EXPORTABLE-->
log LEVEL, LIST
log LIST
Prints a log message inside the progress window, if LEVEL is less or equal
to the tracelevel set inside automation options. If called from outside a
callback (i.e. during script loading) prints through the wxWidgets logging
mechanism. 'log(LIST)' is equal to 'log(Aegisub::LOG_MESSAGE, LIST)'. The
short form is used whenever there are at least two arguments and the first
one cannot be read as an integer; it is always used when given only one
argument. This function is not exported by default (review man perlfunc to
understand why :).
Arguments:
LEVEL The debug level, may be one of the following (the descriptions are
indicative):
0 Fatal error, for vital errors;
1 Error, for serious but not too much threatening errors;
2 Warning, for something that's apparently going wrong;
3 Hint, for indicating something peculiar is happening;
4 Debug, for debugging!
5 Trace, for really verbose debugging;
6 Message, always printed.
If you OR one of these values with the flag LOG_WX the log message will
be delivered though wxWidgets regardless of wether there is a progress
window displayed (you won't normally need this feature, though).
LIST List of arguments to print.
warn LIST
Prints a warning through the GUI log facilities (it is equivalent to
'log(Aegisub::LOG_WARNING, LIST)'). It is automatically hooked to the
global 'warn' function during script execution, thus it is not exported by
default.
Arguments:
LIST List of arguments to print.
<--NOT EXPORTABLE-->
wxlog LEVEL, LIST
wxlog LIST
Similar to 'log', but with the LOG_WX flag implicitely set. This function
is top-secret.
====================================
package Aegisub::PerlConsole
------------------------------------
This package contains the perl console, a debug tool not intended for normal
use by normal users (it's not even enabled in release builds). They are shown
here for completeness.
------------------------------------
Subroutines defined:
<--EXPORTED-->
echo LIST
Prints a list of arguments on the console, or on STDOUT if no console is
registered, a trailing \n is printed too.
Arguments:
LIST List of arguments to print.
register_console NAME, DESC
Registers an instance of the console, as a macro. You don't want to know
any more because in fact you'll never have to do with this. >:)
Arguments:
NAME Set the name for the macro. (optional)
DESC Set the macro's description. (optional)
====================================
package Aegisub::Progress
------------------------------------
This package provides an interface to the progress window automatically showed
during the execution of a feature. Its functions are somewhat different to
those available in lua because of clarity, however aliases are given.
------------------------------------
Subroutines defined:
<--EXPORTED-->
set_progress VALUE
Sets the value of the progress bar. It accepts values comprised in [0, 1]
OR (1, 100] (for instance, a value of 0.86 is equivalent to a value of 86:
they both represent '86%'). You should really always use values in the
range [0, 1] if you don't wanna be mocked by your friends and relatives
(and normally they're more immediately computable).
Arguments:
VALUE The value for the progress bar.
set_task DESC
Sets the description for the current task inside progress window (just
below the progress bar).
Arguments:
DESC The description for the current task.
set_title TITLE
Sets the title for the progress window (which is not actually the window's
title, but a flashier label below it). The default title is 'Executing ...'
(with the ellpsis possibly replaced by the feature's name).
Arguments:
TITLE The title to set.
is_cancelled
Returns: A boolean indicating wether the cancel button on the progress
window where pressed in the near past.
<--EXPORTABLE-->
set VALUE
Synonym for 'set_progress(VALUE)'.
task DESC
Synonym for 'set_desc(DESC)',
title TITLE
Synonym for 'set_title(TITLE)'.
====================================
package Aegisub::Script
------------------------------------
Subroutines defined:
<--EXPORTED-->
register_macro NAME, DESC, PROC_SUB, VAL_SUB
Register a new macro.
Arguments:
NAME The name of the macro.
DESC A description for the macro.
PROC_SUB A ref to a subroutine to be used as the macro processing function
(see the callbacks section). Please, really use a reference and not
just the name of the sub, because of the script 'pacakging' described
below.
VAL_SUB A ref to a subroutine to be used as the macro validation function
(see callbacks)(optional, if not defined will be considered as always true).
set_info NAME, DESC, AUTHOR, VERSION
You can set all of the script's info values with a call to this
function. (Otherwise you can set the corresponding predefined script
variables individually.)
Arguments: see the parts about script variables, anything is optional.
====================================
package Aegisub::Script::pxxxxxxxx
------------------------------------
Every script that's loaded gets its code evaluated inside a different package -
whose name is chosen at 'random' - whereas the perl interpreter is unique, so
all the scripts see the same global package, and can possibly access other
scripts' packages. Therefore is recommended to ALWAYS declare all of the
script's local variables with 'my', and of course to 'use strict' to check on
this. You can still declare another package for your script; the script's
predefined variables should be still visible from it without any change in the
code (they're declared as 'our'), however this is discouraged.
------------------------------------
Variables defined:
$script_author
Holds the script author's name. Default is the user executing aegisub.
$script_description
Holds a description for the script. Default is 'Perl script'.
$script_name
Holds the script's name. Default is the script's filename.
$script_version
Holds the script's version. Default is current aegisub version.
$_script_path
The full path to the script's file. Any change to this variable is ignored
and overwritten.
$_script_package
The full script package as a string. Any change to this variable is
currently ignored and overwritten, and may be so forever.
------------------------------------
Callbacks definable:
macro_processing_function LINES, SELECTED, ACTIVE
A function to be used as a callback for Aegisub::Script::register_macro().
This function will be called when the user selects the corresponding macro
in the Automation menu. The first two arguments can be modified, and the
modifications will be reflected in the subtitles file.
Arguments:
LINES A reference to the list containing the subtitle file lines.
Each element of the list is a reference to a hash that represents a
single subtitle line. For the hash keys refer to lua documentation,
they are basically the same.
Example:
my $lines = $_[0]; # DON'T shift @_ (unless you reconstruct it
# afterwards) or you'll break everything and
# your hard disk be erased >:)
# The first selected line's index
my $first = $_[1][0];
# An entire line
my $l = $lines->[$first];
# The text field of a dialogue line
my $text = $lines->[$first]->{"text"};
SELECTED A ref to an array of ints, showing the currently selected
lines in the file.
ACTIVE Index of the currently active line in the subtitle file (sic).
macro_validation_function LINES, SELECTED, ACTIVE
A function to be used as a callback for Aegisub::Script::register_macro().
This function will be called whenever the Automation menu is opened to
decide what macros are applicable to the current script.
Arguments: same as macro_processing_function; however any change to the
first two ones will be ignored upon function return.
Returns:
VALID A 'boolean' value to indicate if the macro is applicable to this
particular subtitles file.