------------------------------------ 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.