Aegisub/aegisub/automation/v4-docs/perl-api.txt

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