From 09924e97165065ffb50a9e049cc45c334b686d75 Mon Sep 17 00:00:00 2001 From: Karl Blomster Date: Fri, 18 Jan 2008 01:46:12 +0000 Subject: [PATCH] Added auto4perl includes and (highly incomplete) API docs Originally committed to SVN as r1758. --- automation/include/Aegisub/PerlConsole.pm | 6 + automation/include/Aegisub/Script.pm | 6 + automation/include/perl-console.pl | 16 +++ automation/v4-docs/perl-api.txt | 137 ++++++++++++++++++++++ 4 files changed, 165 insertions(+) create mode 100644 automation/include/Aegisub/PerlConsole.pm create mode 100644 automation/include/Aegisub/Script.pm create mode 100644 automation/include/perl-console.pl create mode 100644 automation/v4-docs/perl-api.txt diff --git a/automation/include/Aegisub/PerlConsole.pm b/automation/include/Aegisub/PerlConsole.pm new file mode 100644 index 000000000..4e849f063 --- /dev/null +++ b/automation/include/Aegisub/PerlConsole.pm @@ -0,0 +1,6 @@ +package Aegisub::PerlConsole; +use Exporter 'import'; + +@EXPORT = qw( echo register_console ); + +1; diff --git a/automation/include/Aegisub/Script.pm b/automation/include/Aegisub/Script.pm new file mode 100644 index 000000000..5a21b1b90 --- /dev/null +++ b/automation/include/Aegisub/Script.pm @@ -0,0 +1,6 @@ +package Aegisub::Script; +use Exporter 'import'; + +@EXPORT = qw( register_macro set_info ); + +1; diff --git a/automation/include/perl-console.pl b/automation/include/perl-console.pl new file mode 100644 index 000000000..910ad552a --- /dev/null +++ b/automation/include/perl-console.pl @@ -0,0 +1,16 @@ +# Perl console script +# by Simone Cociancich +# This script simply call the registration function for the builtin perl console +# the perl console is chiefly intended as a development and debug tool + +use strict; +use warnings; + +Aegisub::Script::set_info( +'Perl console', +"\nThis script provides a console for messing with the perl engine \\^^/ +(if you break something don't complain >:)", +'ShB'); + +use Aegisub::PerlConsole; +register_console(); diff --git a/automation/v4-docs/perl-api.txt b/automation/v4-docs/perl-api.txt new file mode 100644 index 000000000..d41035c22 --- /dev/null +++ b/automation/v4-docs/perl-api.txt @@ -0,0 +1,137 @@ +------------------------------------ +Quick reference on Perl engine's API +------------------------------------ + +Every symbol contained in this reference is automatically made visible to the +executing script. They are not however imported in the script's package, so +they must be referenced with their full name. (A mechanism to import them +through the canonical perl commands `use' and `import' will be deployed sooner +or later.) + + +==================================== +package Aegisub + +------------------------------------ +Subroutines defined: + +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. + DESCENT Descent, i.e. the distance from the baseline to the bottom. + EXTLEADING External leading, i.e. the distance between to lines of text. + +warn LIST + Prints a warning through the GUI log facilities. It is automatically hooked + to the global `warn' function during script execution. + Arguments: + LIST List of arguments to print. + + +==================================== +package Aegisub::PerlConsole +------------------------------------ +This package contains the perl console, a debug tool not intended for normal +use by normal users. They are shown here for completeness. + +------------------------------------ +Subroutines defined: + +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::Script + +------------------------------------ +Subroutines defined: + +register_macro NAME, DESC, PROC_SUB, VAL_SUB + Register a new macro. + Arguments: + NAME The name of the macro. + DESC A dascription for the macro. + PROC_SUB A ref to a subroutine to be used as the macro processing function + (see the next section). + VAL_SUB A ref to a subrotine to be used as the macro validation function + (see next)(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 + 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 +they all see the same global package, and can possibly access other +scripts'. Therefore is recommended to ALWAYS declare all of the script's local +variables with `my', if they have to reside outside any function body, and of +course to `use strict' to check on this. You can still define another package +for your script, the script's predefined variables will still be visible +[maybe?] from it, but 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's version. + +$_script_path + The full path to the script's file. Any change to this variable is ignored. + +$_script_package + The full script package as a string. Any change to this variable is + currently ignored + +$_script_reload [BROKEN] + When this is set to true. The script will automatically be reload before + any execution if its file changed on disk. Useful during the development. + +------------------------------------ +Callbacks definable: + +macro_processing_function LINES, SELECTED, ACTIVE + A function to be used as a callback for Aegisub::Script::register_macro(). + The first two arguments can be modified, and the modification will be + reflected in the subtitles file + Arguments: + LINES A ref the the list containing the subtitle file lines + 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(). + Arguments: same as macro_processing_function; however any change to the + first two ones will be ignored upon function return. + Returns: + VALID A 'bolean' value to indicate if the macro is applicable to this + particualar subtitles file.