-
Notifications
You must be signed in to change notification settings - Fork 0
/
Karaoke_Templater_Reference__Code_lines_and_blocks.html
295 lines (284 loc) · 18.9 KB
/
Karaoke_Templater_Reference__Code_lines_and_blocks.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="keywords" content="Karaoke Templater Reference: Code lines and blocks,Automation,Automation 4 Lua Configuration dialogues,Automation 4 Lua Miscellaneous APIs,Automation 4 Lua Progress reporting,Automation 4 Lua Registration,Automation 4 Lua Subtitle file interface,Automation 4 karaskel.lua,Automation 4 unicode.lua,Automation 4 utils.lua,Automation Manager" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="search" type="application/opensearchdescription+xml" href="./opensearch_desc.php" title="Aegisub Manual (English)" />
<title>Karaoke Templater Reference: Code lines and blocks - Aegisub Manual</title>
<style type="text/css" media="screen,projection">/*<![CDATA[*/ @import "./skins/aegisub/main.css"; /*]]>*/</style>
<link rel="stylesheet" type="text/css" media="print" href="./skins/common/commonPrint.css" />
<!--[if lt IE 5.5000]><style type="text/css">@import "./skins/aegisub/IE50Fixes.css";</style><![endif]-->
<!--[if IE 5.5000]><style type="text/css">@import "./skins/aegisub/IE55Fixes.css";</style><![endif]-->
<!--[if gte IE 6]><style type="text/css">@import "./skins/aegisub/IE60Fixes.css";</style><![endif]-->
<!--[if IE]><script type="text/javascript" src="/docs/skins/common/IEFixes.js"></script>
<meta http-equiv="imagetoolbar" content="no" /><![endif]-->
<script type= "text/javascript">/*<![CDATA[*/
var skin = "aegisub";
var stylepath = "/docs/skins";
var wgArticlePath = "/docs/$1";
var wgScriptPath = "/docs";
var wgServer = "http://aegisub.cellosoft.com";
var wgCanonicalNamespace = "";
var wgCanonicalSpecialPageName = false;
var wgNamespaceNumber = 0;
var wgPageName = "Karaoke_Templater_Reference:_Code_lines_and_blocks";
var wgTitle = "Karaoke Templater Reference: Code lines and blocks";
var wgAction = "view";
var wgArticleId = "180";
var wgIsArticle = true;
var wgUserName = null;
var wgUserGroups = null;
var wgUserLanguage = "en";
var wgContentLanguage = "en";
var wgBreakFrames = false;
var wgCurRevisionId = "716";
/*]]>*/</script>
<script type="text/javascript" src="./skins/common/wikibits.js_63.html"><!-- wikibits js --></script>
<script type="text/javascript" src="/docs/index.php?title=-&action=raw&gen=js"><!-- site js --></script>
<style type="text/css">/*<![CDATA[*/
@import "./Common.css";
@import "./Aegisub.css";
@import "/docs/index.php?title=-&action=raw&gen=css&maxage=18000";
/*]]>*/</style>
<!-- Head Scripts -->
<style>
.editsection { display: none; }
</style>
</head>
<body class="mediawiki ns-0 ltr page-Karaoke_Templater_Reference_Code_lines_and_blocks">
<div id="globalWrapper">
<div id="column-content">
<div id="content">
<a name="top" id="contentTop"></a>
<h1 class="firstHeading">Karaoke Templater Reference: Code lines and blocks</h1>
<div id="bodyContent">
<h3 id="siteSub">From Aegisub Manual</h3>
<div id="contentSub"></div>
<!-- start content -->
<p>Code lines and blocks in Karaoke Templater allows you to create advanced effects by incorporating small snippets of Lua code. This can range from simple mathematical expressions adding two numbers to complex functions that for example could generate various shapes in cycling colours.
</p><p>Both code lines and code blocks are run in a separate semi-closed execution environment, meaning they are mostly undisturbed by the primary Lua environment the Karaoke Templater script itself runs in. For an overview of what variables are available in the code line/block execution environment see: <a href="./Karaoke_Templater_Reference__Code_execution_environment.html" title="Karaoke Templater Reference: Code execution environment">Code execution environment</a>.
</p>
<table id="toc" class="toc" summary="Contents"><tr><td><div id="toctitle"><h2>Contents</h2></div>
<ul>
<li class="toclevel-1"><a href="#Code_lines"><span class="tocnumber">1</span> <span class="toctext">Code lines</span></a>
<ul>
<li class="toclevel-2"><a href="#Classes_of_code_lines"><span class="tocnumber">1.1</span> <span class="toctext">Classes of code lines</span></a></li>
</ul>
</li>
<li class="toclevel-1"><a href="#Code_blocks"><span class="tocnumber">2</span> <span class="toctext">Code blocks</span></a>
<ul>
<li class="toclevel-2"><a href="#Hints_for_using_code_blocks"><span class="tocnumber">2.1</span> <span class="toctext">Hints for using code blocks</span></a></li>
</ul>
</li>
</ul>
</td></tr></table><script type="text/javascript"> if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); } </script>
<a name="Code_lines"></a><h2><span class="editsection">[edit]</span> <span class="mw-headline"> Code lines </span></h2>
<p>A code line is a special kind of template line. Instead of using the <code>template</code> keyword in the Effect field it uses the <code>code</code> keyword. A code line contains only Lua code and does not by itself produce any lines in the resulting file.
</p><p>The two primary uses of code lines are:
</p>
<ul><li> Defining/updating variables for use later in templates
</li><li> Defining functions for use later in templates
</li></ul>
<p>For example, if you need a random number, but also need to use it twice in one template, you can use a code line to first generate the number and store it to a variable, then use that variable in your template line.
</p><p>Another example could be defining a function that produces a random colour.
</p>
<a name="Classes_of_code_lines"></a><h3><span class="editsection">[edit]</span> <span class="mw-headline"> Classes of code lines </span></h3>
<p>Like there's multiple classes of template lines there's also multiple classes of code lines. Some of them are the same, and some only exist for one or the other.
</p><p>You specify the class of the code line in the Effect field after the <code>code</code> keyword. The possible classes are:
</p><p><b>once</b>
</p>
<dl><dd>Code lines in the <code>once</code> class are run exactly one time, before any templates are applied. This is usually the best place to define functions and general tables of values you need to look up later.
</dd><dd>This is the default class, if you don't specify a class for a code line it's automatically in the <code>once</code> class.
</dd></dl>
<p><b>line</b>
</p>
<dl><dd>Code lines in the <code>line</code> class are run when a new line is encountered. They are run once per line. They are run interspersed with <code>line</code>/<code>pre-line</code> templates in the order they appear. (There are no "pre-line" code lines.)
</dd></dl>
<p><b>syl</b>
</p>
<dl><dd>Code lines in the <code>syl</code> class are run when a new syllable is encountered. They run once per syllable. They are run interspersed with <code>syl</code> templates.
</dd></dl>
<p><b>furi</b>
</p>
<dl><dd>Code lines in the <code>furi</code> class are run when a new furigana syllable is encountered. They run once per furigana syllable. They are run interspersed with <code>furi</code> templates.
</dd></dl>
<p>You <i>cannot</i> have templates with <code>char</code> or <code>multi</code> modifiers run per-character/per-highlight interspersed with code lines. This is a limitation of the execution model. This may or may not change in later versions of Karaoke Templater.
</p>
<a name="Code_blocks"></a><h2><span class="editsection">[edit]</span> <span class="mw-headline"> Code blocks </span></h2>
<p>A code block is a block of Lua code within a template line. Code blocks are used to insert more complex things than can be expressed with <a href="./Karaoke_Templater_Reference__Inline_variables.html" title="Karaoke Templater Reference: Inline variables">inline variables</a>.
</p><p>Code blocks are required to be single Lua expressions, since a <code>return</code> statement is automatically prepended to the code. This means you (among other things) can't do assignments or use <code>if</code> statements within code blocks, you must use a code line if you want to do any of those things. (There is a way to do basic conditionals in code blocks though, see below.)
</p><p>You create a code block by surrounding the code by exclamation marks, like this:
</p>
<pre>{\t($start,<b>!syl.start_time+20!</b>,\bord0)}
</pre>
<p>It is possible to use inline variables within code blocks. They are expanded before the code block is parsed, so to the Lua interpreter the inline variables look like regular constants.
</p>
<a name="Hints_for_using_code_blocks"></a><h3><span class="editsection">[edit]</span> <span class="mw-headline"> Hints for using code blocks </span></h3>
<p>Most simple mathematical expressions work just like you'd expect them to. Operator precedence rules are those of regular arithmetic.
</p><p>A code block should always return a string or numeric value, if it returns a boolean, a table or something else it might cause a warning and the resulting line containing the wrong output.
</p><p>To create simple conditionals within code blocks you can use the <code>and</code> and <code>or</code> operators to chain values and conditions. For example:
</p>
<pre>{\k<b>!(syl.duration>100) and "f" or ""!</b>$kdur}
</pre>
<p>If the syllable duration is longer than 100 ms the first sub-expression is true, and the code block returns <tt>"f"</tt>, otherwise the entire <code>and</code> expression is false, and the right-hand argument of the <code>or</code> expression is returned.
</p><p>In Lua, <code>and</code> binds stronger than <code>or</code> meaning that <code>and</code> expressions are evaluated first. In the above expression the effective grouping is like this: <code>((syl.duration > 100) and "f") or ""</code>
</p>
<div style="border-top: 2px solid #448; border-bottom: 1px solid #448; background: #f0f0ff; margin: 1em; padding: 0.5em;">
<div style="text-align:center; font-weight:bold; background:#ddf;"><a href="./Automation.html" title="Automation">Automation 4</a></div>
<table style="width:100%; font-size: smaller;">
<tr><th>Overview:</th><td style="text-align: center; background:#f8f8ff;">
<p><a href="./Automation_Manager.html" title="Automation Manager">Automation Manager</a> •
<a href="./Running_Automation_macros.html" title="Running Automation macros">Running macros</a> •
<a href="./Exporting.html" title="Exporting">Using export filters</a> •
<a href="./Using_the_included_macros.html" title="Using the included macros">Standard macros</a> •
<a href="./Overview_of_changes_from_Automation_3.html" title="Overview of changes from Automation 3">Changes from Automation 3</a> •
<a href="./Moving_from_Automation_3.html" title="Moving from Automation 3">Moving from Automation 3</a>
</p>
</td></tr>
<tr><th><a href="./Karaoke_Templater.html" title="Karaoke Templater">Karaoke Templater</a> reference:</th><td style="text-align: center; background:#f8f8ff;">
<p><a href="./Karaoke_Templater_Reference__Declaring_template_and_code_lines.html" title="Karaoke Templater Reference: Declaring template and code lines">Declaring templates</a> •
<a href="./Karaoke_Templater_Reference__Template_execution_rules_and_order.html" title="Karaoke Templater Reference: Template execution rules and order">Execution order</a> •
<a href="./Karaoke_Templater_Reference__Template_modifiers.html" title="Karaoke Templater Reference: Template modifiers">Modifiers</a> •
<a href="./Karaoke_Templater_Reference__Inline_variables.html" title="Karaoke Templater Reference: Inline variables">Inline-variables ($-variables)</a> •
<strong class="selflink">Code lines and blocks</strong> •
<a href="./Karaoke_Templater_Reference__Code_execution_environment.html" title="Karaoke Templater Reference: Code execution environment">Execution envirionment</a>
</p>
</td></tr>
<tr><th><a href="./Lua_Reference.html" title="Lua Reference">Lua</a> reference:</th><td style="text-align: center; background:#f8f8ff;">
<p><a href="./Automation_4_Lua_Registration.html" title="Automation 4 Lua Registration">Registration</a> •
<a href="./Automation_4_Lua_Subtitle_file_interface.html" title="Automation 4 Lua Subtitle file interface">Subtitles object</a> •
<a href="./Automation_4_Lua_Progress_reporting.html" title="Automation 4 Lua Progress reporting">Progress reporting</a> •
<a href="./Automation_4_Lua_Configuration_dialogues.html" title="Automation 4 Lua Configuration dialogues">Config dialogues</a> •
<a href="./Automation_4_Lua_Miscellaneous_APIs.html" title="Automation 4 Lua Miscellaneous APIs">Misc. APIs</a> •
<a href="./Automation_4_karaskel.lua.html" title="Automation 4 karaskel.lua">karaskel.lua</a> •
<a href="./Automation_4_utils.lua.html" title="Automation 4 utils.lua">utils.lua</a> •
<a href="./Automation_4_unicode.lua.html" title="Automation 4 unicode.lua">unicode.lua</a> •
cleantags.lua
</p>
</td></tr>
<tr><th>Karaskel concepts:</th><td style="text-align: center; background:#f8f8ff;">
<p><a href="./Automation_4_karaskel.lua.html#Style_table" title="Automation 4 karaskel.lua">Style tables</a> •
<a href="./Automation_4_karaskel.lua.html#Dialogue_line_table" title="Automation 4 karaskel.lua">Dialogue line tables</a> •
<a href="./Automation_4_karaskel.lua.html#Karaoke_and_furigana_syllable_tables" title="Automation 4 karaskel.lua">Syllable tables</a> •
<a href="./Karaoke_inline-fx.html" title="Karaoke inline-fx">Inline effects</a> •
<a href="./Furigana_karaoke.html" title="Furigana karaoke">Furigana</a>
</p>
</td></tr>
</table>
</div>
<!--
Pre-expand include size: 6661 bytes
Post-expand include size: 2701 bytes
Template argument size: 0 bytes
Maximum: 2097152 bytes
-->
<!-- Saved in parser cache with key zeratul-aegimanual_:pcache:idhash:180-0!1!0!!en!2 and timestamp 20090615192019 -->
<div class="printfooter">
Retrieved from "<a href="./Karaoke_Templater_Reference__Code_lines_and_blocks.html">http://aegisub.cellosoft.com/docs/Karaoke_Templater_Reference:_Code_lines_and_blocks</a>"</div>
<!-- end content -->
<div class="visualClear"></div>
</div>
</div>
</div>
<div id="column-one">
<div class="portlet" id="p-logo">
<a style="background-image: url(/docs/skins/common/images/wiki.png);"
href="./Main_Page.html"
title="Main Page"></a>
</div>
<script type="text/javascript"> if (window.isMSIE55) fixalpha(); </script>
<div class='portlet' id='p-navigation'>
<h5>Navigation</h5>
<div class='pBody'>
<ul>
<li id="n-mainpage"><a href="./Main_Page.html">Main Page</a></li>
</ul>
</div>
</div>
<div class='portlet' id='p-Introduction'>
<h5>Introduction</h5>
<div class='pBody'>
<ul>
<li id="n-What-is-Aegisub?"><a href="./About.html">What is Aegisub?</a></li>
<li id="n-Highlights"><a href="./Highlights.html">Highlights</a></li>
<li id="n-Credits"><a href="./Credits.html">Credits</a></li>
<li id="n-Support-Aegisub"><a href="./Support.html">Support Aegisub</a></li>
<li id="n-FAQ"><a href="./FAQ.html">FAQ</a></li>
<li id="n-Tutorials"><a href="./Tutorials.html">Tutorials</a></li>
</ul>
</div>
</div>
<div class='portlet' id='p-Working with Subtitles'>
<h5>Working with Subtitles</h5>
<div class='pBody'>
<ul>
<li id="n-Editing-Subtitles"><a href="./Editing_Subtitles.html">Editing Subtitles</a></li>
<li id="n-Exporting-Subtitles"><a href="./Exporting.html">Exporting Subtitles</a></li>
<li id="n-Applying-Subtitles"><a href="./Attaching_subtitles_to_video.html">Applying Subtitles</a></li>
<li id="n-Spell-Checker"><a href="./Spell_Checker.html">Spell Checker</a></li>
<li id="n-Translation-Assistant"><a href="./Translation_Assistant.html">Translation Assistant</a></li>
<li id="n-Paste-Over"><a href="./Paste_Over.html">Paste Over</a></li>
<li id="n-Select-Lines"><a href="./Select_Lines.html">Select Lines</a></li>
</ul>
</div>
</div>
<div class='portlet' id='p-Typesetting'>
<h5>Typesetting</h5>
<div class='pBody'>
<ul>
<li id="n-Introduction"><a href="./Typesetting.html">Introduction</a></li>
<li id="n-Working-with-Video"><a href="./Video.html">Working with Video</a></li>
<li id="n-Editing-styles"><a href="./Styles.html">Editing styles</a></li>
<li id="n-Visual-Typesetting"><a href="./Visual_Typesetting.html">Visual Typesetting</a></li>
<li id="n-ASS-Override-Tags"><a href="./ASS_Tags.html">ASS Override Tags</a></li>
<li id="n-Colour-Picker"><a href="./Colour_Picker.html">Colour Picker</a></li>
<li id="n-Styling-Assistant"><a href="./Styling_Assistant.html">Styling Assistant</a></li>
<li id="n-Resolution-Resampler"><a href="./Resolution_Resampler.html">Resolution Resampler</a></li>
<li id="n-Fonts-Collector"><a href="./Fonts_Collector.html">Fonts Collector</a></li>
</ul>
</div>
</div>
<div class='portlet' id='p-Timing'>
<h5>Timing</h5>
<div class='pBody'>
<ul>
<li id="n-Working-with-Audio"><a href="./Audio.html">Working with Audio</a></li>
<li id="n-Shift-times"><a href="./Shift_Times.html">Shift times</a></li>
<li id="n-Timing-Post-Processor"><a href="./Timing_Post-Processor.html">Timing Post-Processor</a></li>
<li id="n-Kanji-Timer"><a href="./Kanji_Timer.html">Kanji Timer</a></li>
</ul>
</div>
</div>
<div class='portlet' id='p-Automation'>
<h5>Automation</h5>
<div class='pBody'>
<ul>
<li id="n-Overview"><a href="./Automation.html">Overview</a></li>
<li id="n-Karaoke-Templater"><a href="./Karaoke_Templater.html">Karaoke Templater</a></li>
<li id="n-Lua-Reference"><a href="./Lua_Reference.html">Lua Reference</a></li>
</ul>
</div>
</div>
<div class='portlet' id='p-Miscellaneous'>
<h5>Miscellaneous</h5>
<div class='pBody'>
<ul>
<li id="n-Aegisub-Options"><a href="./Options.html">Aegisub Options</a></li>
<li id="n-Script-Properties"><a href="./Properties.html">Script Properties</a></li>
<li id="n-Attachment-Manager"><a href="./Attachment_Manager.html">Attachment Manager</a></li>
</ul>
</div>
</div>
<!-- end of the left (by default at least) column -->
<div class="visualClear"></div>
<div id="footer">
<table width = "100%">
<tr><td width="5%" align="left" nowrap='nowrap'></td>
<td align="center"></td>
<td width="5%" align="right" nowrap='nowrap'></td></tr></table>
</div>
<script type="text/javascript">if (window.runOnloadHook) runOnloadHook();</script>
</div>
<!-- Served by cellosoft.com in 0.140 secs. --> </body>
</html>