· 9 years ago · Jun 16, 2017, 08:56 AM
1<HTML>
2<h1 id=section_introduction>Introduction</h1>
3<h2 class='def_title introduction_title' id=introduction_some-of-what's-new-in-2.0><a class='heading_link' href=#introduction_some-of-what's-new-in-2.0></a>Some of what's new in 2.0</h2>
4</HTML>
5A lot of features have been added to Harlowe 2.0, many of which are designed to shorten existing code idioms or make certain workarounds unnecessary. The changes to existing features you should first familiarise yourself with are:
6
7 * The default Harlowe colour scheme is now white text on black, in adherence to SugarCube and Sugarcane. You can change it back to white using the instructions below.
8 * Expressions like ''%%$a < 4 and 5%%'' will now be interpreted as ''%%$a < 4 and it < 5%%'' instead of always producing an error.
9 * Using ''%%is%%'' with comparison operators, like ''%%$a is < 3%%'', is now valid.
10 * Changers can be attached to hooks with [[harlowe:whitespace|whitespace]] between them - ''%%(if: $coverBlown) [Run!]%%'' is now valid.
11 * Changers can be attached to named hooks - ''%%(if: true) |moths>[Several moths!]%%'' is now valid.
12 * Changers can be added together using + while attaching them to a hook - ''%%(font:'Shatter')+(text-style:'outline')[CRASH!]%%'' is now valid.
13 * The default CSS has been changed such that the story's ''%%font%%'' must be overridden on ''%%tw-story%%'' rather than ''%%html%%'' (for consistency with other CSS properties).
14
15The following new features also deserve your attention.
16
17 * The built-in ''%%?page%%'', ''%%?passage%%'', ''%%?sidebar%%'' and ''%%?link%%'' hooks
18 * Hidden hooks, and the [[harlowe:show|(show:)]] and [[harlowe:hidden|(hidden:)]] command macros
19 * Temp variables (see the [[harlowe:set|(set:)]] article)
20 * The special ''%%any%%'' and ''%%all%%'' data names for arrays, strings and datasets (see each type's articles)
21 * The [[harlowe:for|(for:)]] changer macro
22 * The [[harlowe:enchant|(enchant:)]] command macro
23 * The [[harlowe:find|(find:)]], [[harlowe:altered|(altered:)]] and [[harlowe:folded|(folded:)]] data macros
24 * The [[harlowe:dm|(dm:)]] and [[harlowe:ds|(ds:)]] aliases for [[harlowe:datamap|(datamap:)]] and [[harlowe:dataset|(dataset:)]]
25 * Column markup
26 * ''%%tw-passage%%'' elements now have a ''%%tags%%'' attribute.
27
28For a complete list of changes, consult the <html><a href="#changes_2.0.0-changes-(also-see-1.2.3-changes)"></html>change log<html></a></html> section.
29
30=== Changing back from dark to light: ===
31
32You may want to use the black-on-white colour scheme of Harlowe 1 instead of the new white-on-black colour scheme. A few of the new features described above can help you do this without using CSS! Simply create a ''%%header%%'' tagged passage (a passage with the tag 'header'), and include this in it:
33
34<code>
35(enchant: ?page, (text-colour: black) + (background: white))
36</code>
37This uses the new ?page built-in hook to target the entire page, and the new [[harlowe:enchant|(enchant:)]] macro to apply changer commands to it directly. In the future, more features are planned that will allow styling the page in this way without CSS, staying within Harlowe code, and letting you use variables and other macros inside it.\\
38<html><h1 id=section_markup></html>Passage markup<html></h1></html>
39
40<HTML>
41<h2 class='def_title markup_title' id=markup_link><a class='heading_link' href=#markup_link></a>Link markup
42</h2>
43</HTML>
44Hyperlinks are the player's means of moving between passages and affecting the story. They consist of\\
45//link text//, which the player clicks on, and a //passage name// to send the player to.
46
47Inside matching non-nesting pairs of ''%%[[%%'' and ''%%]]%%'', place the link text and the passage name,\\
48separated by either ''%%->%%'' or ''%%<-%%'', with the arrow pointing to the passage name.
49
50You can also write a shorthand form, where there is no ''%%<-%%'' or ''%%->%%'' separator.\\
51The entire content is treated as a passage name, and its evaluation is treated as the link text.
52
53=== Example usage: ===
54
55<code>
56[[Go to the cellar->Cellar]] is a link that goes to a passage named "Cellar".
57[[Parachuting<-Jump]] is a link that goes to a passage named "Parachuting".
58[[Down the hatch]] is a link that goes to a passage named "Down the hatch".
59</code>
60=== Details: ===
61
62The interior of a link (the text between ''%%[[%%'' and ''%%]]%%'') may contain any character except ''%%]%%''. If additional\\
63''%%->%%''s or ''%%<-%%''s appear, the rightmost right arrow or leftmost left arrow is regarded as the canonical separator.
64
65<code>
66[[A->B->C->D->E]] has a link text of
67A->B->C->D
68and a passage name of
69E
70
71[[A<-B<-C<-D<-E]] has a link text of
72B<-C<-D<-E
73and a passage name of
74A
75</code>
76This syntax is not the only way to create links – there are many link macros, such as (link:), which can\\
77be used to make more versatile hyperlinks in your story.\\
78<html><h2 class='def_title markup_title' id=markup_style><a class='heading_link' href=#markup_style></a></html>Style markup\\
79<html></h2></html>
80
81Often, you'd like to apply styles to your text – to italicize a book title,\\
82for example. You can do this with simple formatting codes that\\
83are similar to the double brackets of a link. Here is what's available to you:
84
85^Styling ^
86|Italics |
87|Boldface |
88|Deleted/spoiler text|
89|Emphasis |
90|Strong emphasis |
91|Superscript |
92
93=== Example usage: ===
94
95<code>
96You //can't// be serious! I have to go through the ''whole game''
97again? ^^Jeez, louise!^^
98</code>
99=== Details: ===
100
101You can nest these codes - ''%%''//text//''%%'' will produce **//bold italics//** - but they must nest\\
102symmetrically. ''%%''//text''//%%'' will not work.
103
104A larger variety of text styles can be produced by using the [[harlowe:text-style|(text-style:)]] macro, attaching it to\\
105a text hook you'd like to style. And, furthermore, you can use HTML tags like ''%%<mark>%%'' as an additional\\
106styling option.\\
107<html><h2 class='def_title markup_title' id=markup_macro><a class='heading_link' href=#markup_macro></a></html>Macro markup\\
108<html></h2></html>
109
110A macro is a piece of code that is inserted into passage text. Macros are used to accomplish many effects,\\
111such as altering the game's state, displaying different text depending on the game's state, and altering\\
112the manner in which text is displayed.
113
114There are many built-in macros in Harlowe. To use one, you must //call// upon it in your passage by writing\\
115the name, a colon, and some data values to provide it, all in parentheses. For instance, you call the [[harlowe:print|(print:)]]\\
116macro like so: ''%%(print: 54)%%''. In this example, ''%%print%%'' is the macro's name, and ''%%54%%'' is the value.
117
118The name of the macro is case-insensitive, dash-insensitive and underscore-insensitive. This means that\\
119any combination of case, dashes and underscores in the name will be ignored. You can, for instance, write\\
120''%%(go-to:)%%'' as ''%%(goto:)%%'', ''%%(Goto:)%%'', ''%%(GOTO:)%%'', ''%%(GoTo:)%%'', ''%%(Go_To:)%%'', ''%%(Got--o:)%%'', ''%%(-_-_g-o-t-o:)%%'', or\\
121any other combination or variation.
122
123You can provide any type of data values to a macro call - numbers, strings, booleans, and so forth. These\\
124can be in any form, as well - ''%%"Red" + "belly"%%'' is an expression that produces a single string, "Redbelly",\\
125and can be used anywhere that the joined string can be used. Variables, too, can be used with macros, if\\
126their contents matches what the macro expects. So, if ''%%$var%%'' contains the string "Redbelly", then ''%%(print: $var)%%'',\\
127''%%(print: "Redbelly")%%'' and ''%%(print: "Red" + "belly")%%'' are exactly the same.
128
129Furthermore, each macro call produces a value itself - [[harlowe:num|(num:)]], for instance, produces a number, [[harlowe:a|(a:)]] an array - so\\
130they too can be nested inside other macro calls. ''%%(if: (num:"5") > 2)%%'' nests the [[harlowe:num|(num:)]] macro inside the [[harlowe:if|(if:)]] macro.
131
132If a macro can or should be given multiple values, separate them with commas. You can give the ''%%(a:)%%'' macro\\
133three numbers like so: ''%%(a: 2, 3, 4)%%''. The final value may have a comma after it, or it may not - ''%%(a: 2, 3, 4,)%%''\\
134is equally valid. Also, if you have a data value that's an array, string or dataset, you can "spread out" all\\
135of its values into the macro call by using the ''%%...%%'' operator: ''%%(either: ...$array)%%'' will act as if every value in\\
136$array was placed in the [[harlowe:either|(either:)]] macro call separately\\
137<html><h2 class='def_title markup_title' id=markup_variable><a class='heading_link' href=#markup_variable></a></html>Variable markup\\
138<html></h2></html>
139
140As described in the documentation for the [[harlowe:set|(set:)]] macro, variables are used to remember data values\\
141in your game, keep track of the player's status, and so forth. They start with ''%%$%%'' (for normal variables)\\
142or ''%%_%%'' (for temp variables, which only exist inside a single passage, hook or lambda).
143
144You can print the contents of variables, or any further items within them, using the [[harlowe:print|(print:)]] and [[harlowe:for|(for:)]]\\
145macros. Or, if you only want to print a single variable, you can just enter the variable's name directly\\
146in your passage's prose.
147
148<code>
149Your beloved plushie, $plushieName, awaits you after a long work day.
150You put your _heldItem down and lift it for a snuggle.
151</code>
152Furthermore, if the variable contains a changer command, such as that created by [[harlowe:text-style|(text-style:)]] and such,\\
153then the variable can be attached to a hook to apply the changer to the hook:
154
155<code>
156$robotText[Good golly! Your flesh... it's so soft!]
157_assistantText[Don't touch me, please! I'm ticklish.]
158</code>
159<HTML>
160<h2 class='def_title markup_title' id=markup_hook><a class='heading_link' href=#markup_hook></a>Hook markup
161</h2>
162</HTML>
163A hook is a means of indicating that a specific span of passage prose is special in some way. It\\
164essentially consists of text between single ''%%[%%'' and ''%%]%%'' marks. Prose inside a hook can be modified, styled,\\
165controlled and analysed in a variety of ways using macros.
166
167A hook by itself, such as ''%%[some text]%%'', is not very interesting. However, if you attach a macro or a\\
168variable to the front, the attached value is used to change the hook in some way, such as hiding\\
169it based on the game state, altering the styling of its text, moving its text to elsewhere in the passage.
170
171<code>
172(font: "Courier New")[This is a hook.
173
174As you can see, this has a macro instance in front of it.]
175This text is outside the hook.
176</code>
177The [[harlowe:font|(font:)]] macro is one of several macros which produces a special styling command, instead of a basic\\
178data type like a number or a string. In this case, the command changes the attached hook's font to Courier New,\\
179without modifying the other text.
180
181You can save this command to a variable, and then use it repeatedly, like so:
182
183<code>
184(set: $x to (font: "Skia"))
185$x[This text is in Skia.]
186$x[As is this text.]
187</code>
188The basic [[harlowe:if|(if:)]] macro is used by attaching it to a hook, too:
189
190<code>
191(if: $x is 2)[This text is only displayed if $x is 2.]
192</code>
193For more information about command macros, consult the descriptions for each of them in turn.\\
194<html><h2 class='def_title markup_title' id=markup_named-hook><a class='heading_link' href=#markup_named-hook></a></html>Named hook markup\\
195<html></h2></html>
196
197For a general introduction to hooks, see their respective markup description. Named hooks are a less common type of\\
198hook that offer unique benefits. To produce one, instead of attaching a macro, attach a "nametag" to the front or back:
199
200<code>
201[This hook is named 'opener']<opener|
202
203|s2>[This hook is named 's2']
204</code>
205(Hook nametags are supposed to resemble triangular gift box nametags.)
206
207A macro can refer to and alter the text content of a named hook by referring to the hook as if it were a variable.\\
208To do this, write the hook's name as if it were a variable, but use the ''%%?%%'' symbol in place of the ''%%$%%'' symbol:
209
210<code>
211[Fie and fuggaboo!]<shout|
212
213(click: ?shout)[ (replace: ?shout)["Blast and damnation!"] ]
214</code>
215The above [[harlowe:click|(click:)]] and [[harlowe:replace|(replace:)]] macros can remotely refer to and alter the hook using its name. This lets you,\\
216for instance, write a section of text full of tiny hooks, and then attach behaviour to them further in the passage:
217
218<code>
219Your [ballroom gown]<c1| is [bright red]<c2| with [silver streaks]<c3|,
220and covered in [moonstones]<c4|.
221
222(click: ?c1)[A hand-me-down from your great aunt.]
223(click: ?c2)[A garish shade, to your reckoning.]
224(click: ?c3)[Only their faint shine keeps them from being seen as grey.]
225(click: ?c4)[Dreadfully heavy, they weigh you down and make dancing arduous.]
226</code>
227As you can see, the top sentence remains mostly readable despite the fact that several words have [[harlowe:click|(click:)]] behaviours\\
228assigned to them.
229
230=== Built in names: ===
231
232There are four special built-in hook names, ?Page, ?Passage, ?Sidebar and ?Link, which, in addition to selecting named hooks,\\
233also affect parts of the page that you can't normally style with macros. They can be styled using the [[harlowe:enchant|(enchant:)]] macro.
234
235 * ''%%?Page%%'' selects the page element (to be precise, the ''%%<tw-story>%%'' element) and using it with the [[harlowe:background|(background:)]] macro lets you\\
236change the background of the entire page.
237 * ''%%?Passage%%'' affects just the element that contains the current passage's text (to be precise, the ''%%<tw-passage>%%'' element) and lets you,\\
238for instance, change the [[harlowe:text-colour|(text-colour:)]] or [[harlowe:font|(font:)]] of all the text, or apply complex [[harlowe:css|(css:)]] to it.
239 * ''%%?Sidebar%%'' selects the passage's sidebar containing undo/redo icons (''%%<tw-sidebar>%%''). You can style it with styling macros, or use\\
240[[harlowe:replace|(replace:)]] or [[harlowe:append|(append:)]] to insert your own text into it.
241 * ''%%?Link%%'' selects all of the links (passage links, and those created by [[harlowe:link|(link:)]] and other macros) in the passage.
242
243(Note that, as mentioned above, if you use these names for your own hooks, such as by creating a named hook like ''%%|passage>[]%%'',\\
244then they will, of course, be included in the selections of these names.)\\
245<html><h2 class='def_title markup_title' id=markup_hidden-hook><a class='heading_link' href=#markup_hidden-hook></a></html>Hidden hook markup\\
246<html></h2></html>
247
248Hidden hooks are an advanced kind of named hook that can be shown using macros like [[harlowe:show|(show:)]]. For a general introduction to\\
249named hooks, see their respective markup description.
250
251There may be hooks whose contained prose you don't want to be visible as soon as the passage appears -\\
252a time delay, or the click of a link should be used to show them. You can set a hook to be //hidden// by altering\\
253the hook tag syntax - replace the ''%%>%%'' or ''%%<%%'' mark with a parenthesis.
254
255<code>
256|visible>[This hook is visible when the passage loads.]
257|cloaked)[This hook is hidden when the passage loads, and needs a macro like `(show:?cloaked)` to reveal it.]
258
259[My commanding officer - a war hero, and a charismatic face for the military.]<sight|
260[Privately, I despise the man. His vacuous boosterism makes a mockery of my sacrifices.](thoughts|
261</code>
262(You can think of this as being visually similar to the pointed tails of comic speech balloons vs. round, enclosed\\
263thought balloons.)
264
265In order to be useful, hidden hooks must have a name, which macros like [[harlowe:show|(show:)]] can use to show them. Hence,\\
266there's no way to make a hidden unnamed hook - at least, without using a conditional macro like [[harlowe:if|(if:)]].\\
267<html><h2 class='def_title markup_title' id=markup_html><a class='heading_link' href=#markup_html></a></html>HTML markup\\
268<html></h2></html>
269
270If you are familiar with them, HTML tags (like ''%%<img>%%'') and HTML elements (like ''%%§%%'') can be inserted\\
271straight into your passage text. They are treated very naively - they essentially pass through Harlowe's\\
272markup-to-HTML conversion process untouched.
273
274=== Example usage: ===
275
276<code>
277<mark>This is marked text.
278
279¶ So is this.
280
281And this.</mark>
282</code>
283=== Details: ===
284
285HTML elements included in this manner are given a ''%%data-raw%%'' attribute by Harlowe, to distinguish them\\
286from elements created via markup.
287
288You can include a ''%%<script>%%'' tag in your passage to run Javascript code. The code will run as soon as the\\
289containing passage code is rendered.
290
291You can also include a ''%%<style>%%'' tag containing CSS code. The CSS should affect the entire page\\
292until the element is removed from the DOM.
293
294Finally, you can also include HTML comments ''%%<!-- Comment -->%%'' in your code, if you wish to leave\\
295reminder messages or explanations about the passage's code to yourself.\\
296<html><h2 class='def_title markup_title' id=markup_verbatim><a class='heading_link' href=#markup_verbatim></a></html>Verbatim markup\\
297<html></h2></html>
298
299As plenty of symbols have special uses in Harlowe, you may wonder how you can use them normally, as mere symbols,\\
300without invoking their special functionality. You can do this by placing them between a pair of ''%%`%%'' marks.
301
302If you want to escape a section of text which already contains single ''%%`%%'' marks, simply increase the number\\
303of ''%%`%%'' marks used to enclose them.
304
305=== Example usage: ===
306
307 * ''%%I want to include `[[double square brackets]]` in my story, so I use grave ` marks.%%''
308 * ''%%I want to include ``single graves ` in my story``, so I place them between two grave marks.%%''
309
310There's no hard limit to the amount of graves you can use to enclose the text.\\
311<html><h2 class='def_title markup_title' id=markup_bulleted-list><a class='heading_link' href=#markup_bulleted-list></a></html>Bulleted list markup\\
312<html></h2></html>
313
314You can create bullet-point lists in your text by beginning lines with an asterisk ''%%*%%'', followed by [[harlowe:whitespace|whitespace]],\\
315followed by the list item text. The asterisk will be replaced with an indented bullet-point. Consecutive lines\\
316of bullet-point items will be joined into a single list, with appropriate vertical spacing.
317
318Remember that there must be whitespace between the asterisk and the list item text! Otherwise, this markup\\
319will conflict with the emphasis markup.
320
321If you use multiple asterisks (''%%**%%'', ''%%***%%'' etc.) for the bullet, you will make a nested list, which is indented deeper than\\
322a normal list. Use nested lists for "children" of normal list items.
323
324=== Example usage: ===
325
326<code>
327 * Bulleted item
328 * Bulleted item 2
329 ** Indented bulleted item
330</code>
331<HTML>
332<h2 class='def_title markup_title' id=markup_numbered-list><a class='heading_link' href=#markup_numbered-list></a>Numbered list markup
333</h2>
334</HTML>
335You can create numbered lists in your text, which are similar to bulleted lists, but feature numbers in place of bullets.\\
336Simply begin single lines with ''%%0.%%'', followed by [[harlowe:whitespace|whitespace]], followed by the list item text. Consecutive items will be\\
337joined into a single list, with appropriate vertical spacing. Each of the ''%%0.%%''s will be replaced\\
338with a number corresponding to the item's position in the list.
339
340Remember that there must be whitespace between the ''%%0.%%'' and the list item text! Otherwise, it will be regarded as a plain\\
341number.
342
343If you use multiple ''%%0.%%'' tokens (''%%0.0.%%'', ''%%0.0.0.%%'' etc.) for the bullet, you will make a nested list, which uses different\\
344numbering from outer lists, and are indented deeper. Use nested lists for "children" of normal list items.
345
346=== Example usage: ===
347
348<code>
3490. Numbered item
350 0. Numbered item 2
351 0.0. Indented numbered item
352</code>
353<HTML>
354<h2 class='def_title markup_title' id=markup_aligner><a class='heading_link' href=#markup_aligner></a>Aligner markup
355</h2>
356</HTML>
357An aligner is a special single-line token which specifies the alignment of the subsequent text. It is essentially\\
358'modal' - all text from the token onward (until another aligner is encountered) is wrapped in a ''%%<tw-align>%%'' element\\
359(or unwrapped in the case of left-alignment, as that is the default).
360
361 * Right-alignment, resembling ''%%==>%%'' is produced with 2 or more ''%%=%%''s followed by a ''%%>%%''.
362 * Left-alignment, resembling ''%%<==%%'' is restored with a ''%%<%%'' followed by 2 or more ''%%=%%''.
363 * Justified alignment, resembling ''%%<==>%%'' is produced with ''%%<%%'', 2 or more ''%%=%%'', and a closing ''%%>%%''.
364 * Mixed alignment is 1 or more ''%%=%%'', then ''%%><%%'', then 1 or more ''%%=%%''. The ratio of quantity of left ''%%=%%''s and right ''%%=%%''s determines\\
365the alignment: for instance, one ''%%=%%'' to the left and three ''%%=%%''s to the right produces 25% left alignment.
366
367Any amount of [[harlowe:whitespace|whitespace]] is permitted before or after each token, as long as it is on a single line.
368
369=== Example usage: ===
370
371<code>
372==>
373This is right-aligned
374 =><=
375This is centered
376 <==>
377This is justified
378<==
379This is left-aligned (undoes the above)
380===><=
381This has margins 3/4 left, 1/4 right
382 =><=====
383This has margins 1/6 left, 5/6 right.
384</code>
385<HTML>
386<h2 class='def_title markup_title' id=markup_column><a class='heading_link' href=#markup_column></a>Column markup
387</h2>
388</HTML>
389Column markup is, like aligner markup, a special single-line token which indicates that the subsequent text should be laid out in columns. They consist of a number of ''%%|%%'' marks, indicating the size of the column relative to the other columns - the total width of all columns equals the page width, and this is divided among the columns by their ''%%|%%'' marks. They also have a number of ''%%=%%'' marks surrounding it, indicating the size of the column's margins in CSS "em" units (which are about the width of a capital M).
390
391All text from the token onward, until the next token is encountered, is contained in the specified column. A ''%%|==|%%'' token ends the set of columns and returns the page to normal.
392
393Columns are currently laid out from left to right, in order of appearance.
394
395Any amount of [[harlowe:whitespace|whitespace]] is permitted before or after each token, as long as it is on a single line.
396
397=== Example usage: ===
398
399<code>
400|==
401This is in the leftmost column, which has a right margin of about 2 letters wide.
402 =|||=
403This is in the next column, which has margins of 1 letter wide. It is three times as wide as the left column.
404 =====||
405This is in the right column, which has a right margin of about 5 letters wide. It is twice as wide as the left column.
406 |==|
407This text is not in columns, but takes up the entire width, as usual.
408</code>
409You can create nested columns by enclosing the inner set of columns in an unnamed hook, like so:
410
411<code>
412|==
413This is the outer left column.
414==|
415This is outer right column.
416[\
417 |==
418This is the inner left column, inside the outer right column.
419 ==|
420This is the inner right column, inside the outer right column.
421\]
422</code>
423<HTML>
424<h2 class='def_title markup_title' id=markup_heading><a class='heading_link' href=#markup_heading></a>Heading markup
425</h2>
426</HTML>
427Heading markup is used to create large headings, such as in structured prose or title splash passages.\\
428It is almost the same as the Markdown heading syntax: it starts on a fresh line,\\
429has one to six consecutive ''%%f#%%''s, and ends at the line break.
430
431=== Example usage: ===
432
433<code>
434#Level 1 heading renders as an enclosing <h1>
435 ###Level 3 heading renders as an enclosing <h3>
436 ######Level 6 heading renders as an enclosing <h6>
437</code>
438As you can see, unlike in Markdown, opening [[harlowe:whitespace|whitespace]] is permitted before the first #.\\
439<html><h2 class='def_title markup_title' id=markup_horizontal-rule><a class='heading_link' href=#markup_horizontal-rule></a></html>Horizontal rule markup\\
440<html></h2></html>
441
442A hr (horizontal rule) is a thin horizontal line across the entire passage. In HTML, it is a ''%%<hr>%%'' element.\\
443In Harlowe, it is an entire line consisting of 3 or more consecutive hyphens ''%%-%%''.
444
445=== Example usage: ===
446
447<code>
448 ---
449 ----
450 -----
451</code>
452Again, opening [[harlowe:whitespace|whitespace]] is permitted prior to the first ''%%-%%'' and after the final ''%%-%%''.\\
453<html><h2 class='def_title markup_title' id=markup_whitespace><a class='heading_link' href=#markup_whitespace></a></html>Whitespace markup\\
454<html></h2></html>
455
456"Whitespace" is a term that refers to "space" characters that you use to separate programming code tokens,\\
457such as the spacebar space, and the tab character. They are considered interchangeable in type and quantity -\\
458using two spaces usually has the same effect as using one space, one tab, and so forth.
459
460Harlowe tries to also recognise most forms of [[https://en.wikipedia.org/wiki/Whitespace_character#Unicode|Unicode-defined whitespace]],\\
461including the quads, the per-em and per-en spaces, but not the zero-width space characters (as they may\\
462cause confusion and syntax errors if unnoticed in your code).\\
463<html><h2 class='def_title markup_title' id=markup_collapsing-whitespace><a class='heading_link' href=#markup_collapsing-whitespace></a></html>Collapsing whitespace markup\\
464<html></h2></html>
465
466When working with macros, HTML tags and such, it's convenient for readability purposes to space and indent\\
467the text. However, this [[harlowe:whitespace|whitespace]] will also appear in the compiled passage text. You can get around this by\\
468placing the text between ''%%{%%'' and ''%%}%%'' marks. Inside, all runs of consecutive whitespace (line breaks, spaces)\\
469will be reduced to just one space.
470
471=== Example usage: ===
472
473<code>
474{
475 This sentence
476 will be
477 (set: $event to true)
478 written on one line
479 with only single spaces.
480}
481</code>
482=== Details: ===
483
484You can nest this markup within itself - ''%%{Good { gumballs!}}%%'' - but the inner pair won't behave any\\
485differently as a result of being nested.
486
487Text inside macro calls (in particular, text inside strings provided to macro) will not be collapsed.\\
488Neither will text //outputted// by macro calls, either - ''%%{(print:" ")}%%'' will still print all 3 spaces,\\
489and ''%%{(display:"Attic")}%%'' will still display all of the whitespace in the "Attic" passage.
490
491Also, text inside the verbatim syntax, such as ''%%Thunder` `hound%%'', will not be collapsed either.
492
493If the markup contains a [[harlowe:replace|(replace:)]] command attached to a hook, the hook will still have its whitespace\\
494collapsed, even if it is commanded to replace text outside of the markup.
495
496If you only want to remove specific line breaks, consider the escaped line break markup.\\
497<html><h2 class='def_title markup_title' id=markup_escaped-line-break><a class='heading_link' href=#markup_escaped-line-break></a></html>Escaped line break markup\\
498<html></h2></html>
499
500Sometimes, you may want to write an especially long line, potentially containing many macros.\\
501This may not be particularly readable in the passage editor, though. One piece of markup that\\
502may help you is the ''%%\%%'' mark - placing it just before a line break, or just after it, will cause the line break\\
503to be removed from the passage, thus "joining together" the lines.
504
505=== Example usage: ===
506
507<code>
508This line\
509and this line
510\and this line, are actually just one line.
511</code>
512=== Details: ===
513
514There must not be any [[harlowe:whitespace|whitespace]] between the ''%%\%%'' and the line break. Otherwise, it won't work.
515
516Like most passage text markup, this cannot be used inside a macro call (for instance, ''%%(print: \%%''<html><br></html>\\
517''%%3)%%'') - but since line breaks between values in macro calls are ignored, this doesn't matter.\\
518<html><h1 id=section_macro></html>List of macros<html></h1></html>
519
520<HTML>
521<h2 class='def_title macro_title' id=macro_set><a class='heading_link' href=#macro_set></a>The (set: ) macro</h2>
522<h3 class=macro_signature>(set: <i> <span class=parameter_rest>...</span>[[harlowe:VariableToValue|variabletovalue]]</i>) <span class=macro_returntype>→</span> <i>Instant</i></h3>
523</HTML>
524Stores data values in variables.
525
526=== Example usage: ===
527
528 * ''%%(set: $battlecry to "Save a " + $favouritefood + " for me!")%%'' sets a variable called $battlecry.
529 * ''%%(set: _dist to $altitude - $enemyAltitude)%%'' sets a temp variable called _dist.
530
531=== Rationale: ===
532
533Variables are data storage for your game. You can store data values under special names\\
534of your choosing, and refer to them later.
535
536There are two kinds of variables. Normal variables, whose names begin with ''%%$%%'', persist between passages,\\
537and should be used to store data that will be needed throughout the entire game. Temp variables,\\
538whose names begin with ''%%_%%'', only exist inside the hook or passage that they're first (set:), and\\
539are forgotten after the hook or passage ends. You should use temp variables if you're writing passage\\
540code that mustn't accidentally affect any other passages' variables (by using (set:) on a variable name\\
541that someone else was using for something different). This can be essential in collaborative work\\
542with other authors working on the same story independently, or when writing code to be used in multiple stories.
543
544Variables have many purposes: keeping track of what the player has accomplished,\\
545managing some other state of the story, storing hook styles and [[harlowe:changer|changer]], and\\
546other such things. You can display variables by putting them in passage text,\\
547attach them to hooks, and create and change them using the (set:) and [[harlowe:put|(put:)]] macros.
548
549=== Details: ===
550
551In its basic form, a variable is created or changed using ''%%(set:%%'' variable ''%%to%%'' value ''%%)%%''.\\
552You can also set multiple variables in a single (set:) by separating each VariableToValue\\
553with commas: ''%%(set: $weapon to 'hands', $armour to 'naked')%%'', etc.
554
555You can also use ''%%it%%'' in expressions on the right-side of ''%%to%%''. Much as in other\\
556expressions, it's a shorthand for what's on the left side: ''%%(set: $vases to it + 1)%%''\\
557is a shorthand for ''%%(set: $vases to $vases + 1)%%''.
558
559If the destination isn't something that can be changed - for instance, if you're trying to set a\\
560bare value to another value, like ''%%(set: true to 2)%%'' - then an error will be printed. This includes\\
561modifying [[harlowe:array|array]] - ''%%(set: (a:2,3)'s 1st to 1)%%'' is also an error.
562
563=== See also: ===
564
565[[harlowe:push|(push:)]], [[harlowe:move|(move:)]]\\
566<html><h2 class='def_title macro_title' id=macro_put><a class='heading_link' href=#macro_put></a></html>The (put: ) macro<html></h2></html>
567
568<HTML>
569<h3 class=macro_signature>(put: <i> <span class=parameter_rest>...</span>[[harlowe:VariableToValue|variabletovalue]]</i>) <span class=macro_returntype>→</span> <i>Instant</i></h3>
570</HTML>
571A left-to-right version of [[harlowe:set|(set:)]] that requires the word ''%%into%%'' rather than ''%%to%%''.
572
573=== Rationale: ===
574
575This macro has an identical purpose to [[harlowe:set|(set:)]] - it creates and changes variables.\\
576For a basic explanation, see the rationale for [[harlowe:set|(set:)]].
577
578Almost every programming language has a [[harlowe:set|(set:)]] construct, and most of these place the\\
579variable on the left-hand-side. However, a minority, such as HyperTalk, place the variable\\
580on the right. Harlowe allows both to be used, depending on personal preference. [[harlowe:set|(set:)]] reads\\
581as ''%%(set:%%'' variable ''%%to%%'' value ''%%)%%'', and (put:) reads as ''%%(put:%%'' value ''%%into%%'' variable ''%%)%%''.
582
583=== Details: ===
584
585Just as with [[harlowe:set|(set:)]], a variable is changed using ''%%(put:%%'' value ''%%into%%'' variable ''%%)%%''. You can\\
586also set multiple variables in a single (put:) by separating each VariableToValue\\
587with commas: ''%%(put: 2 into $batteries, 4 into $bottles)%%'', etc.
588
589''%%it%%'' can also be used with (put:), but, interestingly, it's used on the right-hand side of\\
590the expression: ''%%(put: $eggs + 2 into it)%%''.
591
592=== See also: ===
593
594[[harlowe:set|(set:)]], [[harlowe:move|(move:)]]\\
595<html><h2 class='def_title macro_title' id=macro_move><a class='heading_link' href=#macro_move></a></html>The (move: ) macro<html></h2></html>
596
597<HTML>
598<h3 class=macro_signature>(move: <i> <span class=parameter_rest>...</span>[[harlowe:VariableToValue|variabletovalue]]</i>) <span class=macro_returntype>→</span> <i>Instant</i></h3>
599</HTML>
600A variant of [[harlowe:put|(put:)]] that deletes the source value after copying it - in effect\\
601moving the value from the source to the destination.
602
603=== Example usage: ===
604
605''%%(move: $arr's 1st into $var)%%''
606
607=== Rationale: ===
608
609You'll often use data structures such as [[harlowe:array|array]] or [[harlowe:datamap|datamap]] as storage for values\\
610that you'll only use once, such as a list of names to print out. When it comes time\\
611to use them, you can remove it from the structure and retrieve it in one go.
612
613=== Details: ===
614
615You must use the ''%%into%%'' keyword, like [[harlowe:put|(put:)]], with this macro. This is because, like [[harlowe:put|(put:)]],\\
616the destination of the value is on the right, whereas the source is on the left.
617
618You can also set multiple variables in a single (move:) by separating each VariableToValue\\
619with commas: ''%%(move: $a's 1st into $b, $a's 2nd into $c)%%'', etc.
620
621If the value you're accessing cannot be removed - for instance, if it's an array's ''%%length%%'' -\\
622then an error will be produced.
623
624=== See also: ===
625
626[[harlowe:push|(push:)]], [[harlowe:set|(set:)]]\\
627<html><h2 class='def_title macro_title' id=macro_print><a class='heading_link' href=#macro_print></a></html>The (print: ) macro<html></h2></html>
628
629<HTML>
630<h3 class=macro_signature>(print: <i> Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
631</HTML>
632This [[harlowe:command|command]] prints out any single argument provided to it, as text.
633
634=== Example usage: ===
635
636''%%(print: $var + "s")%%''
637
638=== Details: ===
639
640It is capable of printing things which [[harlowe:text|(text:)]] cannot convert to a [[harlowe:string|string]],\\
641such as [[harlowe:changer|changer]] commands - but these will usually become bare descriptive\\
642text like ''%%[A (font: ) command]%%''. You may find this useful for debugging purposes.
643
644This command can be stored in a variable instead of being performed immediately.\\
645Notably, the expression to print is stored inside the command, instead of being\\
646re-evaluated when it is finally performed. So, a passage\\
647that contains:
648
649<code>
650(set: $name to "Dracula")
651(set: $p to (print: "Count " + $name))
652(set: $name to "Alucard")
653$p
654</code>
655will still result in the text ''%%Count Dracula%%''. This is not particularly useful\\
656compared to just setting ''%%$p%%'' to a string, but is available nonetheless.
657
658=== See also: ===
659
660[[harlowe:text|(text:)]], [[harlowe:display|(display:)]]\\
661<html><h2 class='def_title macro_title' id=macro_display><a class='heading_link' href=#macro_display></a></html>The (display: ) macro<html></h2></html>
662
663<HTML>
664<h3 class=macro_signature>(display: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
665</HTML>
666This [[harlowe:command|command]] writes out the contents of the passage with the given [[harlowe:string|string]] name.\\
667If a passage of that name does not exist, this produces an error.
668
669=== Example usage: ===
670
671''%%(display: "Cellar")%%'' prints the contents of the passage named "Cellar".
672
673=== Rationale: ===
674
675Suppose you have a section of code or source that you need to include in several different\\
676passages. It could be a status display, or a few lines of descriptive text. Instead of\\
677manually copy-pasting it into each passage, consider placing it all by itself in another passage,\\
678and using (display:) to place it in every passage. This gives you a lot of flexibility: you can,\\
679for instance, change the code throughout the story by just editing the displayed passage.
680
681=== Details: ===
682
683Text-targeting macros (such as [[harlowe:replace|(replace:)]]) inside the\\
684displayed passage will affect the text and hooks in the outer passage\\
685that occur earlier than the (display:) command. For instance,\\
686if passage A contains ''%%(replace:"Prince")[Frog]%%'', then another passage\\
687containing ''%%Princes(display:'A')%%'' will result in the text ''%%Frogs%%''.
688
689Like all commands, this can be set into a variable. It's not particularly\\
690useful in that state, but you can use that variable in place of that command,\\
691such as writing ''%%$var%%'' in place of ''%%(display: "Yggdrasil")%%''.\\
692<html><h2 class='def_title macro_title' id=macro_if><a class='heading_link' href=#macro_if></a></html>The (if: ) macro<html></h2></html>
693
694<HTML>
695<h3 class=macro_signature>(if: <i> [[harlowe:Boolean|boolean]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
696</HTML>
697This macro accepts only [[harlowe:boolean|boolean]], and produces a [[harlowe:command|command]] that can be attached to hooks\\
698to hide them "if" the value was false.
699
700=== Example usage: ===
701
702''%%(if: $legs is 8)[You're a spider!]%%'' will show the ''%%You're a spider!%%'' hook if ''%%$legs%%'' is ''%%8%%''.\\
703Otherwise, it is not run.
704
705=== Rationale: ===
706
707In a story with multiple paths or threads, where certain events could occur or not occur,\\
708it's common to want to run a slightly modified version of a passage reflecting the current\\
709state of the world. The (if:), [[harlowe:unless|(unless:)]], [[harlowe:else-if|(else-if:)]] and [[harlowe:else|(else:)]] macros let these modifications be\\
710switched on or off depending on variables, comparisons or calculations of your choosing.
711
712=== Details: ===
713
714Note that the (if:) macro only runs once, when the passage or hook containing it is rendered. Any\\
715future change to the condition (such as a [[harlowe:link|(link:)]] containing a [[harlowe:set|(set:)]] that changes a variable) won't\\
716cause it to "re-run", and show/hide the hook anew.
717
718However, if you attach (if:) to a named hook, and the (if:) hides the hook, you can manually reveal\\
719the hook later in the passage (such as, after a [[harlowe:link|(link:)]] has been clicked) by using the [[harlowe:show|(show:)]] macro\\
720to target the hook. Named hooks hidden with (if:) are thus equivalent to hidden named hooks like ''%%|this)[]%%''.
721
722=== Alternatives: ===
723
724The (if:) and [[harlowe:hidden|(hidden:)]] macros are not the only attachment that can hide or show hooks! In fact,\\
725a variable that contains a boolean can be used in its place. For example:
726
727<code>
728(set: $isAWizard to $foundWand and $foundHat and $foundBeard)
729
730$isAWizard[You wring out your beard with a quick twisting spell.]
731You step into the ruined library.
732$isAWizard[The familiar scent of stale parchment comforts you.]
733</code>
734By storing a boolean inside ''%%$isAWizard%%'', it can be used repeatedly throughout the story to\\
735hide or show hooks as you please.
736
737=== See also: ===
738
739[[harlowe:unless|(unless:)]], [[harlowe:else-if|(else-if:)]], [[harlowe:else|(else:)]], [[harlowe:hidden|(hidden:)]]\\
740<html><h2 class='def_title macro_title' id=macro_unless><a class='heading_link' href=#macro_unless></a></html>The (unless: ) macro<html></h2></html>
741
742<HTML>
743<h3 class=macro_signature>(unless: <i> [[harlowe:Boolean|boolean]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
744</HTML>
745This macro is the negated form of [[harlowe:if|(if:)]]: it accepts only [[harlowe:boolean|boolean]], and returns\\
746a [[harlowe:command|command]] that can be attached hooks to hide them "if" the value was true.
747
748For more information, see the documentation of [[harlowe:if|(if:)]].\\
749<html><h2 class='def_title macro_title' id=macro_else-if><a class='heading_link' href=#macro_else-if></a></html>The (else-if: ) macro<html></h2></html>
750
751<HTML>
752<h3 class=macro_signature>(else-if: <i> [[harlowe:Boolean|boolean]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
753</HTML>
754This macro's result changes depending on whether the previous hook in the passage\\
755was shown or hidden. If the previous hook was shown, then this [[harlowe:command|command]] hides the attached\\
756hook. Otherwise, it acts like [[harlowe:if|(if:)]], showing the attached hook if it's true, and hiding it\\
757if it's false. If there was no preceding hook before this, then an error message will be printed.
758
759=== Example usage: ===
760
761<code>
762Your stomach makes {
763(if: $size is 'giant')[
764Â Â Â Â an intimidating rumble!
765](else-if: $size is 'big')[
766Â Â Â Â a loud growl
767](else:​)[
768Â Â Â Â a faint gurgle
769]}.
770</code>
771=== Rationale: ===
772
773If you use the [[harlowe:if|(if:)]] macro, you may find you commonly use it in forked branches of\\
774source: places where only one of a set of hooks should be displayed. In order to\\
775make this so, you would have to phrase your [[harlowe:if|(if:)]] expressions as "if A happened",\\
776"if A didn't happen and B happened", "if A and B didn't happen and C happened", and so forth,\\
777in that order.
778
779The (else-if:) and [[harlowe:else|(else:)]] macros are convenient variants of [[harlowe:if|(if:)]] designed to make this easier: you\\
780can merely say "if A happened", "else, if B happened", "else, if C happened" in your code.
781
782=== Details: ===
783
784Just like the [[harlowe:if|(if:)]] macro, (else-if:) only checks its condition once, when the passage or hook contaning\\
785it is rendered.
786
787The (else-if:) and [[harlowe:else|(else:)]] macros do not need to only be paired with [[harlowe:if|(if:)]]! You can use (else-if:) and\\
788[[harlowe:else|(else:)]] in conjunction with [[harlowe:boolean|boolean]] variables, like so:
789
790<code>
791$married[You hope this warrior will someday find the sort of love you know.]
792(else-if: not $date)[You hope this warrior isn't doing anything this Sunday (because
793you've got overtime on Saturday.)]
794</code>
795If you attach (else-if:) to a named hook, and the (else-if:) hides the hook, you can reveal the hook later\\
796in the passage by using the [[harlowe:show|(show:)]] macro to target the hook.
797
798=== See also: ===
799
800[[harlowe:if|(if:)]], [[harlowe:unless|(unless:)]], [[harlowe:else|(else:)]], [[harlowe:hidden|(hidden:)]]\\
801<html><h2 class='def_title macro_title' id=macro_else><a class='heading_link' href=#macro_else></a></html>The (else: ) macro<html></h2></html>
802
803<HTML>
804<h3 class=macro_signature>(else: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
805</HTML>
806This is a convenient limited variant of the [[harlowe:else-if|(else-if:)]] macro. It will simply show\\
807the attached hook if the preceding hook was hidden, and hide it otherwise.\\
808If there was no preceding hook before this, then an error message will be printed.
809
810=== Rationale: ===
811
812After you've written a series of hooks guarded by [[harlowe:if|(if:)]] and [[harlowe:else-if|(else-if:)]], you'll often have one final\\
813branch to show, when none of the above have been shown. (else:) is the "none of the above" variant\\
814of [[harlowe:else-if|(else-if:)]], which needs no [[harlowe:boolean|boolean]] expression to be provided. It's essentially the same as\\
815''%%(else-if: true)%%'', but shorter and more readable.
816
817For more information, see the documentation of [[harlowe:else-if|(else-if:)]].
818
819=== Notes: ===
820
821Just like the [[harlowe:if|(if:)]] macro, (else:) only checks its condition once, when the passage or hook contaning\\
822it is rendered.
823
824Due to a mysterious quirk, it's possible to use multiple (else:) macro calls in succession:
825
826<code>
827$isUtterlyEvil[You suddenly grip their ankles and spread your warm smile into a searing smirk.]
828(else:​)[In silence, you gently, reverently rub their soles.]
829(else:​)[Before they can react, you unleash a typhoon of tickles!]
830(else:​)[They sigh contentedly, filling your pious heart with joy.]
831</code>
832This usage can result in a somewhat puzzling passage source structure, where each (else:) hook\\
833alternates between visible and hidden depending on the first such hook. So, it is best avoided.
834
835If you attach (else:) to a named hook, and the (else:) hides the hook, you can reveal the hook later\\
836in the passage by using the [[harlowe:show|(show:)]] macro to target the hook.
837
838=== See also: ===
839
840[[harlowe:if|(if:)]], [[harlowe:unless|(unless:)]], [[harlowe:else-if|(else-if:)]], [[harlowe:hidden|(hidden:)]]\\
841<html><h2 class='def_title macro_title' id=macro_for><a class='heading_link' href=#macro_for></a></html>The (for: ) macro<html></h2></html>
842
843<HTML>
844<h3 class=macro_signature>(for: <i> [[harlowe:Lambda|lambda]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
845</HTML>
846Also known as: [[harlowe:loop|(loop:)]]
847
848A [[harlowe:command|command]] that repeats the attached hook, setting a temporary variable to a different value on each repeat.
849
850=== Example usage: ===
851
852 * ''%%(for: each _item, ...$arr) [You have the _item.]%%'' prints "You have the " and the item, for each item in $arr.
853 * ''%%(for: _ingredient where it contains "petal", ...$reagents) [Cook the _ingredient?]%%'' prints "Cook the " and the [[harlowe:string|string]], for\\
854each string in $reagents which contains "petal".
855
856=== Rationale: ===
857
858Suppose you're using [[harlowe:array|array]] to store strings representing inventory items, or character [[harlowe:datamap|datamap]],\\
859or other kinds of sequential game information - or even just built-in arrays like [[harlowe:history|(history:)]] - and you\\
860want to print out a sentence or paragraph for each item. The (for:) macro can be used to print something "for each"\\
861item in an array easily - simply write a hook using a temp variable where each item should be printed or used,\\
862then give (for:) an "each" [[harlowe:lambda|lambda]] that uses the same temp variable.
863
864=== Details: ===
865
866Don't make the mistake of believing you can alter an array by trying to [[harlowe:set|(set:)]] the temp variable in each loop - such\\
867as ''%%(for: each _a, ...$arr)[(set: _a to it + 1)]%%''. This will NOT change $arr - only the temp variable will change (and\\
868only until the next loop, where another $arr value will be put into it). If you want to alter an array item-by-item, use\\
869the [[harlowe:altered|(altered:)]] macro.
870
871The temp variable inside the hook will shadow any other identically-named temp variables outside of it: if you\\
872''%%(set: _a to 1)%%'', then ''%%(for: each _a, 2,3)[ (print: _a) ]%%'', the inner hook will print "2" and "3", and you won't be\\
873able to print or set the "outer" _a.
874
875You may want to simply print several copies of a hook a certain [[harlowe:number|number]] of times, without any particular\\
876array data being looped over. You can use the [[harlowe:range|(range:)]] macro with it instead: ''%%(for: each _i in ...(range:1,10))%%'', and\\
877not use the temp variable inside the hook at all.
878
879As it is a [[harlowe:changer|changer]] macro, (for:)'s value is a changer command which can be stored in a variable - this command stores all\\
880of the values originally given to it, and won't reflect any changes to the values, or their container arrays, since then.
881
882=== Alternatives: ===
883
884You may be tempted to use (for:) not to print anything at all, but to find values inside arrays using [[harlowe:if|(if:)]], or\\
885form a "total" using [[harlowe:set|(set:)]]. The lambda macros [[harlowe:find|(find:)]] and [[harlowe:folded|(folded:)]], while slightly less straightforward,\\
886are recommended to be used instead.
887
888=== See also: ===
889
890[[harlowe:find|(find:)]], [[harlowe:folded|(folded:)]], [[harlowe:if|(if:)]]\\
891<html><h2 class='def_title macro_title' id=macro_either><a class='heading_link' href=#macro_either></a></html>The (either: ) macro<html></h2></html>
892
893<HTML>
894<h3 class=macro_signature>(either: <i> <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>Any</i></h3>
895</HTML>
896Give this macro several values, separated by commas, and it will pick and return\\
897one of them randomly.
898
899=== Example usage: ===
900
901''%%A (either: "slimy", "goopy", "slippery") puddle%%'' will randomly be "A slimy puddle", "A goopy puddle"\\
902or "A slippery puddle".
903
904=== Rationale: ===
905
906There are plenty of occasions where you might want random elements in your story: a few random adjectives\\
907or flavour text lines to give repeated play-throughs variety, for instance, or a few random links for a "maze"\\
908area. For these cases, you'll probably want to simply select from a few possibilities. The (either:)\\
909macro provides this functionality.
910
911=== Details: ===
912
913As with many macros, you can use the spread ''%%...%%'' operator to place all of the values in an [[harlowe:array|array]] or [[harlowe:dataset|dataset]]\\
914into (either:), and pick them randomly. ''%%(either: ...$array)%%'', for instance, will choose one possibility from\\
915all of the array contents.
916
917If you want to pick two or more values randomly, you may want to use the [[harlowe:shuffled|(shuffled:)]] macro, and extract a subarray\\
918from its result.
919
920=== See also: ===
921
922[[harlowe:random|(random:)]], [[harlowe:shuffled|(shuffled:)]]\\
923<html><h2 class='def_title macro_title' id=macro_enchant><a class='heading_link' href=#macro_enchant></a></html>The (enchant: ) macro<html></h2></html>
924
925<HTML>
926<h3 class=macro_signature>(enchant: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]], [[harlowe:Changer|changer]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
927</HTML>
928Applies a [[harlowe:changer|changer]] to every occurrence of a hook or [[harlowe:string|string]] in a passage, and continues applying that changer to any further\\
929occurrences that are made to appear in the same passage later.
930
931=== Example usage: ===
932
933 * ''%%(enchant: "gold", (text-colour: yellow) + (text-style:'bold'))%%'' makes all occurrences of "gold" in the text be bold and yellow.
934 * ''%%(enchant: ?dossier, (link: "Click to read"))%%'' makes all the hooks named "dossier" be hidden behind links reading\\
935"Click to read".
936
937=== Rationale: ===
938
939While changers allow you to style or transform certain hooks in a passage, it can be tedious and error-prone to attach them to every\\
940occurrence as you're writing your story, especially if the attached changers are complicated. You can\\
941simplify this by storing changers in short variables, and attaching just the variables, like so:
942
943<code>
944(set: _ghost to (text-style:'outline'))
945_ghost[Awoo]
946_ghost[Ooooh]
947</code>
948Nevertheless, this can prove undesirable: you may want to remove the _ghost styling later in development, which would\\
949force you to remove the attached variables to avoid producing an error; you may want to only style a single word or phrase,\\
950and find it inconvenient to place it in a hook; you may simply not like having code, like that [[harlowe:set|(set:)]] macro,\\
951be at the start of your passage; you may not want to keep track of which variables hold which changers, given the possibility (if\\
952you're using normal variables) that they could be changed previously in the story.
953
954Instead, you can give the hooks the name "ghost", and then (enchant:) them afterward like so:
955
956<code>
957|ghost>[Awoo]
958|ghost>[Ooooh]
959(enchant: ?ghost, (text-style:'outline'))
960</code>
961The final (enchant:) macro can target words instead of hooks, much like [[harlowe:click|(click:)]] - simply provide a string instead of a hook name.
962
963This macro works well in "header" tagged passages - using a lot of (enchant:) [[harlowe:command|command]] to style certain words or parts of\\
964every passage, you can essentially write a "styling language" for your story, where certain hook names "mean" certain [[harlowe:colour|colour]] or\\
965behaviour. (This is loosely comparable to using CSS to style class names, but exclusively uses macros.)
966
967=== Details: ===
968
969As with [[harlowe:click|(click:)]], the "enchantment" affects the text produced by [[harlowe:display|(display:)]] macros, and any hooks changed by [[harlowe:replace|(replace:)]] etc. in the future,\\
970until the player makes their next turn.
971
972The built-in hook names, ?Page, ?Passage, ?Sidebar and ?Link, can be targeted by this macro, and can be styled on a per-passage basis this way.
973
974=== See also: ===
975
976[[harlowe:click|(click:)]]\\
977<html><h2 class='def_title macro_title' id=macro_hsl><a class='heading_link' href=#macro_hsl></a></html>The (hsl: ) macro<html></h2></html>
978
979<HTML>
980<h3 class=macro_signature>(hsl: <i> [[harlowe:Number|number]], Number, Number</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Colour|colour]]</i></h3>
981</HTML>
982This macro creates a [[harlowe:colour|colour]] using the given hue (h) angle in degrees, as well as the given\\
983saturation (s) and lightness (l) percentages.
984
985=== Example usage: ===
986
987 * ''%%(hsl: 120, 0.8, 0.5)%%'' produces a colour with 120 degree hue, 80% saturation and 50% lightness.
988 * ''%%(hsl: 28, 1, 0.4)'s h%%'' produces the [[harlowe:number|number]] 28.
989
990=== Rationale: ===
991
992The HSL colour model is regarded as easier to work with than the RGB model used for HTML hexadecimal\\
993notation and the [[harlowe:rgb|(rgb:)]] macro. Being able to set the hue with one number instead of three, for\\
994instance, lets you control the hue using a single variable, and alter it at will.
995
996=== Details: ===
997
998This macro takes the same range of numbers as the CSS ''%%hsl()%%'' function.
999
1000Giving saturation or lightness values higher than 1 or lower than 0 will cause an error. However,\\
1001you can give any kind of hue number to (hsl:), and it will automatically round it to fit the 0-359\\
1002degree range. This allows you to cycle through hues easily by providing a steadily increasing variable or\\
1003a counter, such as ''%%(hsl: time / 100, 1, 0.5)%%''.
1004
1005=== See also: ===
1006
1007[[harlowe:rgb|(rgb:)]], [[harlowe:rgba|(rgba:)]], [[harlowe:hsla|(hsla:)]]\\
1008<html><h2 class='def_title macro_title' id=macro_hsla><a class='heading_link' href=#macro_hsla></a></html>The (hsla: ) macro<html></h2></html>
1009
1010<HTML>
1011<h3 class=macro_signature>(hsla: <i> [[harlowe:Number|number]], Number, Number, Number</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Colour|colour]]</i></h3>
1012</HTML>
1013A special version of [[harlowe:hsl|(hsl:)]], this macro allows you to supply not just the hue (h) angle in\\
1014degrees, saturation (s) and lightness (l) percentages, but also the transparency\\
1015(alpha, or a) percentage, which is a fractional value between 0 (fully transparent)\\
1016and 1 (fully visible).
1017
1018Anything drawn with a partially transparent [[harlowe:colour|colour]] will itself be partially transparent. You\\
1019can then layer such elements to produce a few interesting visual effects.
1020
1021=== Example usage: ===
1022
1023''%%(hsla: 120, 0.5, 0.8, 0.6)%%'' produces a 40% transparent faint green.
1024
1025=== Details: ===
1026
1027This macro takes the same range of [[harlowe:number|number]] as the CSS ''%%rgba()%%'' function.
1028
1029Giving alpha percentages higher than 1 or lower than 0 will cause an error.
1030
1031=== See also: ===
1032
1033[[harlowe:rgb|(rgb:)]], [[harlowe:rgba|(rgba:)]], [[harlowe:hsl|(hsl:)]]\\
1034<html><h2 class='def_title macro_title' id=macro_rgb><a class='heading_link' href=#macro_rgb></a></html>The (rgb: ) macro<html></h2></html>
1035
1036<HTML>
1037<h3 class=macro_signature>(rgb: <i> [[harlowe:Number|number]], Number, Number</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Colour|colour]]</i></h3>
1038</HTML>
1039This macro creates a [[harlowe:colour|colour]] using the three red (r), green (g) and blue (b) values\\
1040provided, whose values are whole [[harlowe:number|number]] between 0 and 255.
1041
1042=== Example usage: ===
1043
1044 * ''%%(rgb: 255, 0, 47)%%'' produces a colour with 255 red, 0 blue and 47 green.
1045 * ''%%(rgb: 90, 0, 0)'s r%%'' produces the number 90.
1046
1047=== Rationale: ===
1048
1049The RGB additive colour model is commonly used for defining colours: the HTML\\
1050hexadecimal notation for colours (such as #9263AA) simply consists of three hexadecimal\\
1051values placed together. This macro allows you to create such colours computationally,\\
1052by providing variables for certain components.
1053
1054=== Details: ===
1055
1056This macro takes the same range of numbers as the CSS ''%%rgb()%%'' function.
1057
1058Giving values higher than 255 or lower than 0, or with a fractional part,\\
1059will cause an error.
1060
1061=== See also: ===
1062
1063[[harlowe:rgba|(rgba:)]], [[harlowe:hsl|(hsl:)]], [[harlowe:hsla|(hsla:)]]\\
1064<html><h2 class='def_title macro_title' id=macro_rgba><a class='heading_link' href=#macro_rgba></a></html>The (rgba: ) macro<html></h2></html>
1065
1066<HTML>
1067<h3 class=macro_signature>(rgba: <i> [[harlowe:Number|number]], Number, Number, Number</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Colour|colour]]</i></h3>
1068</HTML>
1069A special version of [[harlowe:rgb|(rgb:)]], this macro allows you to supply not just the red (r),\\
1070green (g) and blue (b) values, but also the transparency (alpha, or a) percentage, which\\
1071is a fractional value between 0 (fully transparent) and 1 (fully visible).
1072
1073Anything drawn with a partially transparent [[harlowe:colour|colour]] will itself be partially transparent. You\\
1074can then layer such elements to produce a few interesting visual effects.
1075
1076=== Example usage: ===
1077
1078''%%(rgba: 178, 229, 178, 0.6)%%'' produces a 40% transparent faint green.
1079
1080=== Details: ===
1081
1082This macro takes the same range of [[harlowe:number|number]] as the CSS ''%%rgba()%%'' function.
1083
1084Giving alpha percentages higher than 1 or lower than 0 will cause an error.
1085
1086=== See also: ===
1087
1088[[harlowe:rgb|(rgb:)]], [[harlowe:hsl|(hsl:)]], [[harlowe:hsla|(hsla:)]]\\
1089<html><h2 class='def_title macro_title' id=macro_a><a class='heading_link' href=#macro_a></a></html>The (a: ) macro<html></h2></html>
1090
1091<HTML>
1092<h3 class=macro_signature>(a: <i> <span class=parameter_optional>\[</span><span class=parameter_rest>...</span>Any<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1093</HTML>
1094Also known as: [[harlowe:array|(array:)]]
1095
1096Creates an [[harlowe:array|array]], which is an ordered collection of values.
1097
1098=== Example usage: ===
1099
1100''%%(a:)%%'' creates an empty array, which could be filled with other values later.\\
1101''%%(a: "gold", "frankincense", "myrrh")%%'' creates an array with three [[harlowe:string|string]].\\
1102This is also a valid array, but with its elements spaced in a way that makes them more readable:
1103
1104<code>
1105(a:
1106"You didn't sleep in the tiniest bed",
1107"You never ate the just-right porridge",
1108"You never sat in the smallest chair",
1109)
1110</code>
1111=== Rationale: ===
1112
1113For an explanation of what arrays are, see the Array article. This macro is the primary\\
1114means of creating arrays - simply supply the values to it, in order.
1115
1116=== Details: ===
1117
1118Note that due to the way the spread ''%%...%%'' operator works, spreading an array into\\
1119the (a:) macro will accomplish nothing: ''%%(a: ...$array)%%'' is the same as just the ''%%$array%%''.
1120
1121=== See also: ===
1122
1123[[harlowe:dm|(dm:)]], [[harlowe:ds|(ds:)]]\\
1124<html><h2 class='def_title macro_title' id=macro_dm><a class='heading_link' href=#macro_dm></a></html>The (dm: ) macro<html></h2></html>
1125
1126<HTML>
1127<h3 class=macro_signature>(dm: <i> <span class=parameter_optional>\[</span><span class=parameter_rest>...</span>Any<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Datamap|datamap]]</i></h3>
1128</HTML>
1129Also known as: [[harlowe:datamap|(datamap:)]]
1130
1131Creates a [[harlowe:datamap|datamap]], which is a data structure that pairs [[harlowe:string|string]] names with data values.\\
1132You should provide a string name, followed by the value paired with it, and then another\\
1133string name, another value, and so on, for as many as you'd like.
1134
1135=== Example usage: ===
1136
1137''%%(dm:)%%'' creates an empty datamap.\\
1138''%%(dm: "Cute", 4, "Wit", 7)%%'' creates a datamap with two names and values.\\
1139The following code also creates a datamap, with the names and values laid out in a readable fashion:
1140
1141<code>
1142(dm:
1143"Susan", "A petite human in a yellow dress",
1144"Tina", "A ten-foot lizardoid in a three-piece suit",
1145"Gertie", "A griffin draped in a flowing cape",
1146)
1147</code>
1148=== Rationale: ===
1149
1150For an explanation of what datamaps are, see the Datamap article.\\
1151This macro is the primary means of creating datamaps - simply supply a name,\\
1152followed by a value, and so on.
1153
1154In addition to creating datamaps for long-term use, this is also used to\\
1155create "momentary" datamaps which are used only in some operation. For instance,\\
1156to add several values to a datamap at once, you can do something like this:
1157
1158<code>
1159(set: $map to it + (dm: "Name 1", "Value 1", "Name 2", "Value 2"))
1160</code>
1161You can also use (dm:) as a kind of "multiple choice" structure, if you combine it with\\
1162the ''%%'s%%'' or ''%%of%%'' syntax. For instance...
1163
1164<code>
1165(set: $element to $monsterName of (dm:
1166"Chilltoad", "Ice",
1167"Rimeswan", "Ice",
1168"Brisketoid", "Fire",
1169"Slime", "Water"
1170))
1171</code>
1172...will set $element to one of those elements if $monsterName matches the correct name. But, be warned: if\\
1173none of those names matches $monsterName, an error will result.
1174
1175=== See also: ===
1176
1177[[harlowe:a|(a:)]], [[harlowe:ds|(ds:)]]\\
1178<html><h2 class='def_title macro_title' id=macro_ds><a class='heading_link' href=#macro_ds></a></html>The (ds: ) macro<html></h2></html>
1179
1180<HTML>
1181<h3 class=macro_signature>(ds: <i> <span class=parameter_optional>\[</span><span class=parameter_rest>...</span>Any<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Dataset|dataset]]</i></h3>
1182</HTML>
1183Also known as: [[harlowe:dataset|(dataset:)]]
1184
1185Creates a [[harlowe:dataset|dataset]], which is an unordered collection of unique values.
1186
1187=== Example usage: ===
1188
1189''%%(ds:)%%'' creates an empty dataset, which could be filled with other values later.\\
1190''%%(ds: "gold", "frankincense", "myrrh")%%'' creates a dataset with three [[harlowe:string|string]].
1191
1192=== Rationale: ===
1193
1194For an explanation of what datasets are, see the Dataset article. This macro is the primary\\
1195means of creating datasets - simply supply the values to it, in any order you like.
1196
1197=== Details: ===
1198
1199You can also use this macro to remove duplicate values from an [[harlowe:array|array]] (though also eliminating the array's\\
1200order) by using the spread ''%%...%%'' operator like so: ''%%(a: ...(ds: ...$array))%%''.
1201
1202=== See also: ===
1203
1204[[harlowe:dm|(dm:)]], [[harlowe:a|(a:)]]\\
1205<html><h2 class='def_title macro_title' id=macro_all-pass><a class='heading_link' href=#macro_all-pass></a></html>The (all-pass: ) macro<html></h2></html>
1206
1207<HTML>
1208<h3 class=macro_signature>(all-pass: <i> [[harlowe:Lambda|lambda]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Boolean|boolean]]</i></h3>
1209</HTML>
1210This takes a "where" [[harlowe:lambda|lambda]] and a series of values, and evaluates to true if the lambda, when run using each value, always evaluated to true.
1211
1212=== Example usage: ===
1213
1214 * ''%%(all-pass: _num where _num > 1 and _num < 14, 6, 8, 12, 10, 9)%%'' is true.
1215 * ''%%(all-pass: _room where "Egg" is not in _room's objs, ...$rooms)%%'' is true if each [[harlowe:datamap|datamap]] in $rooms doesn't have the [[harlowe:string|string]] ''%%"Egg"%%'' in its "objs".
1216
1217=== Rationale: ===
1218
1219While the ''%%contains%%'' and ''%%is in%%'' operators can be used to quickly check if a sequence of values contains an exact value or values, you'll\\
1220often find yourself wanting to check that the values in a sequence merely resemble a kind of value - for instance, that they're positive\\
1221[[harlowe:number|number]], or strings beginning with "E".
1222
1223The (all-pass:) macro lets you perform these checks easily using a lambda, identical to that used with [[harlowe:find|(find:)]] - simply write a "temp variable\\
1224''%%where%%'' a condition" expression, and every value will be put into the temp variable one by one, and the condition checked for each.
1225
1226=== Details: ===
1227
1228Of course, if any condition should cause an error, such as checking if a number contains a number, then the error will appear.
1229
1230The temp variable, which you can name anything you want, is controlled entirely by the lambda - it doesn't exist\\
1231outside of it, it won't alter identically-named temp variables outside of it, and you can't manually [[harlowe:set|(set:)]]\\
1232it within the lambda.
1233
1234You can refer to other variables, including other temp variables, in the ''%%where%%'' condition. For instance, you can\\
1235write ''%%(set: _name to "Eva")(all-pass: _item where _item is _name, "Evan", "Eve", "Eva")%%''. However, for obvious reasons,\\
1236if the outer temp variable is named the same as the lambda's temp variable, it can't be referred to in the condition.
1237
1238=== See also: ===
1239
1240[[harlowe:sorted|(sorted:)]], [[harlowe:count|(count:)]], [[harlowe:find|(find:)]], [[harlowe:some-pass|(some-pass:)]], [[harlowe:none-pass|(none-pass:)]]\\
1241<html><h2 class='def_title macro_title' id=macro_altered><a class='heading_link' href=#macro_altered></a></html>The (altered: ) macro<html></h2></html>
1242
1243<HTML>
1244<h3 class=macro_signature>(altered: <i> [[harlowe:Lambda|lambda]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1245</HTML>
1246This takes a "via" [[harlowe:lambda|lambda]] and a sequence of values, and creates a new [[harlowe:array|array]] with the same values in the same order,\\
1247but altered via the operation in the lambda's "via" clause.
1248
1249=== Example usage: ===
1250
1251 * ''%%(altered: _monster via "Dark " + _monster, "Wolf", "Ape", "Triffid")%%'' produces ''%%(a: "Dark Wolf", "Dark Ape", "Dark Triffid")%%''
1252 * ''%%(altered: _player via _player + (dm: "HP", _player's HP - 1), ...$players)%%'' produces an array of $players [[harlowe:datamap|datamap]] whose "HP" datavalue is decreased by 1.
1253
1254=== Rationale: ===
1255
1256Transforming entire arrays or [[harlowe:dataset|dataset]], performing an operation on every item at once, allows arrays to be modified with the same ease\\
1257that single values can - just as you can add some extra text to a [[harlowe:string|string]] with a single +, so too can you add extra text to an entire\\
1258array of strings using a single call to (altered:).
1259
1260This macro uses a lambda (which is just the "temp variable ''%%via%%'' an expression" expression) to take each item in the sequence and produce a new\\
1261value to populate the resulting array. For ''%%(altered: _a via _a + 1, 10,20,30)%%'' it will produce 10 + 1, 20 + 1 and 30 + 1, and put those\\
1262into a new array.
1263
1264=== Details: ===
1265
1266Of course, if any operation applied to any of the values should cause an error, such as trying to add a string to a [[harlowe:number|number]],\\
1267an error will result.
1268
1269The temp variable, which you can name anything you want, is controlled entirely by the lambda - it doesn't exist\\
1270outside of it, it won't alter identically-named temp variables outside of it, and you can't manually [[harlowe:set|(set:)]]\\
1271it within the lambda.
1272
1273You can refer to other variables, including other temp variables, in the ''%%via%%'' expression. For instance, you can write\\
1274''%%(altered: _object via _playerName + "'s " + _object, "Glove", "Hat", "Purse")%%''. However, for obvious reasons,\\
1275if the outer temp variable is named the same as the lambda's temp variable, it can't be referred to in the expression.
1276
1277If no values are given to (altered:) except for the lambda, an empty array will be produced.
1278
1279=== See also: ===
1280
1281[[harlowe:for|(for:)]], [[harlowe:folded|(folded:)]]\\
1282<html><h2 class='def_title macro_title' id=macro_count><a class='heading_link' href=#macro_count></a></html>The (count: ) macro<html></h2></html>
1283
1284<HTML>
1285<h3 class=macro_signature>(count: <i> [[harlowe:Array|array]] or [[harlowe:String|string]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Number|number]]</i></h3>
1286</HTML>
1287Accepts a [[harlowe:string|string]] or [[harlowe:array|array]], followed by a value, and produces the [[harlowe:number|number]] of times any of the values\\
1288are inside the string or array.
1289
1290=== Example usage: ===
1291
1292''%%(count: (a:1,2,3,2,1), 1, 2)%%'' produces 4.\\
1293''%%(count: "Though", "ugh","u","h")%%'' produces 4.
1294
1295=== Rationale: ===
1296
1297You can think of this macro as being like the ''%%contains%%'' operator, but more powerful.\\
1298While ''%%contains%%'' produces ''%%true%%'' or ''%%false%%'' if occurrences of the right side\\
1299appear in the left side, (count:) produces the actual number of occurrences.
1300
1301Note that if you only want to check if an array or string contains any or all of the\\
1302values, it's easier to use ''%%contains%%'' with the ''%%all%%'' property like so: ''%%$arr contains all of (a:1,2)%%''\\
1303and ''%%$arr contains any of (a:1,2)%%''. But, if you need an exact figure for the number of occurrences,\\
1304this macro will be of use.
1305
1306=== Details: ===
1307
1308If you use this with a number, [[harlowe:boolean|boolean]], [[harlowe:datamap|datamap]], [[harlowe:dataset|dataset]] (which can't have duplicates),\\
1309or anything else which can't have a value, then an error will result.
1310
1311If you use this with a string, and the values aren't also strings, then an error will result.
1312
1313Substrings are counted separately from each other - that is, the string "Though" contains "ugh" once and "h"\\
1314once, and ''%%(count: "Though","ugh","h")%%'' results in 3. To check for "h" occurrences that are not contained in "ugh",\\
1315you can try subtracting two (count:)s - ''%%(count: "Though","ugh") - (count: "Though","h")%%'' produces 1.
1316
1317=== See also: ===
1318
1319[[harlowe:datanames|(datanames:)]], [[harlowe:datavalues|(datavalues:)]]\\
1320<html><h2 class='def_title macro_title' id=macro_dataentries><a class='heading_link' href=#macro_dataentries></a></html>The (dataentries: ) macro<html></h2></html>
1321
1322<HTML>
1323<h3 class=macro_signature>(dataentries: <i> [[harlowe:Datamap|datamap]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1324</HTML>
1325This takes a [[harlowe:datamap|datamap]], and returns an [[harlowe:array|array]] of its name/value pairs. Each pair\\
1326is a datamap that only has "name" and "value" data. The pairs are ordered by their name.
1327
1328=== Example usage: ===
1329
1330 * ''%%(datapairs: (dm:'B',24, 'A',25))%%'' produces the following array:\\
1331''%%(a: (dm: "name", "A", "value", 25), (dm: "name", "B", "value", 24))%%''
1332 * ''%%(altered: _entry via _entry's name + ":" + _entry's value, ...(datapairs: $m))%%'' creates\\
1333an array of [[harlowe:string|string]] from the $m datamap's names and values.
1334
1335=== Rationale: ===
1336
1337There are occasions where operating on just the names, or the values, of\\
1338a datamap isn't good enough - you'll want both. Rather than the verbose process\\
1339of taking the [[harlowe:datanames|(datanames:)]] and [[harlowe:datavalues|(datavalues:)]] arrays and using them [[harlowe:interlaced|(interlaced:)]]\\
1340with each other, you can use this macro instead, which allows the name and value of\\
1341each entry to be referenced using "name" and "value" properties.
1342
1343=== See also: ===
1344
1345[[harlowe:datanames|(datanames:)]], [[harlowe:datavalues|(datavalues:)]]\\
1346<html><h2 class='def_title macro_title' id=macro_datanames><a class='heading_link' href=#macro_datanames></a></html>The (datanames: ) macro<html></h2></html>
1347
1348<HTML>
1349<h3 class=macro_signature>(datanames: <i> [[harlowe:Datamap|datamap]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1350</HTML>
1351This takes a [[harlowe:datamap|datamap]], and returns a sorted [[harlowe:array|array]] of its data names, sorted\\
1352alphabetically.
1353
1354=== Example usage: ===
1355
1356''%%(datanames: (dm:'B','Y', 'A','X'))%%'' produces the array ''%%(a: 'A','B')%%''
1357
1358=== Rationale: ===
1359
1360Sometimes, you may wish to obtain some information about a datamap. You may want\\
1361to list all of its data names, or determine how many entries it has. You can use\\
1362the (datanames:) macro to do these things: if you give it a datamap, it produces\\
1363a sorted array of all of its names. You can then [[harlowe:print|(print:)]] them, check the length\\
1364of the array, obtain a subarray, and other things you can do to arrays.
1365
1366=== See also: ===
1367
1368[[harlowe:datavalues|(datavalues:)]], [[harlowe:dataentries|(dataentries:)]]\\
1369<html><h2 class='def_title macro_title' id=macro_datavalues><a class='heading_link' href=#macro_datavalues></a></html>The (datavalues: ) macro<html></h2></html>
1370
1371<HTML>
1372<h3 class=macro_signature>(datavalues: <i> [[harlowe:Datamap|datamap]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1373</HTML>
1374This takes a [[harlowe:datamap|datamap]], and returns an [[harlowe:array|array]] of its values, sorted\\
1375alphabetically by their name.
1376
1377=== Example usage: ===
1378
1379''%%(datavalues: (dm:'B',24, 'A',25))%%'' produces the array ''%%(a: 25,24)%%''
1380
1381=== Rationale: ===
1382
1383Sometimes, you may wish to examine the values stored in a datamap without\\
1384referencing every name - for instance, determining if 0 is one of the values.\\
1385(This can't be determined using the ''%%contains%%'' keyword, because that only checks\\
1386the map's data names.) You can extract all of the datamap's values into an array\\
1387to compare and analyse them using (datavalues:). The values will be sorted by\\
1388their associated names.
1389
1390=== See also: ===
1391
1392[[harlowe:datanames|(datanames:)]], [[harlowe:dataentries|(dataentries:)]]\\
1393<html><h2 class='def_title macro_title' id=macro_find><a class='heading_link' href=#macro_find></a></html>The (find: ) macro<html></h2></html>
1394
1395<HTML>
1396<h3 class=macro_signature>(find: <i> [[harlowe:Lambda|lambda]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1397</HTML>
1398This searches through the given values, and produces an [[harlowe:array|array]] of those which match the given search\\
1399test (which is expressed using a temp variable, the ''%%where%%'' keyword, and a [[harlowe:boolean|boolean]] condition).\\
1400If none match, an empty array is produced.
1401
1402=== Example usage: ===
1403
1404 * ''%%(find: _person where _person is not "Alice", ...$people)%%'' produces a subset of $people not containing the [[harlowe:string|string]] ''%%"Alice"%%''.
1405 * ''%%(find: _item where _item's 1st is "A", "Thorn", "Apple", "Cryptid", "Anchor")%%'' produces ''%%(a: "Apple", "Anchor")%%''.
1406 * ''%%(find: _num where (_num >= 12) and (it % 2 is 0), 9, 10, 11, 12, 13, 14, 15, 16)%%'' produces ''%%(a: 12, 14, 16)%%''.
1407 * ''%%(find: _val where _val + 2, 9, 10, 11)%%'' produces an error, because ''%%_item + 2%%'' isn't a boolean.
1408 * ''%%1st of (find: _room where _room's objs contains "Egg", ...$rooms)%%'' finds the first [[harlowe:datamap|datamap]] in $rooms whose "objs" contains the string ''%%"Egg"%%''.
1409
1410=== Rationale: ===
1411
1412Selecting specific data from arrays or sequences based on a user-provided boolean condition is one of the more common and powerful\\
1413operations in programming. This macro allows you to immediately work with a subset of the array's data, without\\
1414caring what kind of subset it is. The subset can be based on each string's characters, each datamap's values, each [[harlowe:number|number]]'s\\
1415evenness or oddness, whether a variable matches it... anything you can write.
1416
1417This macro uses a [[harlowe:lambda|lambda]] (which is just the "temp variable ''%%where%%'' a condition" expression) to check every one of\\
1418the values given after it. For ''%%(find: _item where _item > 40, 30, 60, 90)%%'', it will first check if ''%%30 > 40%%'' (which\\
1419is ''%%false%%''), if ''%%60 > 40%%'' (which is ''%%true%%''), and if ''%%90 > 40%%'' (which is ''%%true%%''), and include in the returned array\\
1420those values which resulted in ''%%true%%''.
1421
1422=== Details: ===
1423
1424Of course, if any condition should cause an error, such as checking if a number contains a number, then the error will appear.
1425
1426The temp variable, which you can name anything you want, is controlled entirely by the lambda - it doesn't exist\\
1427outside of it, it won't alter identically-named temp variables outside of it, and you can't manually [[harlowe:set|(set:)]]\\
1428it within the lambda.
1429
1430You can refer to other variables, including other temp variables, in the ''%%where%%'' condition. For instance, you can\\
1431write ''%%(set: _name to "Eva")(find: _item where _item is _name, "Evan", "Eve", "Eva")%%''. However, for obvious reasons,\\
1432if the outer temp variable is named the same as the lambda's temp variable, it can't be referred to in the condition.
1433
1434There isn't a way to examine the position of a value in the condition - you can't write, say, ''%%(find: _item where _pos % 2 is 0, "A", "B", "C", "D")%%'' to select just "B" and "D".
1435
1436You shouldn't use this macro to try and alter the given values! Consider the [[harlowe:altered|(altered:)]] or [[harlowe:folded|(folded:)]] macro instead.
1437
1438=== See also: ===
1439
1440[[harlowe:sorted|(sorted:)]], [[harlowe:all-pass|(all-pass:)]], [[harlowe:some-pass|(some-pass:)]], [[harlowe:none-pass|(none-pass:)]]\\
1441<html><h2 class='def_title macro_title' id=macro_folded><a class='heading_link' href=#macro_folded></a></html>The (folded: ) macro<html></h2></html>
1442
1443<HTML>
1444<h3 class=macro_signature>(folded: <i> [[harlowe:Lambda|lambda]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>Any</i></h3>
1445</HTML>
1446This takes a "making" [[harlowe:lambda|lambda]] and a sequence of values, and creates a new value (the "total") by feeding every value in the\\
1447sequence to the lambda, akin to folding a long strip of paper into a single square.
1448
1449=== Example usage: ===
1450
1451 * ''%%(folded: _enemy making _allHP via _allHP + _enemy's hp, ...$enemies)%%'' will first set _sum to $enemies's 1st's hp, then add the remaining hp values in $enemies to it.
1452 * ''%%(folded: _name making _allNames via _allNames + "/" + _name, ...(history: ))%%'' will create a [[harlowe:string|string]] of every passage name in the [[harlowe:history|(history:)]] [[harlowe:array|array]],\\
1453separated by a forward slash.
1454
1455=== Rationale: ===
1456
1457The [[harlowe:for|(for:)]] macro, while intended to display multiple copies of a hook, can also be used to run a single macro call multiple times. You may\\
1458wish to use this to repeatedly [[harlowe:set|(set:)]] a variable to itself plus one of the looped values (or some other operation). (folded:) is meant\\
1459to let you perform this in a shorter, more fluid fashion.
1460
1461Consider, first of all, a typical [[harlowe:for|(for:)]] and [[harlowe:set|(set:)]] loop such as the following:
1462
1463<code>
1464{(set:$allNames to "")
1465(for: each _name, ...(history: ))[
1466 (set:$allNames to it + "/" _name)
1467]}
1468You've visited: $allNames
1469</code>
1470This can be rewritten using (folded:) as follows. While this version may seem a little harder to read if you're not used to it, it\\
1471allows you to accomplish the same thing in a single line, by immediately using the macro's provided value without a variable:
1472
1473<code>
1474You've visited: (folded: _name making _allNames via _allNames + "/" + _name, ...(history: )))
1475</code>
1476This macro uses a lambda (which is the "temp variable ''%%making%%'' another temp variable ''%%via%%'' expression" expression) to run the\\
1477expression using every provided value, much like those repeated [[harlowe:set|(set:)]] calls.
1478
1479If you need to perform this operation at various different times in your story, you may wish to [[harlowe:set|(set:)]] the lambda into a variable,\\
1480so that you, for instance, might need only write:
1481
1482<code>
1483You've visited: (folded: $namesWithForwardSlashes, ...(history: )))
1484</code>
1485=== Details: ===
1486
1487Of course, if at any time the expression should cause an error, such as adding a [[harlowe:number|number]] to a string, then an error will result.
1488
1489Both of the temp variables, the value and the total, can be named anything you want. As with other lambda macros, they don't exist\\
1490outside of it, won't alter identically-named temp variables outside of it, and can't be manually [[harlowe:set|(set:)]] within the lambda.
1491
1492You can refer to other variables, including other temp variables, in the ''%%via%%'' expression. For instance, you can write\\
1493''%%(folded: _score making _totalScore via _totalScore + _score * _bonusMultiplier)%%''. However, for obvious reasons,\\
1494if the outer temp variable is named the same as the lambda's temp variables, it can't be referred to in the expression.
1495
1496You can also use a "where" clause inside the "making" lambda to prevent an operation from occurring if a value isn't suitable -\\
1497''%%(folded: _item making _total via _total + _item where _item > 0, ...$arr)%%'' will only sum up the values in $arr which are greater than 0.
1498
1499=== See also: ===
1500
1501[[harlowe:for|(for:)]], [[harlowe:altered|(altered:)]]\\
1502<html><h2 class='def_title macro_title' id=macro_interlaced><a class='heading_link' href=#macro_interlaced></a></html>The (interlaced: ) macro<html></h2></html>
1503
1504<HTML>
1505<h3 class=macro_signature>(interlaced: <i> [[harlowe:Array|array]], <span class=parameter_rest>...</span>Array</i>) <span class=macro_returntype>→</span> <i>Array</i></h3>
1506</HTML>
1507Takes multiple [[harlowe:array|array]], and pairs up each value in those arrays: it\\
1508creates an array containing each array's first value followed by each\\
1509array's second value, and so forth. If some values have no matching pair (i.e. one array\\
1510is longer than the other) then those values are ignored.
1511
1512=== Example usage: ===
1513
1514''%%(interlaced: (a: 'A', 'B', 'C', 'D'), (a: 1, 2, 3))%%'' is the same as ''%%(a: 'A',1,'B',2,'C',3)%%''
1515
1516=== Rationale: ===
1517
1518There are a couple of other macros which accept data in pairs - the most notable being\\
1519[[harlowe:dm|(dm:)]], which takes data names and data values paired. This macro can help\\
1520with using such macros. For instance, you can supply an array of [[harlowe:datanames|(datanames:)]] and\\
1521[[harlowe:datavalues|(datavalues:)]] to (interlaced:), and supply that to [[harlowe:dm|(dm:)]], to produce the original\\
1522[[harlowe:datamap|datamap]] again. Or, you can supply just the names, and use a macro like [[harlowe:repeated|(repeated:)]] to\\
1523fill the other values.
1524
1525However, (interlaced:) can also be of use alongside macros which accept a sequence: you\\
1526can use it to cleanly insert values between each item. For instance, one can pair\\
1527an array with another array of spaces, and then convert them to a [[harlowe:string|string]] with [[harlowe:text|(text:)]].\\
1528''%%(text: ...(interlaced: $arr, (repeated: $arr's length, ' '))%%'' will create a string containing\\
1529each element of $arr, followed by a space.
1530
1531=== Details: ===
1532
1533If one of the arrays provided is empty, the resulting array will be empty, as well.
1534
1535=== See also: ===
1536
1537[[harlowe:a|(a:)]], [[harlowe:rotated|(rotated:)]], [[harlowe:repeated|(repeated:)]]\\
1538<html><h2 class='def_title macro_title' id=macro_none-pass><a class='heading_link' href=#macro_none-pass></a></html>The (none-pass: ) macro<html></h2></html>
1539
1540<HTML>
1541<h3 class=macro_signature>(none-pass: <i> [[harlowe:Lambda|lambda]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Boolean|boolean]]</i></h3>
1542</HTML>
1543This can be thought of as the opposite of [[harlowe:all-pass|(all-pass:)]]: it produces true if every value, when given to the [[harlowe:lambda|lambda]], evaluated to false.\\
1544For more information, consult the description of [[harlowe:all-pass|(all-pass:)]].\\
1545<html><h2 class='def_title macro_title' id=macro_range><a class='heading_link' href=#macro_range></a></html>The (range: ) macro<html></h2></html>
1546
1547<HTML>
1548<h3 class=macro_signature>(range: <i> [[harlowe:Number|number]], Number</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1549</HTML>
1550Produces an [[harlowe:array|array]] containing an inclusive range of whole [[harlowe:number|number]] from a to b,\\
1551in ascending order.
1552
1553=== Example usage: ===
1554
1555''%%(range:1,14)%%'' is equivalent to ''%%(a:1,2,3,4,5,6,7,8,9,10,11,12,13,14)%%''\\
1556''%%(range:2,-2)%%'' is equivalent to ''%%(a:-2,-1,0,1,2)%%''
1557
1558=== Rationale: ===
1559
1560This macro is a shorthand for defining an array that contains a sequence of\\
1561integer values. Rather than writing out all of the numbers, you can simply provide\\
1562the first and last numbers.
1563
1564=== Details: ===
1565
1566Certain kinds of macros, like [[harlowe:either|(either:)]] or [[harlowe:dataset|(dataset:)]], accept sequences of values. You can\\
1567use (range:) with these in conjunction with the ''%%...%%'' spreading operator:\\
1568''%%(dataset: ...(range:2,6))%%'' is equivalent to ''%%(dataset: 2,4,5,6,7)%%'', and\\
1569''%%(either: ...(range:1,5))%%'' is equivalent to ''%%(random: 1,5)%%''.
1570
1571=== See also: ===
1572
1573[[harlowe:a|(a:)]]\\
1574<html><h2 class='def_title macro_title' id=macro_repeated><a class='heading_link' href=#macro_repeated></a></html>The (repeated: ) macro<html></h2></html>
1575
1576<HTML>
1577<h3 class=macro_signature>(repeated: <i> [[harlowe:Number|number]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1578</HTML>
1579When given a [[harlowe:number|number]] and a sequence of values, this macro produces an [[harlowe:array|array]] containing\\
1580those values repeated, in order, by the given number of times.
1581
1582=== Example usage: ===
1583
1584 * ''%%(repeated: 5, false)%%'' produces ''%%(a: false, false, false, false, false)%%''
1585 * ''%%(repeated: 3, 1,2,3)%%'' produces ''%%(a: 1,2,3,1,2,3,1,2,3)%%''
1586
1587=== Rationale: ===
1588
1589This macro, as well as [[harlowe:range|(range:)]], are the means by which you can create a large array of\\
1590similar or regular data, quickly. Just as an example: you want, say, an array of several\\
1591identical, complex [[harlowe:datamap|datamap]], each of which are likely to be modified in the game,\\
1592you can use (repeated:) to make those copies easily. Or, if you want, for instance, a\\
1593lot of identical [[harlowe:string|string]] accompanied by a lone different string, you can use (repeated:)\\
1594and add a ''%%(a: "string")%%''to the end.
1595
1596When you already have an array variable, this is similar to simply adding that variable\\
1597to itself several times. However, if the number of times is over 5, this can be much\\
1598simpler to write.
1599
1600=== Details: ===
1601
1602An error will, of course, be produced if the number given is 0 or less, or contains a fraction.
1603
1604=== See also: ===
1605
1606[[harlowe:a|(a:)]], [[harlowe:range|(range:)]]\\
1607<html><h2 class='def_title macro_title' id=macro_rotated><a class='heading_link' href=#macro_rotated></a></html>The (rotated: ) macro<html></h2></html>
1608
1609<HTML>
1610<h3 class=macro_signature>(rotated: <i> [[harlowe:Number|number]], <span class=parameter_optional>\[</span><span class=parameter_rest>...</span>Any<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1611</HTML>
1612Similar to the [[harlowe:a|(a:)]] macro, but it also takes a [[harlowe:number|number]] at the start, and moves\\
1613each item forward by that number, wrapping back to the start\\
1614if they pass the end of the [[harlowe:array|array]].
1615
1616=== Example usage: ===
1617
1618 * ''%%(rotated: 1, 'A','B','C','D')%%'' is equal to ''%%(a: 'D','A','B','C')%%''.
1619 * ''%%(rotated: -2, 'A','B','C','D')%%'' is equal to ''%%(a: 'C','D','A','B')%%''.
1620
1621=== Rationale: ===
1622
1623Sometimes, you may want to cycle through a number of values, without\\
1624repeating any until you reach the end. For instance, you may have a rotating set\\
1625of flavour-text descriptions for a thing in your story, which you'd like displayed\\
1626in their entirety without the whim of a random picker. The (rotated:) macro\\
1627allows you to apply this "rotation" to a sequence of data, changing their positions\\
1628by a certain number without discarding any values.
1629
1630Remember that, as with all macros, you can insert all the values in an existing\\
1631array using the ''%%...%%'' syntax: ''%%(set: $a to (rotated: 1, ...$a))%%'' is a common means of\\
1632replacing an array with a rotation of itself.
1633
1634Think of the number as being an addition to each position in the original sequence -\\
1635if it's 1, then the value in position 1 moves to 2, the value in position 2 moves to 3,\\
1636and so forth.
1637
1638Incidentally... you can also use this macro to rotate a [[harlowe:string|string]]'s characters, by doing\\
1639something like this: ''%%(string: ...(rotated: 1, ...$str))%%''
1640
1641=== Details: ===
1642
1643To ensure that it's being used correctly, this macro requires three or more items -\\
1644providing just two, one or none will cause an error to be presented.
1645
1646=== See also: ===
1647
1648[[harlowe:sorted|(sorted:)]]\\
1649<html><h2 class='def_title macro_title' id=macro_shuffled><a class='heading_link' href=#macro_shuffled></a></html>The (shuffled: ) macro<html></h2></html>
1650
1651<HTML>
1652<h3 class=macro_signature>(shuffled: <i> Any, Any, <span class=parameter_optional>\[</span><span class=parameter_rest>...</span>Any<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1653</HTML>
1654Identical to [[harlowe:a|(a:)]], except that it randomly rearranges the elements\\
1655instead of placing them in the given order.
1656
1657=== Example usage: ===
1658
1659<code>
1660(set: $a to (a: 1,2,3,4,5,6))
1661(print: (shuffled: ...$a))
1662</code>
1663=== Rationale: ===
1664
1665If you're making a particularly random story, you'll often want to create a 'deck'\\
1666of random descriptions, elements, etc. that are only used once. That is to say, you'll want\\
1667to put them in an [[harlowe:array|array]], then randomise the array's order, preserving that random order\\
1668for the duration of a game.
1669
1670The [[harlowe:either|(either:)]] macro is useful for selecting an element from an array randomly\\
1671(if you use the spread ''%%...%%'' syntax), but isn't very helpful for this particular problem.\\
1672The (shuffled:) macro is the solution: it takes elements and returns a randomly-ordered array that\\
1673can be used as you please.
1674
1675=== Details: ===
1676
1677To ensure that it's being used correctly, this macro requires two or more items -\\
1678providing just one (or none) will cause an error to be presented.
1679
1680=== See also: ===
1681
1682[[harlowe:a|(a:)]], [[harlowe:either|(either:)]], [[harlowe:rotated|(rotated:)]]\\
1683<html><h2 class='def_title macro_title' id=macro_some-pass><a class='heading_link' href=#macro_some-pass></a></html>The (some-pass: ) macro<html></h2></html>
1684
1685<HTML>
1686<h3 class=macro_signature>(some-pass: <i> [[harlowe:Lambda|lambda]], <span class=parameter_rest>...</span>Any</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Boolean|boolean]]</i></h3>
1687</HTML>
1688This is similar to [[harlowe:all-pass|(all-pass:)]], but produces true if one or more value, when given to the [[harlowe:lambda|lambda]], evaluated to false.\\
1689It can be thought of as shorthand for putting ''%%not%%'' in front of [[harlowe:none-pass|(none-pass:)]].\\
1690For more information, consult the description of [[harlowe:all-pass|(all-pass:)]].\\
1691<html><h2 class='def_title macro_title' id=macro_sorted><a class='heading_link' href=#macro_sorted></a></html>The (sorted: ) macro<html></h2></html>
1692
1693<HTML>
1694<h3 class=macro_signature>(sorted: <i> [[harlowe:Number|number]] or [[harlowe:String|string]], <span class=parameter_rest>...</span>Number or String</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1695</HTML>
1696Similar to [[harlowe:a|(a:)]], except that it requires only [[harlowe:number|number]] or [[harlowe:string|string]], and orders\\
1697them in English alphanumeric sort order, rather than the order in which they were provided.
1698
1699=== Example usage: ===
1700
1701<code>
1702(set: $a to (a: 'A','C','E','G', 2, 1))
1703(print: (sorted: ...$a))
1704</code>
1705=== Rationale: ===
1706
1707Often, you'll be using [[harlowe:array|array]] as 'decks' that will provide values to other parts of\\
1708your story in a specific order. If you want, for instance, several strings to appear in\\
1709alphabetical order, this macro can be used to create a sorted array, or (by using the\\
1710spread ''%%...%%'' syntax) convert an existing array into a sorted one.
1711
1712=== Details: ===
1713
1714Unlike other programming languages, strings aren't sorted using ASCII sort order, but alphanumeric sorting:\\
1715the string "A2" will be sorted after "A1" and before "A11". Moreover, if the player's web browser\\
1716supports internationalisation (that is, every current browser except Safari 6-8 and IE 10), then\\
1717the strings will be sorted using English language rules (for instance, "é" comes after "e" and before\\
1718"f", and regardless of the player's computer's language settings. Otherwise, it will sort\\
1719using ASCII comparison (whereby "é" comes after "z").
1720
1721Currently there is no way to specify an alternative language locale to sort by, but this is likely to\\
1722be made available in a future version of Harlowe.
1723
1724To ensure that it's being used correctly, this macro requires two or more items -\\
1725providing just one (or none) will cause an error to be presented.
1726
1727=== See also: ===
1728
1729[[harlowe:a|(a:)]], [[harlowe:shuffled|(shuffled:)]], [[harlowe:rotated|(rotated:)]]\\
1730<html><h2 class='def_title macro_title' id=macro_current-date><a class='heading_link' href=#macro_current-date></a></html>The (current-date: ) macro<html></h2></html>
1731
1732<HTML>
1733<h3 class=macro_signature>(current-date: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:String|string]]</i></h3>
1734</HTML>
1735This date/time macro produces a [[harlowe:string|string]] of the current date the current player's system clock,\\
1736in the format "Thu Jan 01 1970".
1737
1738=== Example usage: ===
1739
1740''%%Right now, it's (current-date:).%%''\\
1741<html><h2 class='def_title macro_title' id=macro_current-time><a class='heading_link' href=#macro_current-time></a></html>The (current-time: ) macro<html></h2></html>
1742
1743<HTML>
1744<h3 class=macro_signature>(current-time: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:String|string]]</i></h3>
1745</HTML>
1746This date/time macro produces a [[harlowe:string|string]] of the current 12-hour time on the current player's system clock,\\
1747in the format "12:00 AM".
1748
1749=== Example usage: ===
1750
1751''%%The time is (current-time:).%%''\\
1752<html><h2 class='def_title macro_title' id=macro_monthday><a class='heading_link' href=#macro_monthday></a></html>The (monthday: ) macro<html></h2></html>
1753
1754<HTML>
1755<h3 class=macro_signature>(monthday: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Number|number]]</i></h3>
1756</HTML>
1757This date/time macro produces a [[harlowe:number|number]] corresponding to the day of the month on the current player's system clock.\\
1758This should be between 1 (on the 1st of the month) and 31, inclusive.
1759
1760=== Example usage: ===
1761
1762''%%Today is day (monthday:).%%''\\
1763<html><h2 class='def_title macro_title' id=macro_weekday><a class='heading_link' href=#macro_weekday></a></html>The (weekday: ) macro<html></h2></html>
1764
1765<HTML>
1766<h3 class=macro_signature>(weekday: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:String|string]]</i></h3>
1767</HTML>
1768This date/time macro produces one of the [[harlowe:string|string]] "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday"\\
1769or "Saturday", based on the weekday on the current player's system clock.
1770
1771=== Example usage: ===
1772
1773''%%Today is a (weekday:).%%''\\
1774<html><h2 class='def_title macro_title' id=macro_history><a class='heading_link' href=#macro_history></a></html>The (history: ) macro<html></h2></html>
1775
1776<HTML>
1777<h3 class=macro_signature>(history: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
1778</HTML>
1779This returns an [[harlowe:array|array]] containing the [[harlowe:string|string]] names of all of the passages\\
1780the player has visited up to now, in the order that the player visited them.
1781
1782=== Example usage: ===
1783
1784''%%(history:) contains "Cellar"%%'' is true if the player has visited a passage called\\
1785"Cellar" at some point.
1786
1787=== Rationale: ===
1788
1789Often, you may find yourself using "flag" variables to keep track of whether\\
1790the player has visited a certain passage in the past. You can use (history:), along with\\
1791data structure operators such as the ''%%contains%%'' operator, to obviate this necessity.
1792
1793=== Details: ===
1794
1795This includes duplicate names if the player has visited a passage more than once, or visited\\
1796the same passage two or more turns in a row.
1797
1798This does //not// include the name of the current passage the player is visiting.
1799
1800=== See also: ===
1801
1802[[harlowe:passage|(passage:)]], [[harlowe:savedgames|(savedgames:)]]\\
1803<html><h2 class='def_title macro_title' id=macro_passage><a class='heading_link' href=#macro_passage></a></html>The (passage: ) macro<html></h2></html>
1804
1805<HTML>
1806<h3 class=macro_signature>(passage: <i> <span class=parameter_optional>\[</span>[[harlowe:String|string]]<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Datamap|datamap]]</i></h3>
1807</HTML>
1808When given a passage [[harlowe:string|string]] name, this provides a [[harlowe:datamap|datamap]] containing information about that passage. If no\\
1809name was provided, then it provides information about the current passage.
1810
1811=== Example usage: ===
1812
1813''%%(passage:"Cellar")%%''
1814
1815=== Rationale: ===
1816
1817There are times when you wish to examine the data of the story as it is running - for instance, checking what\\
1818tag a certain passage has, and performing some special behaviour as a result. This macro provides that functionality.
1819
1820=== Details: ===
1821
1822The datamap contains the following names and values.
1823
1824^Name ^
1825|source|
1826|name |
1827|tags |
1828
1829The "source" value, like all strings, can be printed using [[harlowe:print|(print:)]]. Be warned that printing the source of\\
1830the current passage, while inside of it, may lead to an infinite regress.
1831
1832Interestingly, the construction ''%%(print: (passage: "Cellar")'s source)%%'' is essentially identical in function (albeit longer to write)\\
1833than ''%%(display: "Cellar")%%''.
1834
1835=== See also: ===
1836
1837[[harlowe:history|(history:)]], [[harlowe:savedgames|(savedgames:)]]\\
1838<html><h2 class='def_title macro_title' id=macro_link><a class='heading_link' href=#macro_link></a></html>The (link: ) macro<html></h2></html>
1839
1840<HTML>
1841<h3 class=macro_signature>(link: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
1842</HTML>
1843Also known as: [[harlowe:link-replace|(link-replace:)]]
1844
1845Makes a [[harlowe:command|command]] to create a special link that can be used to show a hook.
1846
1847=== Example usage: ===
1848
1849''%%(link: "Stake")[The dracula crumbles to dust.]%%'' will create a link reading "Stake"\\
1850which, when clicked, disappears and shows "The dracula crumbles to dust."
1851
1852=== Rationale: ===
1853
1854As you're aware, links are what the player uses to traverse your story. However,\\
1855links can also be used to simply display text or run macros inside hooks. Just\\
1856attach the (link:) macro to a hook, and the entire hook will not run or appear at all until the\\
1857player clicks the link.
1858
1859Note that this particular macro's links disappear when they are clicked - if you want\\
1860their words to remain in the text, consider using [[harlowe:link-reveal|(link-reveal:)]].
1861
1862=== Details: ===
1863
1864This creates a link which is visually indistinguishable from normal passage links.
1865
1866=== See also: ===
1867
1868[[harlowe:link-reveal|(link-reveal:)]], [[harlowe:link-repeat|(link-repeat:)]], [[harlowe:link-goto|(link-goto:)]], [[harlowe:click|(click:)]]\\
1869<html><h2 class='def_title macro_title' id=macro_link-reveal><a class='heading_link' href=#macro_link-reveal></a></html>The (link-reveal: ) macro<html></h2></html>
1870
1871<HTML>
1872<h3 class=macro_signature>(link-reveal: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
1873</HTML>
1874Makes a [[harlowe:command|command]] to create a special link that shows a hook, keeping the link's\\
1875text visible after clicking.
1876
1877=== Example usage: ===
1878
1879''%%(link-reveal: "Heart")[broken]%%'' will create a link reading "Heart"\\
1880which, when clicked, changes to plain text, and shows "broken" after it.
1881
1882=== Rationale: ===
1883
1884This is similar to [[harlowe:link|(link:)]], but allows the text of the link to remain in the passage\\
1885after it is clicked. It allows key words and phrases in the passage to expand and\\
1886reveal more text after themselves. Simply attach it to a hook, and the hook will only be\\
1887revealed when the link is clicked.
1888
1889=== Details: ===
1890
1891This creates a link which is visually indistinguishable from normal passage links.
1892
1893If the link text contains formatting syntax, such as "**bold**", then it will be retained\\
1894when the link is demoted to text.
1895
1896=== See also: ===
1897
1898[[harlowe:link|(link:)]], [[harlowe:link-repeat|(link-repeat:)]], [[harlowe:link-goto|(link-goto:)]], [[harlowe:click|(click:)]]\\
1899<html><h2 class='def_title macro_title' id=macro_link-repeat><a class='heading_link' href=#macro_link-repeat></a></html>The (link-repeat: ) macro<html></h2></html>
1900
1901<HTML>
1902<h3 class=macro_signature>(link-repeat: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
1903</HTML>
1904Makes a [[harlowe:command|command]] to create a special link that shows a hook, and, when clicked again,\\
1905re-runs the hook, appending its contents again.
1906
1907=== Example usage: ===
1908
1909''%%(link-repeat: "Add cheese")[(set:$cheese to it + 1)]%%'' will create a link reading "Add cheese"\\
1910which, when clicked, adds 1 to the $cheese variable using [[harlowe:set|(set:)]], and can be clicked repeatedly.
1911
1912=== Rationale: ===
1913
1914This is similar to [[harlowe:link|(link:)]], but allows the created link to remain in the passage\\
1915after it is clicked. It can be used to make a link that displays more text after\\
1916each click, or which must be clicked multiple times before something can happen (using [[harlowe:set|(set:)]]\\
1917and [[harlowe:if|(if:)]] to keep count of the [[harlowe:number|number]] of clicks).
1918
1919=== Details: ===
1920
1921This creates a link which is visually indistinguishable from normal passage links.\\
1922Each time the link is clicked, the text and macros printed in the previous run are\\
1923appended.
1924
1925=== See also: ===
1926
1927[[harlowe:link-reveal|(link-reveal:)]], [[harlowe:link|(link:)]], [[harlowe:link-goto|(link-goto:)]], [[harlowe:click|(click:)]]\\
1928<html><h2 class='def_title macro_title' id=macro_link-goto><a class='heading_link' href=#macro_link-goto></a></html>The (link-goto: ) macro<html></h2></html>
1929
1930<HTML>
1931<h3 class=macro_signature>(link-goto: <i> [[harlowe:String|string]], <span class=parameter_optional>\[</span>String<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
1932</HTML>
1933Takes a [[harlowe:string|string]] of link text, and an optional destination passage name, and makes a [[harlowe:command|command]] to create\\
1934a link that takes the player to another passage. The link functions identically to a standard link.\\
1935This command should not be attached to a hook.
1936
1937=== Example usage: ===
1938
1939 * ''%%(link-goto: "Enter the cellar", "Cellar")%%'' is approximately the same as ''%%[[Enter the cellar->Cellar]]%%''.
1940 * ''%%(link-goto: "Cellar")%%'' is the same as ''%%[[Cellar]]%%''.
1941
1942=== Rationale: ===
1943
1944This macro serves as an alternative to the standard link syntax (''%%[[Link text->Destination]]%%''), but has a couple of\\
1945slight differences.
1946
1947 * The link syntax lets you supply a fixed text string for the link, and an expression for the destination\\
1948passage's name. However, it does not provide any other means of computing the link. (link-goto:) also\\
1949allows the link text to be any expression - so, something like ''%%(link-goto: "Move " + $name + "to the cellar", "Cellar")%%''\\
1950can be written.
1951 * The resulting command from this macro, like all commands, can be saved and used elsewhere.\\
1952If you have a complicated link you need to use in several passages, you could [[harlowe:set|(set:)]] it to a variable and use that variable\\
1953in its place.
1954
1955=== Details: ===
1956
1957As a bit of trivia... the Harlowe engine actually converts all standard links into (link-goto:) macro calls internally -\\
1958the link syntax is, essentially, a syntactic shorthand for (link-goto:).
1959
1960=== See also: ===
1961
1962[[harlowe:link|(link:)]], [[harlowe:link-reveal|(link-reveal:)]], [[harlowe:link-repeat|(link-repeat:)]], [[harlowe:link-undo|(link-undo:)]], [[harlowe:goto|(goto:)]]\\
1963<html><h2 class='def_title macro_title' id=macro_click><a class='heading_link' href=#macro_click></a></html>The (click: ) macro<html></h2></html>
1964
1965<HTML>
1966<h3 class=macro_signature>(click: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
1967</HTML>
1968Produces a [[harlowe:command|command]] which, when attached to a hook, hides it and enchants the specified target, such that\\
1969it visually resembles a link, and that clicking it causes the attached hook to be revealed.
1970
1971=== Example usage: ===
1972
1973 * ''%%There is a small dish of water. (click: "dish")[Your finger gets wet.]%%'' causes "dish" to become a link that,\\
1974when clicked, reveals "Your finger gets wet." at the specified location.
1975 * ''%%[Fie and fuggaboo!]<shout| (click: ?shout)[Blast and damnation!]%%'' does something similar to every hook named ''%%<shout|%%''.
1976
1977=== Rationale: ===
1978
1979The [[harlowe:link|(link:)]] macro and its variations lets you make passages more interactive, by adding links that display text when\\
1980clicked. However, it can often greatly improve your passage code's readability to write a macro call that's separate\\
1981from the text that it affects. You could want to write an entire paragraph, then write code that makes certain words\\
1982into links, without interrupting the flow of the prose in the editor.
1983
1984The (click:) macro lets you separate text and code in this way. Place (click:) hooks at the end of your passages, and have\\
1985them affect named hooks, or text [[harlowe:string|string]], earlier in the passage.
1986
1987=== Details: ===
1988
1989Text or hooks targeted by a (click:) macro will be styled in a way that makes them indistinguishable from passage links,\\
1990and links created by [[harlowe:link|(link:)]]. When any one of the targets is clicked, this styling will be removed and the hook attached to the\\
1991(click:) will be displayed.
1992
1993Additionally, if a (click:) macro is removed from the passage, then its targets will lose the link styling and no longer be\\
1994affected by the macro.
1995
1996=== Targeting ?Page or ?Passage: ===
1997
1998When a (click:) command is targeting the ?Page or ?Passage, instead of transforming the entire passage text into\\
1999a link, something else will occur: a blue link-coloured border will surround the page, and\\
2000the mouse cursor (on desktop browsers) will resemble a hand no matter what it's hovering over.
2001
2002Clicking a link when a (click:) is targeting the ?Page or ?Passage will cause both the link and the (click:) to\\
2003activate at once.
2004
2005Using multiple (click:) commands to target the ?Page or ?Passage will require multiple clicks from the\\
2006player to activate all of them. They activate in the order they appear on the page - top to bottom.
2007
2008=== See also: ===
2009
2010[[harlowe:link|(link:)]], [[harlowe:link-reveal|(link-reveal:)]], [[harlowe:link-repeat|(link-repeat:)]], [[harlowe:mouseover|(mouseover:)]], [[harlowe:mouseout|(mouseout:)]], [[harlowe:replace|(replace:)]], [[harlowe:click-replace|(click-replace:)]]\\
2011<html><h2 class='def_title macro_title' id=macro_link-undo><a class='heading_link' href=#macro_link-undo></a></html>The (link-undo: ) macro<html></h2></html>
2012
2013<HTML>
2014<h3 class=macro_signature>(link-undo: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
2015</HTML>
2016Takes a [[harlowe:string|string]] of link text, and produces a link that, when clicked, undoes the current turn and\\
2017sends the player back to the previously visited passage. The link appears identical to a typical\\
2018passage link.\\
2019This [[harlowe:command|command]] should not be attached to a hook.
2020
2021=== Example usage: ===
2022
2023''%%(link-undo:"Retreat")%%'' behaves the same as ''%%(link:"Retreat")[[[harlowe:undo|(undo:)]]]%%''.
2024
2025=== Rationale: ===
2026
2027The ability to undo the player's last turn, as an alternative to [[harlowe:go-to|(go-to:)]], is explained in the documentation\\
2028of the [[harlowe:undo|(undo:)]] macro. This macro provides a shorthand for placing [[harlowe:undo|(undo:)]] inside a [[harlowe:link|(link:)]] attached hook.
2029
2030You may, as part of customising your story, be using [[harlowe:replace|(replace:)]] to change the ?sidebar, and remove its\\
2031default "undo" link. If so, you can selectively provide undo links at certain parts of your story instead,\\
2032by using this macro.
2033
2034=== Details: ===
2035
2036As with [[harlowe:undo|(undo:)]], if this command is used on the play session's first turn, an error will be produced (as there\\
2037is yet nothing to undo at that time.) You can check which turn it is by examining the ''%%length%%'' of the [[harlowe:history|(history:)]][[harlowe:array|array]].
2038
2039=== See also: ===
2040
2041[[harlowe:undo|(undo:)]], [[harlowe:link-goto|(link-goto:)]]\\
2042<html><h2 class='def_title macro_title' id=macro_click-replace><a class='heading_link' href=#macro_click-replace></a></html>The (click-replace: ) macro<html></h2></html>
2043
2044<HTML>
2045<h3 class=macro_signature>(click-replace: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2046</HTML>
2047A special shorthand combination of the [[harlowe:click|(click:)]] and [[harlowe:replace|(replace:)]] macros, this allows you to make a hook\\
2048replace its own text with that of the attached hook whenever it's clicked. ''%%(click: ?1)[(replace:?1)[...]]%%''\\
2049can be rewritten as ''%%(click-replace: ?1)[...]%%''.
2050
2051=== Example usage: ===
2052
2053<code>
2054My deepest secret.
2055(click-replace: "secret")[longing for you].
2056</code>
2057=== See also: ===
2058
2059[[harlowe:click-prepend|(click-prepend:)]], [[harlowe:click-append|(click-append:)]]\\
2060<html><h2 class='def_title macro_title' id=macro_click-append><a class='heading_link' href=#macro_click-append></a></html>The (click-append: ) macro<html></h2></html>
2061
2062<HTML>
2063<h3 class=macro_signature>(click-append: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2064</HTML>
2065A special shorthand combination of the [[harlowe:click|(click:)]] and [[harlowe:append|(append:)]] macros, this allows you to append\\
2066text to a hook or [[harlowe:string|string]] when it's clicked. ''%%(click: ?1)[(append:?1)[...]]%%''\\
2067can be rewritten as ''%%(click-append: ?1)[...]%%''.
2068
2069=== Example usage: ===
2070
2071<code>
2072I have nothing to fear.
2073(click-append: "fear")[ but my own hand].
2074</code>
2075=== See also: ===
2076
2077[[harlowe:click-replace|(click-replace:)]], [[harlowe:click-prepend|(click-prepend:)]]\\
2078<html><h2 class='def_title macro_title' id=macro_click-prepend><a class='heading_link' href=#macro_click-prepend></a></html>The (click-prepend: ) macro<html></h2></html>
2079
2080<HTML>
2081<h3 class=macro_signature>(click-prepend: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2082</HTML>
2083A special shorthand combination of the [[harlowe:click|(click:)]] and [[harlowe:prepend|(prepend:)]] macros, this allows you to prepend\\
2084text to a hook or [[harlowe:string|string]] when it's clicked. ''%%(click: ?1)[(prepend:?1)[...]]%%''\\
2085can be rewritten as ''%%(click-prepend: ?1)[...]%%''.
2086
2087=== Example usage: ===
2088
2089<code>
2090Who stands with me?
2091(click-prepend: "?")[ but my shadow].
2092</code>
2093=== See also: ===
2094
2095[[harlowe:click-replace|(click-replace:)]], [[harlowe:click-append|(click-append:)]]\\
2096<html><h2 class='def_title macro_title' id=macro_mouseover><a class='heading_link' href=#macro_mouseover></a></html>The (mouseover: ) macro<html></h2></html>
2097
2098<HTML>
2099<h3 class=macro_signature>(mouseover: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2100</HTML>
2101A variation of [[harlowe:click|(click:)]] that, instead of showing the hook when the target is clicked, shows it\\
2102when the mouse pointer merely hovers over it. The target is also styled differently, to denote this\\
2103hovering functionality.
2104
2105=== Rationale: ===
2106
2107[[harlowe:click|(click:)]] and [[harlowe:link|(link:)]] can be used to create links in your passage that reveal text or, in conjunction with\\
2108other macros, transform the text in myriad ways. This macro is exactly like [[harlowe:click|(click:)]], except that instead of\\
2109making the target a link, it makes the target reveal the hook when the mouse hovers over it. This can convey\\
2110a mood of fragility and spontaneity in your stories, of text reacting to the merest of interactions.
2111
2112=== Details: ===
2113
2114This macro is subject to the same rules regarding the styling of its targets that [[harlowe:click|(click:)]] has, so\\
2115consult [[harlowe:click|(click:)]]'s details to review them.
2116
2117This macro is not recommended for use in games or stories intended for use on touch devices, as\\
2118the concept of "hovering" over an element doesn't really make sense with that input method.
2119
2120=== See also: ===
2121
2122[[harlowe:link|(link:)]], [[harlowe:link-reveal|(link-reveal:)]], [[harlowe:link-repeat|(link-repeat:)]], [[harlowe:click|(click:)]], [[harlowe:mouseout|(mouseout:)]], [[harlowe:replace|(replace:)]], [[harlowe:mouseover-replace|(mouseover-replace:)]], [[harlowe:hover-style|(hover-style:)]]\\
2123<html><h2 class='def_title macro_title' id=macro_mouseover-replace><a class='heading_link' href=#macro_mouseover-replace></a></html>The (mouseover-replace: ) macro<html></h2></html>
2124
2125<HTML>
2126<h3 class=macro_signature>(mouseover-replace: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2127</HTML>
2128This is similar to [[harlowe:click-replace|(click-replace:)]], but uses the [[harlowe:mouseover|(mouseover:)]] macro's behaviour instead of\\
2129[[harlowe:click|(click:)]]'s. For more information, consult the description of [[harlowe:click-replace|(click-replace:)]].\\
2130<html><h2 class='def_title macro_title' id=macro_mouseover-append><a class='heading_link' href=#macro_mouseover-append></a></html>The (mouseover-append: ) macro<html></h2></html>
2131
2132<HTML>
2133<h3 class=macro_signature>(mouseover-append: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2134</HTML>
2135This is similar to [[harlowe:click-append|(click-append:)]], but uses the [[harlowe:mouseover|(mouseover:)]] macro's behaviour instead of\\
2136[[harlowe:click|(click:)]]'s. For more information, consult the description of [[harlowe:click-append|(click-append:)]].\\
2137<html><h2 class='def_title macro_title' id=macro_mouseover-prepend><a class='heading_link' href=#macro_mouseover-prepend></a></html>The (mouseover-prepend: ) macro<html></h2></html>
2138
2139<HTML>
2140<h3 class=macro_signature>(mouseover-prepend: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2141</HTML>
2142This is similar to [[harlowe:click-prepend|(click-prepend:)]], but uses the [[harlowe:mouseover|(mouseover:)]] macro's behaviour instead of\\
2143[[harlowe:click|(click:)]]'s. For more information, consult the description of [[harlowe:click-prepend|(click-prepend:)]].\\
2144<html><h2 class='def_title macro_title' id=macro_mouseout><a class='heading_link' href=#macro_mouseout></a></html>The (mouseout: ) macro<html></h2></html>
2145
2146<HTML>
2147<h3 class=macro_signature>(mouseout: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2148</HTML>
2149A variation of [[harlowe:click|(click:)]] that, instead of showing the hook when the target is clicked, shows it\\
2150when the mouse pointer moves over it, and then leaves. The target is also styled differently, to denote this\\
2151hovering functionality.
2152
2153=== Rationale: ===
2154
2155[[harlowe:click|(click:)]] and [[harlowe:link|(link:)]] can be used to create links in your passage that reveal text or, in conjunction with\\
2156other macros, transform the text in myriad ways. This macro is exactly like [[harlowe:click|(click:)]], but rather than\\
2157making the target a link, it makes the target reveal the hook when the mouse stops hovering over it.\\
2158This is very similar to clicking, but is subtly different, and conveys a sense of "pointing" at the element to\\
2159interact with it rather than "touching" it. You can use this in your stories to give a dream-like or unearthly\\
2160air to scenes or places, if you wish.
2161
2162=== Details: ===
2163
2164This macro is subject to the same rules regarding the styling of its targets that [[harlowe:click|(click:)]] has, so\\
2165consult [[harlowe:click|(click:)]]'s details to review them.
2166
2167This macro is not recommended for use in games or stories intended for use on touch devices, as\\
2168the concept of "hovering" over an element doesn't really make sense with that input method.
2169
2170=== See also: ===
2171
2172[[harlowe:link|(link:)]], [[harlowe:link-reveal|(link-reveal:)]], [[harlowe:link-repeat|(link-repeat:)]], [[harlowe:click|(click:)]], [[harlowe:mouseover|(mouseover:)]], [[harlowe:replace|(replace:)]], [[harlowe:mouseout-replace|(mouseout-replace:)]], [[harlowe:hover-style|(hover-style:)]]\\
2173<html><h2 class='def_title macro_title' id=macro_mouseout-replace><a class='heading_link' href=#macro_mouseout-replace></a></html>The (mouseout-replace: ) macro<html></h2></html>
2174
2175<HTML>
2176<h3 class=macro_signature>(mouseout-replace: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2177</HTML>
2178This is similar to [[harlowe:click-replace|(click-replace:)]], but uses the [[harlowe:mouseout|(mouseout:)]] macro's behaviour instead of\\
2179[[harlowe:click|(click:)]]'s. For more information, consult the description of [[harlowe:click-replace|(click-replace:)]].\\
2180<html><h2 class='def_title macro_title' id=macro_mouseout-append><a class='heading_link' href=#macro_mouseout-append></a></html>The (mouseout-append: ) macro<html></h2></html>
2181
2182<HTML>
2183<h3 class=macro_signature>(mouseout-append: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2184</HTML>
2185This is similar to [[harlowe:click-append|(click-append:)]], but uses the [[harlowe:mouseout|(mouseout:)]] macro's behaviour instead of\\
2186[[harlowe:click|(click:)]]'s. For more information, consult the description of [[harlowe:click-append|(click-append:)]].\\
2187<html><h2 class='def_title macro_title' id=macro_mouseout-prepend><a class='heading_link' href=#macro_mouseout-prepend></a></html>The (mouseout-prepend: ) macro<html></h2></html>
2188
2189<HTML>
2190<h3 class=macro_signature>(mouseout-prepend: <i> [[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2191</HTML>
2192This is similar to [[harlowe:click-prepend|(click-prepend:)]], but uses the [[harlowe:mouseout|(mouseout:)]] macro's behaviour instead of\\
2193[[harlowe:click|(click:)]]'s. For more information, consult the description of [[harlowe:click-prepend|(click-prepend:)]].\\
2194<html><h2 class='def_title macro_title' id=macro_go-to><a class='heading_link' href=#macro_go-to></a></html>The (go-to: ) macro<html></h2></html>
2195
2196<HTML>
2197<h3 class=macro_signature>(go-to: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
2198</HTML>
2199This [[harlowe:command|command]] stops passage code and sends the player to a new passage.\\
2200If the passage named by the [[harlowe:string|string]] does not exist, this produces an error.
2201
2202=== Example usage: ===
2203
2204''%%(go-to: "The Distant Future")%%''
2205
2206=== Rationale: ===
2207
2208There are plenty of occasions where you may want to instantly advance to a new\\
2209passage without the player's volition. (go-to:) provides access to this ability.
2210
2211(go-to:) can accept any expression which evaluates to\\
2212a string. You can, for instance, go to a randomly selected passage by combining it with\\
2213[[harlowe:either|(either:)]] - ''%%(go-to: (either: "Win", "Lose", "Draw"))%%''.
2214
2215(go-to:) can be combined with [[harlowe:link|(link:)]] to accomplish the same thing as [[harlowe:link-goto|(link-goto:)]]:\\
2216''%%(link:"Enter the hole")[(go-to:"Falling")]%%'' However, you\\
2217can include other macros inside the hook to run before the (go-to:), such as [[harlowe:set|(set:)]],\\
2218[[harlowe:put|(put:)]] or [[harlowe:save-game|(save-game:)]].
2219
2220=== Details: ===
2221
2222If it is performed, (go-to:) will "halt" the passage and prevent any macros and text\\
2223after it from running. So, a passage that contains:
2224
2225<code>
2226(set: $listen to "I love")
2227(go-to: "Train")
2228(set: $listen to it + " you")
2229</code>
2230will //not// cause ''%%$listen%%'' to become ''%%"I love you"%%'' when it runs.
2231
2232Going to a passage using this macro will count as a new "turn" in the game's passage history,\\
2233much as if a passage link was clicked. If you want to go back to the previous passage,\\
2234forgetting the current turn, then you may use [[harlowe:undo|(undo:)]].
2235
2236=== See also: ===
2237
2238[[harlowe:link-goto|(link-goto:)]], [[harlowe:undo|(undo:)]], [[harlowe:loadgame|(loadgame:)]]\\
2239<html><h2 class='def_title macro_title' id=macro_undo><a class='heading_link' href=#macro_undo></a></html>The (undo: ) macro<html></h2></html>
2240
2241<HTML>
2242<h3 class=macro_signature>(undo: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
2243</HTML>
2244This [[harlowe:command|command]] stops passage code and "undoes" the current turn, sending the player to the previous visited\\
2245passage and forgetting any variable changes that occurred in this passage.
2246
2247=== Example usage: ===
2248
2249''%%You scurry back whence you came... (live:2s)[(undo:)]%%'' will undo the current turn after 2 seconds.
2250
2251=== Rationale: ===
2252
2253The [[harlowe:go-to|(go-to:)]] macro sends players to different passages instantly. But, it's common to want to\\
2254send players back to the passage they previously visited, acting as if this turn never happened.\\
2255(undo:) provides this functionality.
2256
2257By default, Harlowe offers a button in its sidebar that lets players undo at any time, going\\
2258back to the beginning of the game session. However, if you wish to use this macro, and only permit undos\\
2259in certain passages and occasions, you may remove the button by using [[harlowe:replace|(replace:)]] on the ?sidebar in\\
2260a header tagged passage.
2261
2262=== Details: ===
2263
2264If this is the first turn of the game session, (undo:) will produce an error. You can check which turn it is\\
2265by examining the ''%%length%%'' of the [[harlowe:history|(history:)]] [[harlowe:array|array]].
2266
2267Just like [[harlowe:go-to|(go-to:)]], (undo:) will "halt" the passage and prevent any macros and text\\
2268after it from running.
2269
2270=== See also: ===
2271
2272[[harlowe:go-to|(go-to:)]], [[harlowe:link-undo|(link-undo:)]]\\
2273<html><h2 class='def_title macro_title' id=macro_live><a class='heading_link' href=#macro_live></a></html>The (live: ) macro<html></h2></html>
2274
2275<HTML>
2276<h3 class=macro_signature>(live: <i> <span class=parameter_optional>\[</span>[[harlowe:Number|number]]<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2277</HTML>
2278When you attach this macro to a hook, the hook becomes "live", which means that it's repeatedly re-run\\
2279every certain [[harlowe:number|number]] of milliseconds, replacing the source inside of the hook with a newly computed version.
2280
2281=== Example usage: ===
2282
2283<code>
2284{(live: 0.5s)[
2285Â Â Â Â (either: "Bang!", "Kaboom!", "Whammo!", "Pow!")
2286]}
2287</code>
2288=== Rationale: ===
2289
2290Twine passage text generally behaves like a HTML document: it starts as code, is changed into a\\
2291rendered page when you "open" it, and remains so until you leave. But, you may want a part of the\\
2292page to change itself before the player's eyes, for its code to be re-renders "live"\\
2293in front of the player, while the remainder of the passage remains the same.
2294
2295Certain macros, such as the [[harlowe:link|(link:)]] macro, allow a hook to be withheld until after an element is\\
2296interacted with. The (live:) macro is more versatile: it re-renders a hook every specified number of\\
2297milliseconds. If [[harlowe:if|(if:)]] or [[harlowe:unless|(unless:)]] macros are inside the hook, they of course will be re-evaluated each time.\\
2298By using these two kinds of macros, you can make a (live:) macro repeatedly check if an event has occurred, and\\
2299only change its text at that point.
2300
2301=== Details: ===
2302
2303Live hooks will continue to re-render themselves until they encounter and print a [[harlowe:stop|(stop:)]] macro.\\
2304<html><h2 class='def_title macro_title' id=macro_stop><a class='heading_link' href=#macro_stop></a></html>The (stop: ) macro<html></h2></html>
2305
2306<HTML>
2307<h3 class=macro_signature>(stop: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
2308</HTML>
2309This macro, which accepts no arguments, creates a (stop:) [[harlowe:command|command]], which is not configurable.
2310
2311=== Example usage: ===
2312
2313<code>
2314{(live: 1s)[
2315Â Â Â Â (if: $packedBags)[OK, let's go!(stop:)]
2316Â Â Â Â (else: )[(either:"Are you ready yet?","We mustn't be late!")]
2317]}
2318</code>
2319=== Rationale: ===
2320
2321Clunky though it looks, this macro serves a single important purpose: inside a [[harlowe:live|(live:)]]\\
2322macro's hook, its appearance signals that the macro must stop running. In every other occasion,\\
2323this macro does nothing.
2324
2325=== See also: ===
2326
2327[[harlowe:live|(live:)]]\\
2328<html><h2 class='def_title macro_title' id=macro_abs><a class='heading_link' href=#macro_abs></a></html>The (abs: ) macro<html></h2></html>
2329
2330<HTML>
2331<h3 class=macro_signature>(abs: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2332</HTML>
2333This maths macro finds the absolute value of a [[harlowe:number|number]] (without the sign).
2334
2335=== Example usage: ===
2336
2337''%%(abs: -4)%%'' produces 4.\\
2338<html><h2 class='def_title macro_title' id=macro_cos><a class='heading_link' href=#macro_cos></a></html>The (cos: ) macro<html></h2></html>
2339
2340<HTML>
2341<h3 class=macro_signature>(cos: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2342</HTML>
2343This maths macro computes the cosine of the given [[harlowe:number|number]] of radians.
2344
2345=== Example usage: ===
2346
2347''%%(cos: 3.14159265)%%'' produces -1.\\
2348<html><h2 class='def_title macro_title' id=macro_exp><a class='heading_link' href=#macro_exp></a></html>The (exp: ) macro<html></h2></html>
2349
2350<HTML>
2351<h3 class=macro_signature>(exp: <i> [[harlowe:Number|number]], Number</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2352</HTML>
2353This maths macro raises Euler's [[harlowe:number|number]] to the power of the second number, and\\
2354provides the result.
2355
2356=== Example usage: ===
2357
2358''%%(exp: 6)%%'' produces approximately 7.38905609893065.\\
2359<html><h2 class='def_title macro_title' id=macro_log><a class='heading_link' href=#macro_log></a></html>The (log: ) macro<html></h2></html>
2360
2361<HTML>
2362<h3 class=macro_signature>(log: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2363</HTML>
2364This maths macro produces the natural logarithm (the base-e logarithm) of the given [[harlowe:number|number]].
2365
2366=== Example usage: ===
2367
2368''%%(log: (exp:5))%%'' produces 5.\\
2369<html><h2 class='def_title macro_title' id=macro_log10><a class='heading_link' href=#macro_log10></a></html>The (log10: ) macro<html></h2></html>
2370
2371<HTML>
2372<h3 class=macro_signature>(log10: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2373</HTML>
2374This maths macro produces the base-10 logarithm of the given [[harlowe:number|number]].
2375
2376=== Example usage: ===
2377
2378''%%(log10: 100)%%'' produces 2.\\
2379<html><h2 class='def_title macro_title' id=macro_log2><a class='heading_link' href=#macro_log2></a></html>The (log2: ) macro<html></h2></html>
2380
2381<HTML>
2382<h3 class=macro_signature>(log2: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2383</HTML>
2384This maths macro produces the base-2 logarithm of the given [[harlowe:number|number]].
2385
2386=== Example usage: ===
2387
2388''%%(log2: 256)%%'' produces 8.\\
2389<html><h2 class='def_title macro_title' id=macro_max><a class='heading_link' href=#macro_max></a></html>The (max: ) macro<html></h2></html>
2390
2391<HTML>
2392<h3 class=macro_signature>(max: <i> <span class=parameter_rest>...</span>[[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2393</HTML>
2394This maths macro accepts [[harlowe:number|number]], and evaluates to the highest valued number.
2395
2396=== Example usage: ===
2397
2398''%%(max: 2, -5, 2, 7, 0.1)%%'' produces 7.\\
2399<html><h2 class='def_title macro_title' id=macro_min><a class='heading_link' href=#macro_min></a></html>The (min: ) macro<html></h2></html>
2400
2401<HTML>
2402<h3 class=macro_signature>(min: <i> <span class=parameter_rest>...</span>[[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2403</HTML>
2404This maths macro accepts [[harlowe:number|number]], and evaluates to the lowest valued number.
2405
2406=== Example usage: ===
2407
2408''%%(min: 2, -5, 2, 7, 0.1)%%'' produces -5.\\
2409<html><h2 class='def_title macro_title' id=macro_pow><a class='heading_link' href=#macro_pow></a></html>The (pow: ) macro<html></h2></html>
2410
2411<HTML>
2412<h3 class=macro_signature>(pow: <i> [[harlowe:Number|number]], Number</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2413</HTML>
2414This maths macro raises the first [[harlowe:number|number]] to the power of the second number, and\\
2415provides the result.
2416
2417=== Example usage: ===
2418
2419''%%(pow: 2, 8)%%'' produces 256.\\
2420<html><h2 class='def_title macro_title' id=macro_sign><a class='heading_link' href=#macro_sign></a></html>The (sign: ) macro<html></h2></html>
2421
2422<HTML>
2423<h3 class=macro_signature>(sign: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2424</HTML>
2425This maths macro produces -1 when given a negative [[harlowe:number|number]], 0 when given 0, and 1\\
2426when given a positive number.
2427
2428=== Example usage: ===
2429
2430''%%(sign: -4)%%'' produces -1.\\
2431<html><h2 class='def_title macro_title' id=macro_sin><a class='heading_link' href=#macro_sin></a></html>The (sin: ) macro<html></h2></html>
2432
2433<HTML>
2434<h3 class=macro_signature>(sin: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2435</HTML>
2436This maths macro computes the sine of the given [[harlowe:number|number]] of radians.
2437
2438=== Example usage: ===
2439
2440''%%(sin: 3.14159265 / 2)%%'' produces 1.\\
2441<html><h2 class='def_title macro_title' id=macro_sqrt><a class='heading_link' href=#macro_sqrt></a></html>The (sqrt: ) macro<html></h2></html>
2442
2443<HTML>
2444<h3 class=macro_signature>(sqrt: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2445</HTML>
2446This maths macro produces the square root of the given [[harlowe:number|number]].
2447
2448=== Example usage: ===
2449
2450''%%(sqrt: 25)%%'' produces 5.\\
2451<html><h2 class='def_title macro_title' id=macro_tan><a class='heading_link' href=#macro_tan></a></html>The (tan: ) macro<html></h2></html>
2452
2453<HTML>
2454<h3 class=macro_signature>(tan: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2455</HTML>
2456This maths macro computes the tangent of the given [[harlowe:number|number]] of radians.
2457
2458=== Example usage: ===
2459
2460''%%(tan: 3.14159265 / 4)%%'' produces approximately 1.\\
2461<html><h2 class='def_title macro_title' id=macro_ceil><a class='heading_link' href=#macro_ceil></a></html>The (ceil: ) macro<html></h2></html>
2462
2463<HTML>
2464<h3 class=macro_signature>(ceil: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2465</HTML>
2466This macro rounds the given [[harlowe:number|number]] upward to a whole number. If a whole number is provided,\\
2467it returns the number as-is.
2468
2469=== Example usage: ===
2470
2471''%%(ceil: 1.1)%%'' produces 2.\\
2472<html><h2 class='def_title macro_title' id=macro_floor><a class='heading_link' href=#macro_floor></a></html>The (floor: ) macro<html></h2></html>
2473
2474<HTML>
2475<h3 class=macro_signature>(floor: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2476</HTML>
2477This macro rounds the given [[harlowe:number|number]] downward to a whole number. If a whole number is provided,\\
2478it returns the number as-is.
2479
2480=== Example usage: ===
2481
2482''%%(floor: 1.99)%%'' produces 1.\\
2483<html><h2 class='def_title macro_title' id=macro_num><a class='heading_link' href=#macro_num></a></html>The (num: ) macro<html></h2></html>
2484
2485<HTML>
2486<h3 class=macro_signature>(num: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Number|number]]</i></h3>
2487</HTML>
2488Also known as: [[harlowe:number|(number:)]]
2489
2490This macro converts [[harlowe:string|string]] to [[harlowe:number|number]] by reading the digits in the entire\\
2491string. It can handle decimal fractions and negative numbers.\\
2492If any letters or other unusual characters appear in the number, it will\\
2493result in an error.
2494
2495=== Example usage: ===
2496
2497''%%(num: "25")%%'' results in the number ''%%25%%''.
2498
2499=== Rationale: ===
2500
2501Unlike in Twine 1 and SugarCube, Twine 2 will only convert numbers into strings, or strings\\
2502into numbers, if you explictly ask it to using macros such as this. This extra\\
2503carefulness decreases the likelihood of unusual bugs creeping into stories\\
2504(such as performing ''%%"Eggs: " + 2 + 1%%'' and getting ''%%"Eggs: 21"%%'').
2505
2506Usually, you will only work with numbers and strings of your own creation, but\\
2507if you're receiving user input and need to perform arithmetic on it,\\
2508this macro will be necessary.
2509
2510=== See also: ===
2511
2512[[harlowe:text|(text:)]]\\
2513<html><h2 class='def_title macro_title' id=macro_random><a class='heading_link' href=#macro_random></a></html>The (random: ) macro<html></h2></html>
2514
2515<HTML>
2516<h3 class=macro_signature>(random: <i> [[harlowe:Number|number]], <span class=parameter_optional>\[</span>Number<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2517</HTML>
2518This macro produces a whole [[harlowe:number|number]] randomly selected between the two whole numbers, inclusive\\
2519(or, if the second number is absent, then between 0 and the first number, inclusive).
2520
2521=== Example usage: ===
2522
2523''%%(random: 1,6)%%'' simulates a six-sided die roll.
2524
2525=== See also: ===
2526
2527[[harlowe:either|(either:)]], [[harlowe:shuffled|(shuffled:)]]\\
2528<html><h2 class='def_title macro_title' id=macro_round><a class='heading_link' href=#macro_round></a></html>The (round: ) macro<html></h2></html>
2529
2530<HTML>
2531<h3 class=macro_signature>(round: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>Number</i></h3>
2532</HTML>
2533This macro rounds the given [[harlowe:number|number]] to the nearest whole number - downward if\\
2534its decimals are smaller than 0.5, and upward otherwise. If a whole number is provided,\\
2535it returns the number as-is.
2536
2537=== Example usage: ===
2538
2539''%%(round: 1.5)%%'' produces 2.\\
2540<html><h2 class='def_title macro_title' id=macro_alert><a class='heading_link' href=#macro_alert></a></html>The (alert: ) macro<html></h2></html>
2541
2542<HTML>
2543<h3 class=macro_signature>(alert: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
2544</HTML>
2545This macro produces a [[harlowe:command|command]] that, when evaluated, shows a browser pop-up dialog box with the given\\
2546[[harlowe:string|string]] displayed, and an "OK" button to dismiss it.
2547
2548=== Example usage: ===
2549
2550''%%(alert:"Beyond this point, things get serious. Grab a snack and buckle up.")%%''
2551
2552=== Details: ===
2553
2554This is essentially identical to the Javascript ''%%alert()%%'' function in purpose and ability. You\\
2555can use it to display a special message above the game itself. But, be aware that as the box uses\\
2556the player's operating system and browser's styling, it may clash visually with the design\\
2557of your story.
2558
2559When the dialog is on-screen, the entire game is essentially "paused" - no further computations are\\
2560performed until it is dismissed.
2561
2562=== See also: ===
2563
2564[[harlowe:prompt|(prompt:)]], [[harlowe:confirm|(confirm:)]]\\
2565<html><h2 class='def_title macro_title' id=macro_confirm><a class='heading_link' href=#macro_confirm></a></html>The (confirm: ) macro<html></h2></html>
2566
2567<HTML>
2568<h3 class=macro_signature>(confirm: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Boolean|boolean]]</i></h3>
2569</HTML>
2570When this macro is evaluated, a browser pop-up dialog box is shown with the given [[harlowe:string|string]] displayed,\\
2571as well as "OK" and "Cancel" button to confirm or cancel whatever action or fact the string tells the player.\\
2572When it is submitted, it evaluates to the [[harlowe:boolean|boolean]] true if "OK" had been pressed, and false if "Cancel" had.
2573
2574=== Example usage: ===
2575
2576''%%(set: $makeCake to (confirm: "Transform your best friend into a cake?"))%%''
2577
2578=== Details: ===
2579
2580This is essentially identical to the Javascript ''%%confirm()%%'' function in purpose and ability. You can\\
2581use it to ask the player a question directly, and act on the result immediately.\\
2582But, be aware that as the box uses the player's operating system and browser's styling, it\\
2583may clash visually with the design of your story.
2584
2585When the dialog is on-screen, the entire game is essentially "paused" - no further computations are\\
2586performed until it is dismissed.
2587
2588=== See also: ===
2589
2590[[harlowe:alert|(alert:)]], [[harlowe:prompt|(prompt:)]]\\
2591<html><h2 class='def_title macro_title' id=macro_prompt><a class='heading_link' href=#macro_prompt></a></html>The (prompt: ) macro<html></h2></html>
2592
2593<HTML>
2594<h3 class=macro_signature>(prompt: <i> [[harlowe:String|string]], String</i>) <span class=macro_returntype>→</span> <i>String</i></h3>
2595</HTML>
2596When this macro is evaluated, a browser pop-up dialog box is shown with the first [[harlowe:string|string]] displayed,\\
2597a text entry box containing the second string (as a default value), and an "OK" button to submit.\\
2598When it is submitted, it evaluates to the string in the text entry box.
2599
2600=== Example usage: ===
2601
2602''%%(set: $name to (prompt: "Your name, please:", "Frances Spayne"))%%''
2603
2604=== Details: ===
2605
2606This is essentially identical to the Javascript ''%%prompt()%%'' function in purpose and ability. You can\\
2607use it to obtain a string value from the player directly, such as a name for the main character.\\
2608But, be aware that as the box uses the player's operating system and browser's styling, it\\
2609may clash visually with the design of your story.
2610
2611When the dialog is on-screen, the entire game is essentially "paused" - no further computations are\\
2612performed until it is dismissed.
2613
2614=== See also: ===
2615
2616[[harlowe:alert|(alert:)]], [[harlowe:confirm|(confirm:)]]\\
2617<html><h2 class='def_title macro_title' id=macro_append><a class='heading_link' href=#macro_append></a></html>The (append: ) macro<html></h2></html>
2618
2619<HTML>
2620<h3 class=macro_signature>(append: <i> <span class=parameter_rest>...</span>[[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2621</HTML>
2622A variation of [[harlowe:replace|(replace:)]] which adds the attached hook's contents to\\
2623the end of each target, rather than replacing it entirely.
2624
2625=== Example usage: ===
2626
2627 * ''%%(append: "Emily", "Em")[, my maid]%%'' adds ", my maid " to the end of every occurrence of "Emily" or "Em".
2628 * ''%%(append: ?dress)[ from happier days]%%'' adds " from happier days" to the end of the ''%%|dress>%%'' hook.
2629
2630=== Rationale: ===
2631
2632As this is a variation of [[harlowe:replace|(replace:)]], the rationale for this macro can be found in\\
2633that macro's description. This provides the ability to append content to a target, building up\\
2634text or amending it with an extra sentence or word, changing or revealing a deeper meaning.
2635
2636=== See also: ===
2637
2638[[harlowe:replace|(replace:)]], [[harlowe:prepend|(prepend:)]]\\
2639<html><h2 class='def_title macro_title' id=macro_prepend><a class='heading_link' href=#macro_prepend></a></html>The (prepend: ) macro<html></h2></html>
2640
2641<HTML>
2642<h3 class=macro_signature>(prepend: <i> <span class=parameter_rest>...</span>[[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2643</HTML>
2644A variation of [[harlowe:replace|(replace:)]] which adds the attached hook's contents to\\
2645the beginning of each target, rather than replacing it entirely.
2646
2647=== Example usage: ===
2648
2649 * ''%%(prepend: "Emily", "Em")[Miss ]%%'' adds "Miss " to the start of every occurrence of "Emily" or "Em".
2650 * ''%%(prepend: ?dress)[my wedding ]%%'' adds "my wedding " to the start of the ''%%|dress>%%'' hook.
2651
2652=== Rationale: ===
2653
2654As this is a variation of [[harlowe:replace|(replace:)]], the rationale for this macro can be found in\\
2655that macro's description. This provides the ability to prepend content to a target, adding\\
2656preceding sentences or words to a text to change or reveal a deeper meaning.
2657
2658=== See also: ===
2659
2660[[harlowe:replace|(replace:)]], [[harlowe:append|(append:)]]\\
2661<html><h2 class='def_title macro_title' id=macro_replace><a class='heading_link' href=#macro_replace></a></html>The (replace: ) macro<html></h2></html>
2662
2663<HTML>
2664<h3 class=macro_signature>(replace: <i> <span class=parameter_rest>...</span>[[harlowe:HookName|hookname]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2665</HTML>
2666Creates a [[harlowe:command|command]] which you can attach to a hook, and replace target\\
2667destinations with the hook's contents. The targets are either text [[harlowe:string|string]] within\\
2668the current passage, or hook references.
2669
2670=== Example usage: ===
2671
2672This example changes the words "categorical catastrophe" to "**dog**egorical **dog**astrophe"
2673
2674<code>
2675A categorical catastrophe!
2676(replace: "cat")[**dog**]
2677</code>
2678This example changes the ''%%|face>%%'' and ''%%|heart>%%'' hooks to read "smile":
2679
2680<code>
2681A |heart>[song] in your heart, a |face>[song] on your face.
2682(replace: ?face, ?heart)[smile]
2683</code>
2684=== Rationale: ===
2685
2686A common way to make your stories feel dynamic is to cause their text to modify itself\\
2687before the player's eyes, in response to actions they perform. You can check for these actions\\
2688using macros such as [[harlowe:link|(link:)]], [[harlowe:click|(click:)]] or [[harlowe:live|(live:)]], and you can make these changes using macros\\
2689such as (replace:).
2690
2691Using (replace:) is only one way of providing this dynamism, however - the [[harlowe:show|(show:)]] macro also\\
2692offers similar functionality. See that macro's article for an explanation of when you might prefer\\
2693to use it over (replace:), and vice-versa.
2694
2695=== Details: ===
2696
2697(replace:) lets you specify a target, and a block of text to replace the target with. The attached hook\\
2698will not be rendered normally - thus, you can essentially place (replace:) commands anywhere in the passage\\
2699text without interfering much with the passage's visible text.
2700
2701If the given target is a string, then every instance of the string in the current passage is replaced\\
2702with a copy of the hook's contents. If the given target is a hook reference, then only named hooks\\
2703with the same name as the reference will be replaced with the hook's contents. Use named hooks when\\
2704you want only specific places in the passage text to change.
2705
2706If the target doesn't match any part of the passage, nothing will happen. This is to allow you to\\
2707place (replace:) commands in ''%%header%%'' tagged passages, if you want them to conditionally affect\\
2708certain named hooks throughout the entire game, without them interfering with other passages.
2709
2710=== See also: ===
2711
2712[[harlowe:append|(append:)]], [[harlowe:prepend|(prepend:)]], [[harlowe:show|(show:)]]\\
2713<html><h2 class='def_title macro_title' id=macro_load-game><a class='heading_link' href=#macro_load-game></a></html>The (load-game: ) macro<html></h2></html>
2714
2715<HTML>
2716<h3 class=macro_signature>(load-game: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
2717</HTML>
2718This [[harlowe:command|command]] attempts to load a saved game from the given slot, ending the current game and replacing it\\
2719with the loaded one. This causes the passage to change.
2720
2721=== Example usage: ===
2722
2723<code>
2724{(if: $Saves contains "Slot A")[
2725Â Â (link: "Load game")[(load-game:"Slot A")]
2726]}
2727</code>
2728=== Details: ===
2729
2730Just as [[harlowe:save-game|(save-game:)]] exists to store the current game session, (load-game:) exists to retrieve a past\\
2731game session, whenever you want. This command, when given the [[harlowe:string|string]] name of a slot, will attempt to\\
2732load the save, completely and instantly replacing the variables and move history with that of the\\
2733save, and going to the passage where that save was made.
2734
2735This macro assumes that the save slot exists and contains a game, which you can check by seeing if\\
2736''%%[[harlowe:saved-games|(saved-games:)]] contains%%'' the slot name before running (load-game:).
2737
2738=== See also: ===
2739
2740[[harlowe:save-game|(save-game:)]], [[harlowe:saved-games|(saved-games:)]]\\
2741<html><h2 class='def_title macro_title' id=macro_save-game><a class='heading_link' href=#macro_save-game></a></html>The (save-game: ) macro<html></h2></html>
2742
2743<HTML>
2744<h3 class=macro_signature>(save-game: <i> [[harlowe:String|string]], <span class=parameter_optional>\[</span>String<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Boolean|boolean]]</i></h3>
2745</HTML>
2746This macro saves the current game's state in browser storage, in the given save slot,\\
2747and including a special filename. It can then be restored using [[harlowe:load-game|(load-game:)]].
2748
2749=== Rationale: ===
2750
2751Many web games use browser cookies to save the player's place in the game.\\
2752Twine allows you to save the game, including all of the variables that were [[harlowe:set|(set:)]]\\
2753or [[harlowe:put|(put:)]], and the passages the player visited, to the player's browser storage.
2754
2755(save-game:) is a single operation that can be used as often or as little as you\\
2756want to. You can include it on every page; You can put it at the start of each "chapter";\\
2757You can put it inside a [[harlowe:link|(link:)]] hook, such as
2758
2759<code>
2760{(link:"Save game")[
2761Â Â (if:(save-game:"Slot A"))[
2762Â Â Â Â Game saved!
2763Â Â ](else: )[
2764Â Â Â Â Sorry, I couldn't save your game.
2765Â Â ]
2766]}
2767</code>
2768and let the player choose when to save.
2769
2770=== Details: ===
2771
2772(save-game:)'s first [[harlowe:string|string]] is a slot name in which to store the game. You can have as many slots\\
2773as you like. If you only need one slot, you can just call it, say, ''%%"A"%%'', and use ''%%(save-game:"A")%%''.\\
2774You can tie them to a name the player gives, such as ''%%(save-game: $playerName)%%'', if multiple players\\
2775are likely to play this game - at an exhibition, for instance.
2776
2777Giving the saved game a file name is optional, but allows that name to be displayed by finding it in the\\
2778$Saves [[harlowe:datamap|datamap]]. This can be combined with a [[harlowe:load-game|(load-game:)]][[harlowe:link|(link:)]] to clue the players into the save's contents:
2779
2780<code>
2781(link: "Load game: " + ("Slot 1") of Saves)[
2782Â Â (load-game: "Slot 1")
2783]
2784</code>
2785(save-game:) evaluates to a [[harlowe:boolean|boolean]] - true if the game was indeed saved, and false if the browser prevented\\
2786it (because they're using private browsing, their browser's storage is full, or some other reason).\\
2787Since there's always a possibility of a save failing, you should use [[harlowe:if|(if:)]] and [[harlowe:else|(else:)]] with (save-game:)\\
2788to display an apology message in the event that it returns false (as seen above).
2789
2790=== See also: ===
2791
2792[[harlowe:load-game|(load-game:)]], [[harlowe:saved-games|(saved-games:)]]\\
2793<html><h2 class='def_title macro_title' id=macro_saved-games><a class='heading_link' href=#macro_saved-games></a></html>The (saved-games: ) macro<html></h2></html>
2794
2795<HTML>
2796<h3 class=macro_signature>(saved-games: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Datamap|datamap]]</i></h3>
2797</HTML>
2798This returns a [[harlowe:datamap|datamap]] containing the names of currently occupied save game slots.
2799
2800=== Example usage: ===
2801
2802''%%(print (saved-games:)'s "File A")%%'' prints the name of the save file in the slot "File A".\\
2803''%%(if: (saved-games:) contains "File A")%%'' checks if the slot "File A" is occupied.
2804
2805=== Rationale: ===
2806
2807For a more thorough description of the save file system, see the [[harlowe:save-game|(save-game:)]] article.\\
2808This macro provides a means to examine the current save files in the user's browser storage, so\\
2809you can decide to print "Load game" links if a slot is occupied, or display a list of\\
2810all of the occupied slots.
2811
2812=== Details: ===
2813
2814Each name in the datamap corresponds to an occupied slot name. The values are the file names of\\
2815the files occupying the slot.
2816
2817Changing the datamap does not affect the save files - it is simply information.
2818
2819=== See also: ===
2820
2821[[harlowe:save-game|(save-game:)]], [[harlowe:load-game|(load-game:)]]\\
2822<html><h2 class='def_title macro_title' id=macro_hidden><a class='heading_link' href=#macro_hidden></a></html>The (hidden: ) macro<html></h2></html>
2823
2824<HTML>
2825<h3 class=macro_signature>(hidden: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
2826</HTML>
2827Produces a [[harlowe:command|command]] that can be attached to hooks to hide them.
2828
2829=== Example usage: ===
2830
2831<code>
2832Don't you recognise me? (hidden:)|truth>[I'm your OC, brought to life!]
2833</code>
2834The above example is the same as
2835
2836<code>
2837Don't you recognise me? |truth)[I'm your OC, brought to life!]
2838</code>
2839=== Rationale: ===
2840
2841While there is a way to succinctly mark certain named hooks as hidden, by using parentheses instead of\\
2842''%%<%%'' or ''%%>%%'' marks, this macro provides a clear way for complex [[harlowe:changer|changer]] to hide their attached hooks.\\
2843This works well when added to the [[harlowe:hook|(hook:)]] macro, for instance, to specify a hook's name and visibility\\
2844in a single changer.
2845
2846This macro is essentially identical in behaviour to ''%%(if:false)%%'', but reads better.
2847
2848=== See also: ===
2849
2850[[harlowe:if|(if:)]], [[harlowe:hook|(hook:)]], [[harlowe:show|(show:)]]\\
2851<html><h2 class='def_title macro_title' id=macro_show><a class='heading_link' href=#macro_show></a></html>The (show: ) macro<html></h2></html>
2852
2853<HTML>
2854<h3 class=macro_signature>(show: <i> <span class=parameter_rest>...</span>[[harlowe:HookName|hookname]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
2855</HTML>
2856Reveals hidden hooks, running the code within.
2857
2858=== Example usage: ===
2859
2860<code>
2861|fan)[The overhead fan spins lazily.]
2862
2863(link:"Turn on fan")[(show:?fan)]
2864</code>
2865=== Rationale: ===
2866
2867The purpose of hidden hooks is, of course, to eventually show them - and this macro is\\
2868how you show them. You can use this [[harlowe:command|command]] inside a [[harlowe:link|(link:)]], trigger it in real-time with\\
2869a [[harlowe:live|(live:)]] macro, or anywhere else.
2870
2871Using (show:) vs [[harlowe:replace|(replace:)]]:\\
2872There are different reasons for using hidden hooks and (show:) instead of [[harlowe:replace|(replace:)]]. For your stories,\\
2873think about whether the prose being revealed is part of the "main" text of the passage, or is just an aside.\\
2874In neatly-coded stories, the main text should appear early in a passage's code, as the focus of the\\
2875writer's attention.
2876
2877When using [[harlowe:replace|(replace:)]], the replacement prose is written far from its insertion point. This can improve\\
2878readability when the insertion point is part of a long paragraph or sentence, and the prose is a minor aside\\
2879or amendment, similar to a footnote or post-script, that would clutter the paragraph were it included inside.\\
2880Additionally, [[harlowe:replace|(replace:)]] can be used in a "header" or "footer" tagged passage to affect certain named hooks\\
2881throughout the story.
2882
2883<code>
2884You turn away from her, facing the grandfather clock, its [stern ticking]<1| filling the tense silence.
2885
2886(click-replace: ?1)[echoing, hollow ticking]
2887</code>
2888When using (show:), the hidden hook's position is fixed in the passage prose. This can improve\\
2889readability when the hidden hook contains a lot of the "main" text of a passage, which provides vital context\\
2890and meaning for the rest of the text.
2891
2892<code>
2893I don't know where to begin... |1)[The weird state of my birth, the prophecy made centuries ago,
2894my first day of school, the day of the meteors, the day I awoke my friends' powers... so many strands in
2895the tapestry of my tale, and no time to unravel them.] ...so for now I'll start with when we fell down the hole.
2896
2897(link:"Where, indeed?")[(show:?1)]
2898</code>
2899But, there aren't any hard rules for when you should use one or the other. As a passage changes in the writing, you should feel free to change between one or the other, or leave your choice as-is.
2900
2901=== Details: ===
2902
2903(show:) will reveal every hook with the given name. To only reveal a specific hook, you can use the\\
2904possessive syntax, as usual: ''%%(show: ?shrub's 1st)%%''.
2905
2906If you provide to (show:) a hook which is already visible, an error will be produced.
2907
2908=== See also: ===
2909
2910[[harlowe:hidden|(hidden:)]], [[harlowe:replace|(replace:)]]\\
2911<html><h2 class='def_title macro_title' id=macro_lowercase><a class='heading_link' href=#macro_lowercase></a></html>The (lowercase: ) macro<html></h2></html>
2912
2913<HTML>
2914<h3 class=macro_signature>(lowercase: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>String</i></h3>
2915</HTML>
2916This macro produces a lowercase version of the given [[harlowe:string|string]].
2917
2918=== Example usage: ===
2919
2920''%%(lowercase: "GrImAcE")%%'' is the same as ''%%"grimace"%%''
2921
2922=== Details: ===
2923
2924The results of this macro for non-ASCII characters currently depends on the player's browser's Unicode\\
2925support. For instance, 'İ' in lowercase should be 'i̇', but some browsers don't support this.
2926
2927=== See also: ===
2928
2929[[harlowe:uppercase|(uppercase:)]], [[harlowe:lowerfirst|(lowerfirst:)]], [[harlowe:upperfirst|(upperfirst:)]]\\
2930<html><h2 class='def_title macro_title' id=macro_lowerfirst><a class='heading_link' href=#macro_lowerfirst></a></html>The (lowerfirst: ) macro<html></h2></html>
2931
2932<HTML>
2933<h3 class=macro_signature>(lowerfirst: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>String</i></h3>
2934</HTML>
2935This macro produces a version of the given [[harlowe:string|string]], where the first alphanumeric character is lowercase, and\\
2936other characters are left as-is.
2937
2938=== Example usage: ===
2939
2940''%%(lowerfirst: " College B")%%'' is the same as ''%%" college B"%%''
2941
2942=== Details: ===
2943
2944If the first alphanumeric character cannot change case (for instance, if it's a [[harlowe:number|number]]) then nothing\\
2945will change in the string. So, "8DX" won't become "8dX".
2946
2947The results of this macro for non-ASCII characters currently depends on the player's browser's Unicode\\
2948support. For instance, 'İ' in lowercase should be 'i̇', but some browsers don't support this.
2949
2950=== See also: ===
2951
2952[[harlowe:uppercase|(uppercase:)]], [[harlowe:lowercase|(lowercase:)]], [[harlowe:upperfirst|(upperfirst:)]]\\
2953<html><h2 class='def_title macro_title' id=macro_text><a class='heading_link' href=#macro_text></a></html>The (text: ) macro<html></h2></html>
2954
2955<HTML>
2956<h3 class=macro_signature>(text: <i> <span class=parameter_rest>...</span><span class=parameter_optional>\[</span>[[harlowe:Number|number]] or [[harlowe:String|string]] or [[harlowe:Boolean|boolean]] or [[harlowe:Array|array]]<span class=parameter_optional>\]</span></i>) <span class=macro_returntype>→</span> <i>String</i></h3>
2957</HTML>
2958Also known as: [[harlowe:string|(string:)]]
2959
2960(text:) accepts any amount of expressions and tries to convert them all\\
2961to a single String.
2962
2963=== Example usages: ===
2964
2965 * ''%%(text: $cash + 200)%%''
2966 * ''%%(if: (text: $cash)'s length > 3)[Phew! Over four digits!]%%''
2967 * ''%%(text: ...$arr)%%''
2968
2969=== Rationale: ===
2970
2971Unlike in Twine 1 and SugarCube, Twine 2 will only convert [[harlowe:number|number]] into [[harlowe:string|string]], or strings\\
2972into numbers, if you explictly ask it to. This extra carefulness decreases\\
2973the likelihood of unusual bugs creeping into stories (such as adding 1 and "22"\\
2974and getting "122"). The (text:) macro (along with [[harlowe:num|(num:)]]) is how you can convert\\
2975non-string values to a string.
2976
2977=== Details: ===
2978
2979This macro can also be used much like the [[harlowe:print|(print:)]] macro - as it evaluates to a\\
2980string, and strings can be placed in the story source freely,
2981
2982If you give an [[harlowe:array|array]] to (text:), it will attempt to convert every element\\
2983contained in the array to a String, and then join them up with commas. So,\\
2984''%%(text: (a: 2, "Hot", 4, "U"))%%'' will result in the string "2,Hot,4,U".\\
2985If you'd rather this not occur, you can also pass the array's individual\\
2986elements using the ''%%...%%'' operator - this will join them with nothing in between.\\
2987So, ''%%(text: ...(a: 2, "Hot", 4, "U"))%%'' will result in the string "2Hot4U".
2988
2989=== See also: ===
2990
2991[[harlowe:num|(num:)]]\\
2992<html><h2 class='def_title macro_title' id=macro_uppercase><a class='heading_link' href=#macro_uppercase></a></html>The (uppercase: ) macro<html></h2></html>
2993
2994<HTML>
2995<h3 class=macro_signature>(uppercase: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>String</i></h3>
2996</HTML>
2997This macro produces an uppercase version of the given [[harlowe:string|string]].
2998
2999=== Example usage: ===
3000
3001''%%(uppercase: "GrImAcE")%%'' is the same as ''%%"GRIMACE"%%''
3002
3003=== Details: ===
3004
3005The results of this macro for non-ASCII characters currently depends on the player's browser's Unicode\\
3006support. For instance, 'ß' in uppercase should be 'SS', but some browsers don't support this.
3007
3008=== See also: ===
3009
3010[[harlowe:lowercase|(lowercase:)]], [[harlowe:upperfirst|(upperfirst:)]], [[harlowe:lowerfirst|(lowerfirst:)]]\\
3011<html><h2 class='def_title macro_title' id=macro_upperfirst><a class='heading_link' href=#macro_upperfirst></a></html>The (upperfirst: ) macro<html></h2></html>
3012
3013<HTML>
3014<h3 class=macro_signature>(upperfirst: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>String</i></h3>
3015</HTML>
3016This macro produces a version of the given [[harlowe:string|string]], where the first alphanumeric character is uppercase, and\\
3017other characters are left as-is.
3018
3019=== Example usage: ===
3020
3021''%%(upperfirst: " college B")%%'' is the same as ''%%" College B"%%''
3022
3023=== Details: ===
3024
3025If the first alphanumeric character cannot change case (for instance, if it's a [[harlowe:number|number]]) then nothing\\
3026will change in the string. So, "4ever" won't become "4Ever".
3027
3028The results of this macro for non-ASCII characters currently depends on the player's browser's Unicode\\
3029support. For instance, 'ß' in uppercase should be 'SS', but some browsers don't support this.
3030
3031=== See also: ===
3032
3033[[harlowe:uppercase|(uppercase:)]], [[harlowe:lowercase|(lowercase:)]], [[harlowe:lowerfirst|(lowerfirst:)]]\\
3034<html><h2 class='def_title macro_title' id=macro_words><a class='heading_link' href=#macro_words></a></html>The (words: ) macro<html></h2></html>
3035
3036<HTML>
3037<h3 class=macro_signature>(words: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Array|array]]</i></h3>
3038</HTML>
3039This macro takes a [[harlowe:string|string]] and creates an [[harlowe:array|array]] of each word ("word" meaning a sequence of non-whitespace\\
3040characters) in the string.
3041
3042=== Example usage: ===
3043
3044''%%(words: "god-king Torment's peril")%%'' is the same as ''%%(a: "god-king", "Torment's", "peril")%%''
3045
3046=== Rationale: ===
3047
3048It can be useful to explicitly distinguish individual words within a string, in a manner not possible\\
3049with just the ''%%contains%%'' operator - for instance, seeing if a string contains the bare word "to" - not "torn"\\
3050or any other larger word. This macro allows a string's words to be split up and examined individually -\\
3051you can safely check if ''%%(words: $a) contains "to"%%'', or check on a particular word in the sequence by\\
3052asking if, say, ''%%(words: $a)'s 2nd is 'goose'%%''.
3053
3054=== Details: ===
3055
3056If the string was empty or contained only whitespace, then this will create an empty array. Moreover,\\
3057if the string contained no whitespace, then the array will contain just the entire original string.
3058
3059The whitespace characters recognised by this macro include line breaks, non-breaking spaces, and other uncommon\\
3060space characters.
3061
3062=== See also: ===
3063
3064[[harlowe:startcase|(startcase:)]]\\
3065<html><h2 class='def_title macro_title' id=macro_align><a class='heading_link' href=#macro_align></a></html>The (align: ) macro<html></h2></html>
3066
3067<HTML>
3068<h3 class=macro_signature>(align: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3069</HTML>
3070This styling [[harlowe:command|command]] changes the alignment of text in the attached hook, as if the\\
3071''%%===>%%''~ arrow syntax was used. In fact, these same arrows (''%%==>%%''~, ''%%=><=%%''~, ''%%<==>%%''~, ''%%====><=%%''~ etc.)\\
3072should be supplied as a [[harlowe:string|string]] to specify the degree of alignment.
3073
3074=== Example usage: ===
3075
3076''%%(align: "=><==")[Hmm? Anything the matter?]%%''
3077
3078=== Details: ===
3079
3080Hooks affected by this command will take up their own lines in the passage, regardless of\\
3081their placement in the story prose. This allows them to be aligned in the specified manner.\\
3082<html><h2 class='def_title macro_title' id=macro_background><a class='heading_link' href=#macro_background></a></html>The (background: ) macro<html></h2></html>
3083
3084<HTML>
3085<h3 class=macro_signature>(background: <i> [[harlowe:Colour|colour]] or [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3086</HTML>
3087This styling [[harlowe:command|command]] alters the background [[harlowe:colour|colour]] or background image\\
3088of the attached hook. Supplying a colour, or a [[harlowe:string|string]] contanining a CSS\\
3089hexadecimal colour (such as ''%%#A6A612%%'') will set the background to a flat colour.\\
3090Other strings will be interpreted as an image URL, and the background will be\\
3091set to it.
3092
3093=== Example usage: ===
3094
3095 * ''%%(background: red + white)[Pink background]%%''
3096 * ''%%(background: "#663399")[Purple background]%%''
3097 * ''%%(background: "marble.png")[Marble texture background]%%''
3098
3099=== Details: ===
3100
3101Combining two (background:) commands will do nothing if they both influence the\\
3102colour or the image. For instance ''%%(background:red) + (background:white)%%'' will simply\\
3103produce the equivalent ''%%(background:white)%%''. However, ''%%(background:red) + (background:"mottled.png")%%''\\
3104will work as intended if the background image contains transparency, allowing the background\\
3105colour to appear through it.
3106
3107Currently, supplying other CSS colour names (such as ''%%burlywood%%'') is not\\
3108permitted - they will be interpreted as image URLs regardless.
3109
3110No error will be reported if the image at the given URL cannot be accessed.
3111
3112=== See also: ===
3113
3114[[harlowe:colour|(colour:)]]\\
3115<html><h2 class='def_title macro_title' id=macro_css><a class='heading_link' href=#macro_css></a></html>The (css: ) macro<html></h2></html>
3116
3117<HTML>
3118<h3 class=macro_signature>(css: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3119</HTML>
3120This takes a [[harlowe:string|string]] of inline CSS, and applies it to the hook, as if it\\
3121were a HTML "style" property.
3122
3123=== Usage example: ===
3124
3125<code>
3126(css: "background-color:indigo")
3127</code>
3128=== Rationale: ===
3129
3130The built-in macros for layout and styling hooks, such as [[harlowe:text-style|(text-style:)]],\\
3131are powerful and geared toward ease-of-use, but do not entirely provide\\
3132comprehensive access to the browser's styling. This [[harlowe:changer|changer]] macro allows\\
3133extended styling, using inline CSS, to be applied to hooks.
3134
3135This is, however, intended solely as a "macro of last resort" - as it requires\\
3136basic knowledge of CSS - a separate language distinct from Harlowe - to use,\\
3137and requires it be provided a single inert string, it's not as accommodating as\\
3138the other such macros.
3139
3140=== See also: ===
3141
3142[[harlowe:text-style|(text-style:)]]\\
3143<html><h2 class='def_title macro_title' id=macro_font><a class='heading_link' href=#macro_font></a></html>The (font: ) macro<html></h2></html>
3144
3145<HTML>
3146<h3 class=macro_signature>(font: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3147</HTML>
3148This styling [[harlowe:command|command]] changes the font used to display the text of the attached hook. Provide\\
3149the font's family name (such as "Helvetica Neue" or "Courier") as a [[harlowe:string|string]].
3150
3151=== Example usage: ===
3152
3153''%%(font:"Skia")[And what have we here?]%%''
3154
3155=== Details: ===
3156
3157Currently, this command will only work if the font is available to the player's browser.\\
3158If font files are embedded in your story stylesheet using base64 (an explanation for which\\
3159is beyond the scope of this macro's description) then it can be uses instead.
3160
3161No error will be reported if the provided font name is not available, invalid or misspelled.
3162
3163=== See also: ===
3164
3165[[harlowe:text-style|(text-style:)]]\\
3166<html><h2 class='def_title macro_title' id=macro_hook><a class='heading_link' href=#macro_hook></a></html>The (hook: ) macro<html></h2></html>
3167
3168<HTML>
3169<h3 class=macro_signature>(hook: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3170</HTML>
3171A [[harlowe:command|command]] that allows the author to give a hook a computed tag name.
3172
3173=== Example usage: ===
3174
3175''%%(hook: $name)[]%%''
3176
3177=== Rationale: ===
3178
3179You may notice that it isn't possible to attach a nametag to hooks with commands\\
3180already attached - in the case of ''%%(font:"Museo Slab")[The Vault]<title|%%'', the nametag results\\
3181in an error. This command can be added with other commands to allow the hook to be named:\\
3182''%%(font:"Museo Slab")+(hook: "title")%%''.
3183
3184Furthermore, unlike the nametag syntax, (hook:) can be given any [[harlowe:string|string]] expression:\\
3185''%%(hook: "eyes" + (string:$eyeCount))%%'' is valid, and will, as you'd expect, give the hook\\
3186the name of ''%%eyes1%%'' if ''%%$eyeCount%%'' is 1.
3187
3188=== See also: ===
3189
3190[[harlowe:hidden|(hidden:)]]\\
3191<html><h2 class='def_title macro_title' id=macro_hover-style><a class='heading_link' href=#macro_hover-style></a></html>The (hover-style: ) macro<html></h2></html>
3192
3193<HTML>
3194<h3 class=macro_signature>(hover-style: <i> [[harlowe:Changer|changer]]</i>) <span class=macro_returntype>→</span> <i>Changer</i></h3>
3195</HTML>
3196Given a style-altering [[harlowe:changer|changer]], it makes a changer which only applies when the hook or expression is hovered over\\
3197with the mouse pointer, and is removed when hovering off.
3198
3199=== Example usage: ===
3200
3201The following makes a [[harlowe:link|(link:)]] that turns cyan and italic when the mouse hovers over it.
3202
3203<code>
3204(hover-style:(text-color:cyan) + (text-style:'italic'))+(link:"The lake")
3205[The still, cold lake.]
3206</code>
3207=== Rationale: ===
3208
3209Making text react in small visual ways when the pointer hovers over it is an old hypertext tradition. It lends a\\
3210degree of "life" to the text, making it seem aware of the player. This feeling of life is best used to signify\\
3211interactivity - it seems to invite the player to answer in turn, by clicking. So, adding them to [[harlowe:link|(link:)]] changers,\\
3212instead of just bare words or paragraphs, is highly recommended.
3213
3214=== Details: ===
3215
3216True to its name, this macro can only be used for subtle style changes. Only the following changers (and combinations\\
3217thereof) may be given to (hover-style:) - any others will produce an error:
3218
3219 * [[harlowe:align|(align:)]]
3220 * [[harlowe:background|(background:)]]
3221 * [[harlowe:css|(css:)]]
3222 * [[harlowe:font|(font:)]]
3223 * [[harlowe:text-colour|(text-colour:)]]
3224 * [[harlowe:text-rotate|(text-rotate:)]]
3225 * [[harlowe:text-style|(text-style:)]]
3226
3227More extensive mouse-based interactivity should use the [[harlowe:mouseover|(mouseover:)]] and [[harlowe:mouseout|(mouseout:)]] macros.
3228
3229This macro is not recommended for use in games or stories intended for use on touch devices, as\\
3230the concept of "hovering" over an element doesn't really make sense with that input method.
3231
3232=== See also: ===
3233
3234[[harlowe:mouseover|(mouseover:)]], [[harlowe:mouseout|(mouseout:)]]\\
3235<html><h2 class='def_title macro_title' id=macro_text-colour><a class='heading_link' href=#macro_text-colour></a></html>The (text-colour: ) macro<html></h2></html>
3236
3237<HTML>
3238<h3 class=macro_signature>(text-colour: <i> [[harlowe:String|string]] or [[harlowe:Colour|colour]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3239</HTML>
3240Also known as: [[harlowe:colour|(colour:)]], [[harlowe:text-color|(text-color:)]], [[harlowe:color|(color:)]]
3241
3242This styling [[harlowe:command|command]] changes the [[harlowe:colour|colour]] used by the text in the attached hook.\\
3243You can supply either a [[harlowe:string|string]] with a CSS-style colour (a colour name or\\
3244RGB [[harlowe:number|number]] supported by CSS), or a built-in colour object.
3245
3246=== Example usage: ===
3247
3248''%%(colour: red + white)[Pink]%%'' combines the built-in red and white colours to make pink.\\
3249''%%(colour: "#696969")[Gray]%%'' uses a CSS-style colour to style the text gray.
3250
3251=== Details: ===
3252
3253This macro only affects the text colour. To change the text background, call upon\\
3254the [[harlowe:background|(background:)]] macro.
3255
3256=== See also: ===
3257
3258[[harlowe:background|(background:)]]\\
3259<html><h2 class='def_title macro_title' id=macro_text-rotate><a class='heading_link' href=#macro_text-rotate></a></html>The (text-rotate: ) macro<html></h2></html>
3260
3261<HTML>
3262<h3 class=macro_signature>(text-rotate: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3263</HTML>
3264This styling [[harlowe:command|command]] visually rotates the attached hook clockwise by a given [[harlowe:number|number]] of\\
3265degrees. The rotational axis is in the centre of the hook.
3266
3267=== Example usage: ===
3268
3269''%%(text-rotate:45)[Tilted]%%'' will produce <html><span style="display:inline-block;transform:rotate(45deg);"></html>Tilted<html></span></html>
3270
3271=== Details: ===
3272
3273The surrounding non-rotated text will behave as if the rotated text is still in its original position -\\
3274the horizontal space of its original length will be preserved, and text it overlaps with vertically will\\
3275ignore it.
3276
3277A rotation of 180 degrees will, due to the rotational axis, flip the hook upside-down and back-to-front, as\\
3278if the [[harlowe:text-style|(text-style:)]] styles "mirror" and "upside-down" were both applied.
3279
3280Due to browser limitations, hooks using this macro will have its CSS ''%%display%%'' attribute\\
3281set to ''%%inline-block%%''.
3282
3283=== See also: ===
3284
3285[[harlowe:text-style|(text-style:)]]\\
3286<html><h2 class='def_title macro_title' id=macro_text-style><a class='heading_link' href=#macro_text-style></a></html>The (text-style: ) macro<html></h2></html>
3287
3288<HTML>
3289<h3 class=macro_signature>(text-style: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3290</HTML>
3291This applies a selected built-in text style to the hook's text.
3292
3293=== Example usage: ===
3294
3295''%%The shadow (text-style: "shadow")[flares] at you!%%'' will style the word "flares" with a shadow.
3296
3297''%%(set: $s to (text-style: "shadow")) The shadow $s[flares] at you!%%'' will also style it with a shadow.
3298
3299=== Rationale: ===
3300
3301While Twine offers markup for common formatting styles like bold and italic, having these\\
3302styles available from a [[harlowe:command|command]] macro provides some extra benefits: it's possible, as with all\\
3303such style macros, to [[harlowe:set|(set:)]] them into a variable, combine them with other commands, and re-use them\\
3304succinctly throughout the story (by using the variable in place of the macro).
3305
3306Furthermore, this macro also offers many less common but equally desirable styles to the author,\\
3307which are otherwise unavailable or difficult to produce.
3308
3309=== Details: ===
3310
3311At present, the following text [[harlowe:string|string]] will produce a particular style.
3312
3313^String ^
3314|"none" |
3315|"bold" |
3316|"italic" |
3317|"underline" |
3318|"strike" |
3319|"superscript"|
3320|"subscript" |
3321|"mark" |
3322|"outline" |
3323|"shadow" |
3324|"emboss" |
3325|"condense" |
3326|"expand" |
3327|"blur" |
3328|"blurrier" |
3329|"smear" |
3330|"mirror" |
3331|"upside-down"|
3332|"blink" |
3333|"fade-in-out"|
3334|"rumble" |
3335|"shudder" |
3336
3337You can use the "none" style to remove an existing style from a combined [[harlowe:changer|changer]].
3338
3339Due to browser limitations, hooks using "mirror", "upside-down", "rumble" or "shudder" will have its CSS ''%%display%%''\\
3340attribute set to ''%%inline-block%%''.
3341
3342=== See also: ===
3343
3344[[harlowe:css|(css:)]]\\
3345<html><h2 class='def_title macro_title' id=macro_transition-time><a class='heading_link' href=#macro_transition-time></a></html>The (transition-time: ) macro<html></h2></html>
3346
3347<HTML>
3348<h3 class=macro_signature>(transition-time: <i> [[harlowe:Number|number]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3349</HTML>
3350Also known as: [[harlowe:t8n-time|(t8n-time:)]]
3351
3352A [[harlowe:command|command]] that, when added to a [[harlowe:transition|(transition:)]] command, adjusts the time of the transition.
3353
3354=== Example usage: ===
3355
3356''%%(set: $slowTransition to (transition:"shudder") + (transition-time: 2s))%%'' creates a transition\\
3357style which uses "shudder" and takes 2 seconds.
3358
3359=== Details: ===
3360
3361Much like [[harlowe:live|(live:)]], this macro should be given a [[harlowe:number|number]] of milliseconds (such as ''%%50ms%%'') or seconds\\
3362(such as ''%%10s%%''). Providing 0 or fewer seconds/milliseconds is not permitted and will result in an error.
3363
3364=== See also: ===
3365
3366[[harlowe:transition|(transition:)]]\\
3367<html><h2 class='def_title macro_title' id=macro_transition><a class='heading_link' href=#macro_transition></a></html>The (transition: ) macro<html></h2></html>
3368
3369<HTML>
3370<h3 class=macro_signature>(transition: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Changer|changer]]</i></h3>
3371</HTML>
3372Also known as: [[harlowe:t8n|(t8n:)]]
3373
3374A [[harlowe:command|command]] that applies a built-in CSS transition to a hook as it appears.
3375
3376=== Example usage: ===
3377
3378''%%(transition: "pulse")[Gleep!]%%'' makes the hook ''%%[Gleep!]%%'' use the "pulse" transition\\
3379when it appears.
3380
3381=== Details: ===
3382
3383At present, the following text [[harlowe:string|string]] will produce a particular transition:
3384
3385 * "dissolve" (causes the hook to gently fade in)
3386 * "shudder" (causes the hook to instantly appear while shaking back and forth)
3387 * "pulse" (causes the hook to instantly appear while pulsating rapidly)
3388
3389All transitions are 0.8 seconds long, unless a [[harlowe:transition-time|(transition-time:)]] command is added\\
3390to the command.
3391
3392=== See also: ===
3393
3394[[harlowe:text-style|(text-style:)]], [[harlowe:transition-time|(transition-time:)]]\\
3395<html><h2 class='def_title macro_title' id=macro_goto-url><a class='heading_link' href=#macro_goto-url></a></html>The (goto-url: ) macro<html></h2></html>
3396
3397<HTML>
3398<h3 class=macro_signature>(goto-url: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
3399</HTML>
3400When this [[harlowe:command|command]] is used, the player's browser will immediately attempt to leave\\
3401the story's page, and navigate to the given URL in the same tab. If this succeeds, then\\
3402the story session will "end".
3403
3404=== Example usage: ===
3405
3406''%%(goto-url: "http://www.example.org/")%%''
3407
3408=== Details: ===
3409
3410If the given URL is invalid, no error will be reported - the browser will simply attempt to\\
3411open it anyway.
3412
3413Much like the ''%%<a>%%'' HTML element, the URL is treated as a relative URL if it doesn't start\\
3414with "http://", "https://", or another such protocol. This means that if your story file is\\
3415hosted at "http://www.example.org/story.html", then ''%%(open-url: "page2.html")%%'' will actually open\\
3416the URL "http://www.example.org/page2.html".
3417
3418=== See also: ===
3419
3420[[harlowe:open-url|(open-url:)]]\\
3421<html><h2 class='def_title macro_title' id=macro_open-url><a class='heading_link' href=#macro_open-url></a></html>The (open-url: ) macro<html></h2></html>
3422
3423<HTML>
3424<h3 class=macro_signature>(open-url: <i> [[harlowe:String|string]]</i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
3425</HTML>
3426When this macro is evaluated, the player's browser attempts to open a new tab with the given\\
3427URL. This will usually require confirmation from the player, as most browsers block\\
3428Javascript programs such as Harlowe from opening tabs by default.
3429
3430=== Example usage: ===
3431
3432''%%(open-url: "http://www.example.org/")%%''
3433
3434=== Details: ===
3435
3436If the given URL is invalid, no error will be reported - the browser will simply attempt to\\
3437open it anyway.
3438
3439Much like the ''%%<a>%%'' HTML element, the URL is treated as a relative URL if it doesn't start\\
3440with "http://", "https://", or another such protocol. This means that if your story file is\\
3441hosted at "http://www.example.org/story.html", then ''%%(open-url: "page2.html")%%'' will actually open\\
3442the URL "http://www.example.org/page2.html".
3443
3444=== See also: ===
3445
3446[[harlowe:goto-url|(goto-url:)]]\\
3447<html><h2 class='def_title macro_title' id=macro_page-url><a class='heading_link' href=#macro_page-url></a></html>The (page-url: ) macro<html></h2></html>
3448
3449<HTML>
3450<h3 class=macro_signature>(page-url: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:String|string]]</i></h3>
3451</HTML>
3452This macro produces the full URL of the story's HTML page, as it is in the player's browser.
3453
3454=== Example usage: ===
3455
3456''%%(if: (page-url:) contains "#cellar")%%'' will be true if the URL contains the ''%%#cellar%%'' hash.
3457
3458=== Details: ===
3459
3460This **may** be changed in a future version of Harlowe to return a [[harlowe:datamap|datamap]] containing more\\
3461descriptive values about the URL, instead of a single [[harlowe:string|string]].\\
3462<html><h2 class='def_title macro_title' id=macro_reload><a class='heading_link' href=#macro_reload></a></html>The (reload: ) macro<html></h2></html>
3463
3464<HTML>
3465<h3 class=macro_signature>(reload: <i></i>) <span class=macro_returntype>→</span> <i>[[harlowe:Command|command]]</i></h3>
3466</HTML>
3467When this [[harlowe:command|command]] is used, the player's browser will immediately attempt to reload\\
3468the page, in effect restarting the entire story.
3469
3470=== Example usage: ===
3471
3472''%%(click:"Restart")[(reload:)]%%''
3473
3474=== Details: ===
3475
3476If the first passage in the story contains this macro, the story will be caught in a "reload\\
3477loop", and won't be able to proceed. No error will be reported in this case.\\
3478<html><h2 class='def_title macro_title' id=macro_substring><a class='heading_link' href=#macro_substring></a></html>The (substring: ) macro<html></h2></html>
3479
3480<HTML>
3481<h3 class=macro_signature>(substring: <i> [[harlowe:String|string]], [[harlowe:Number|number]], Number</i>) <span class=macro_returntype>→</span> <i>String</i></h3>
3482</HTML>
3483This macro produces a substring of the given [[harlowe:string|string]], cut from two inclusive [[harlowe:number|number]] positions.
3484
3485=== Example usage: ===
3486
3487''%%(substring: "growl", 3, 5)%%'' is the same as ''%%"growl"'s (a:3,4,5)%%''
3488
3489=== Rationale: ===
3490
3491You can obtain substrings of strings without this macro, by using the ''%%'s%%'' or ''%%of%%'' syntax along\\
3492with an [[harlowe:array|array]] of positions. For instance, ''%%$str's (range:4,12)%%'' obtains a substring of $str containing\\
3493its 4th through 12th characters. But, for compatibility with previous Harlowe versions which did not\\
3494feature this syntax, this macro also exists.
3495
3496=== Details: ===
3497
3498If you provide negative numbers, they will be treated as being offset from the end\\
3499of the string - ''%%-2%%'' will specify the ''%%2ndlast%%'' character, just as 2 will specify\\
3500the ''%%2nd%%'' character.
3501
3502If the last number given is smaller than the first (for instance, in ''%%(substring: "hewed", 4, 2)%%'')\\
3503then the macro will still work - in that case returning "ewe" as if the numbers were in\\
3504the correct order.
3505
3506=== See also: ===
3507
3508[[harlowe:subarray|(subarray:)]]\\
3509<html><h2 class='def_title macro_title' id=macro_subarray><a class='heading_link' href=#macro_subarray></a></html>The (subarray: ) macro<html></h2></html>
3510
3511<HTML>
3512<h3 class=macro_signature>(subarray: <i> [[harlowe:Array|array]], [[harlowe:Number|number]], Number</i>) <span class=macro_returntype>→</span> <i>Array</i></h3>
3513</HTML>
3514When given an [[harlowe:array|array]], this returns a new array containing only the elements\\
3515whose positions are between the two [[harlowe:number|number]], inclusively.
3516
3517=== Example usage: ===
3518
3519''%%(subarray: $a, 3, 4)%%'' is the same as ''%%$a's (a:3,4)%%''
3520
3521=== Rationale: ===
3522
3523You can obtain subarrays of arrays without this macro, by using the ''%%'s%%'' or ''%%of%%'' syntax along\\
3524with an array of positions. For instance, ''%%$a's (range:4,12)%%'' obtains a subarray of $a containing\\
3525its 4th through 12th values. But, for compatibility with previous Harlowe versions which did not\\
3526feature this syntax, this macro also exists.
3527
3528=== Details: ===
3529
3530If you provide negative numbers, they will be treated as being offset from the end\\
3531of the array - ''%%-2%%'' will specify the ''%%2ndlast%%'' item, just as 2 will specify\\
3532the ''%%2nd%%'' item.
3533
3534If the last number given is larger than the first (for instance, in ''%%(subarray: (a:1,2,3,4), 4, 2)%%'')\\
3535then the macro will still work - in that case returning (a:2,3,4) as if the numbers were in\\
3536the correct order.
3537
3538=== See also: ===
3539
3540[[harlowe:substring|(substring:)]], [[harlowe:rotated|(rotated:)]]\\
3541<html><h1 id=section_type></html>Types of data<html></h1></html>
3542
3543<HTML>
3544<h2 class='def_title type_title' id=type_any><a class='heading_link' href=#type_any></a>Any data
3545</h2>
3546</HTML>
3547A macro that is said to accept "Any" will accept any kind of data\\
3548without complaint, as long as the data does not contain any errors.\\
3549<html><h2 class='def_title type_title' id=type_array><a class='heading_link' href=#type_array></a></html>Array data\\
3550<html></h2></html>
3551
3552There are occasions when you may need to work with a whole sequence of values at once.\\
3553For example, a sequence of adjectives (describing the player) that should be printed depending\\
3554on what a numeric variable (such as a health point variable) currently is.\\
3555You could create many, many variables to hold each value, but it is preferable to\\
3556use an array containing these values.
3557
3558Arrays are one of the two major "data structures" you can use in Harlowe. The other, [[harlowe:datamap|datamap]],\\
3559are created with [[harlowe:dm|(dm:)]]. Generally, you want to use arrays when you're dealing with values that\\
3560directly correspond to //[[harlowe:number|number]]//, and whose //order// and //position// relative to each other matter.\\
3561If you instead need to refer to values by a name, and don't care about their order, a datamap is best used.
3562
3563You can refer to and extract data at certain positions inside arrays using ''%%1st%%'', ''%%2nd%%'', ''%%3rd%%'', and so forth:\\
3564''%%$array's 1st%%'', also written as ''%%1st of $array%%'', refers to the value in the first position. Additionally, you can\\
3565use ''%%last%%'' to refer to the last position, ''%%2ndlast%%'' to refer to the second-last, and so forth. Arrays also have\\
3566a ''%%length%%'' number: ''%%$array's length%%'' tells you how many values are in it. If you don't know the exact position\\
3567to remove an item from, you can use an expression, in brackers, after it: ''%%$array's ($pos - 3)%%''.
3568
3569To see if arrays contain certain values, you can use the ''%%contains%%'' and ''%%is in%%'' operators like so: ''%%$array contains 1%%''\\
3570is true if it contains the number 1 anywhere, and false if it does not. ''%%1 is in $array%%'' is another way to write that.\\
3571If you want to check if an array contains some, or all of the values, in another array, you can compare with a special\\
3572''%%any%%'' or ''%%all%%'' name on the other array: ''%%$array contains any of (a:2,4,6)%%'', and ''%%$array contains all of (a:2,4,6)%%''\\
3573will check if ''%%$array%%'' contains some, or all, of the numbers 2, 4 and 6.
3574
3575(Incidentally, ''%%any%%'' and ''%%all%%'' can also be used with other operators, like ''%%is%%'', ''%%is not%%'', ''%%>%%'', ''%%<%%'', ''%%>=%%'', and ''%%<=%%'',\\
3576to compare every value in the array with a number or other value. For instance, ''%%all of (a:2,4) >= 2%%'' is true, as is\\
3577''%%any of (a:2,4) >= 4%%''.)
3578
3579Arrays may be joined by adding them together: ''%%(a: 1, 2) + (a: 3, 4)%%'' is the same as ''%%(a: 1, 2, 3, 4)%%''.\\
3580You can only join arrays to other arrays. To add a bare value to the front or back of an array, you must\\
3581put it into an otherwise empty array using the [[harlowe:a|(a:)]] macro: ''%%$myArray + (a:5)%%'' will make an array that's just\\
3582$myArray with 5 added on the end, and ''%%(a:0) + $myArray%%'' is $myArray with 0 at the start.
3583
3584You can make a subarray by providing a range (an array of numbers, such as\\
3585those created with [[harlowe:range|(range:)]]) as a reference - ''%%$arr's (a:1,2)%%'' produces an array with only the first 2 values of $arr.\\
3586Additionally, you can subtract items from arrays (that is, create a copy of an array with certain values removed) using\\
3587the ''%%-%%'' operator: ''%%(a:"B","C") - (a:"B")%%'' produces ''%%(a:"C")%%''. Note that multiple copies of a value in an array will all\\
3588be removed by doing this: ''%%(a:"B","B","B","C") - (a:"B")%%'' also produces ''%%(a:"C")%%''.
3589
3590You may note that certain macros, like [[harlowe:either|(either:)]], accept sequences of values. A special operator, ''%%...%%'', exists which\\
3591can "spread out" the values inside an array, as if they were individually placed inside the macro call.\\
3592''%%(either: ...$array)%%'' is a shorthand for ''%%(either: $array's 1st, $array's 2nd, $array's 3rd)%%'', and so forth for as many\\
3593values as there are inside the $array. Note that you can still include values after the spread: ''%%(either: 1, ...$array, 5)%%''\\
3594is valid and works as expected.
3595
3596To summarise, the following operators work on arrays.
3597
3598^Operator ^
3599|''%%is%%'' |
3600|''%%is not%%'' |
3601|''%%contains%%''|
3602|''%%is in%%'' |
3603|''%%+%%'' |
3604|''%%-%%'' |
3605|''%%...%%'' |
3606|''%%'s%%'' |
3607|''%%of%%'' |
3608
3609<HTML>
3610<h2 class='def_title type_title' id=type_boolean><a class='heading_link' href=#type_boolean></a>Boolean data
3611</h2>
3612</HTML>
3613Computers can perform more than just mathematical tasks - they are also virtuosos in classical logic. Much as how\\
3614arithmetic involves manipulating [[harlowe:number|number]] with addition, multiplication and such, logic involves manipulating the\\
3615values ''%%true%%'' and ''%%false%%'' using its own operators. Those are not text [[harlowe:string|string]] - they are values as fundamental as\\
3616the natural numbers. In computer science, they are both called //Booleans//, after the 19th century mathematician\\
3617George Boole.
3618
3619''%%is%%'' is a logical operator. Just as + adds the two numbers on each side of it, ''%%is%%'' compares two values on each\\
3620side and evaluates to ''%%true%%'' or ''%%false%%'' depending on whether they're identical. It works equally well with strings,\\
3621numbers, [[harlowe:array|array]], and anything else, but beware - the string ''%%"2"%%'' is not equal to the number 2.
3622
3623There are several other logical operators available.
3624
3625^Operator ^
3626|''%%is%%'' |
3627|''%%is not%%'' |
3628|''%%contains%%''|
3629|''%%is in%%'' |
3630|''%%>%%'' |
3631|''%%>=%%'' |
3632|''%%<%%'' |
3633|''%%<=%%'' |
3634|''%%and%%'' |
3635|''%%or%%'' |
3636|''%%not%%'' |
3637
3638Conditions can quickly become complicated. The best way to keep things straight is to use parentheses to\\
3639group things.\\
3640<html><h2 class='def_title type_title' id=type_changer><a class='heading_link' href=#type_changer></a></html>Changer data\\
3641<html></h2></html>
3642
3643Changer [[harlowe:command|command]] (changers) are similar to ordinary commands, but they only have an effect when they're attached to hooks,\\
3644and modify the hook in a certain manner. Macros that work like this include [[harlowe:text-style|(text-style:)]], [[harlowe:font|(font:)]], [[harlowe:transition|(transition:)]],\\
3645[[harlowe:text-rotate|(text-rotate:)]], [[harlowe:hook|(hook:)]], [[harlowe:click|(click:)]], [[harlowe:link|(link:)]], and more.
3646
3647You can save changer commands into variables, and re-use them many times in your story:
3648
3649<code>
3650(set: $robotic to (font:'Courier New'))
3651$robotic[Hi, it's me. Your clanky, cold friend.]
3652</code>
3653Alternatively, you may prefer to use the [[harlowe:enchant|(enchant:)]] macro to accomplish the same thing using only hook names:
3654
3655<code>
3656|robotic>[Hi, it's me. Your clanky, cold friend.]
3657(enchant: ?robotic, (font:'Courier New'))
3658</code>
3659Changers can be combined using the ''%%+%%'' operator: ''%%(text-colour: red) + (font: "Courier New")[This text is red Courier New.]%%''\\
3660styles the text using both changers at once. These combined changers, too, can be saved in variables or used with [[harlowe:enchant|(enchant:)]].
3661
3662<code>
3663(set: _alertText to (font:"Courier New") + (text-style: "shudder") + (text-colour:"#e74"))
3664_alertText[Social alert: no one read the emails you sent yesterday.]
3665_alertText[Arithmetic error: I forgot my seven-times-tables.]
3666</code>
3667<HTML>
3668<h2 class='def_title type_title' id=type_colour><a class='heading_link' href=#type_colour></a>Colour data
3669</h2>
3670</HTML>
3671Colours are special data values which can be provided to certain styling macros, such as [[harlowe:background|(background:)]]\\
3672or [[harlowe:text-colour|(text-colour:)]]. You can use built=in named colour values, or create other colours using the\\
3673[[harlowe:rgb|(rgb:)]] or [[harlowe:hsl|(hsl:)]] macros.
3674
3675The built-in values consist of the following:
3676
3677^Value ^
3678|''%%red%%'' |
3679|''%%orange%%'' |
3680|''%%yellow%%'' |
3681|''%%lime%%'' |
3682|''%%green%%'' |
3683|''%%aqua%%'' or ''%%cyan%%'' |
3684|''%%blue%%'' |
3685|''%%navy%%'' |
3686|''%%purple%%'' |
3687|''%%magenta%%'' or ''%%fuchsia%%''|
3688|''%%white%%'' |
3689|''%%black%%'' |
3690|''%%grey%%'' or ''%%gray%%'' |
3691
3692(These colours were chosen to be visually pleasing when used as both background colours and text colours, without\\
3693the glaring intensity that certain HTML colours, like pure #f00 red, are known to exhibit.)
3694
3695In addition to these values, and the [[harlowe:rgb|(rgb:)]] macro, you can also use HTML hex #xxxxxx and #xxx notation to specify\\
3696colours, such as ''%%#691212%%'' or ''%%#a4e%%''. (Note that these are //not// [[harlowe:string|string]], but bare values - ''%%(background: #a4e)%%''\\
3697is valid, as is ''%%(background:navy)%%''.) Of course, HTML hex notation is notoriously hard to read and write, so this\\
3698isn't recommended.
3699
3700If you want to quickly obtain a colour which is the blending of two others, you can blend them\\
3701using the ''%%+%%'' operator: ''%%red + orange + white%%'' produces a blend of red and orange, tinted\\
3702white. ''%%#a4e + black%%'' is a dim purple.
3703
3704Like [[harlowe:datamap|datamap]], colour values have a few read-only data names, which let you examine the **r**ed, **g**reen and **b**lue\\
3705components that make up the colour, as well as its **h**ue, **s**aturation and **l**ightness.
3706
3707^Data name^
3708|''%%r%%''|
3709|''%%g%%''|
3710|''%%b%%''|
3711|''%%h%%''|
3712|''%%s%%''|
3713|''%%l%%''|
3714
3715These values can be used in the [[harlowe:hsl|(hsl:)]] and [[harlowe:rgb|(rgb:)]] macros to produce further colours. Note that some of these values\\
3716do not transfer one-to-one between representations! For instance, the hue of a gray is essentially irrelevant, so grays\\
3717will usually have a ''%%h%%'' value equal to 0, even if you provided a different hue to [[harlowe:hsl|(hsl:)]]. Furthermore, colours with a\\
3718lightness of 1 are always white, so their saturation and hue are irrelevant.\\
3719<html><h2 class='def_title type_title' id=type_command><a class='heading_link' href=#type_command></a></html>Command data\\
3720<html></h2></html>
3721
3722Commands are special kinds of data which perform an effect when they're placed in the passage.\\
3723Most commands are created from macros placed directly in the passage, but, like all forms of\\
3724data, they can be saved into variables using [[harlowe:set|(set:)]] and [[harlowe:put|(put:)]], and stored for later use.
3725
3726Macros that produce commands include [[harlowe:display|(display:)]], [[harlowe:print|(print:)]], [[harlowe:go-to|(go-to:)]], [[harlowe:save-game|(save-game:)]], [[harlowe:load-game|(load-game:)]],\\
3727[[harlowe:link-goto|(link-goto:)]], and more.\\
3728<html><h2 class='def_title type_title' id=type_datamap><a class='heading_link' href=#type_datamap></a></html>Datamap data\\
3729<html></h2></html>
3730
3731There are occasions when you may need to work with collections of values that "belong" to a\\
3732specific object or entity in your story - for example, a table of numeric "statistics" for\\
3733a monster - or that associate a certain kind of value with another kind, such as a combination of\\
3734adjectives ("slash", "thump") that change depending on the player's weapon name ("claw", "mallet") etc.\\
3735You can create datamaps to keep these values together, move them around en masse, and organise them.
3736
3737Datamaps are one of the two major "data structures" you can use in Harlowe. The other, [[harlowe:array|array]],\\
3738are created with [[harlowe:a|(a:)]]. You'll want to use datamaps if you want to store values that directly correspond to //[[harlowe:string|string]]//,\\
3739and whose //order// and //position// do not matter. If you need to preserve the order of the values, then an array\\
3740may be better suited.
3741
3742Datamaps consist of several string //name//s, each of which maps to a specific //value//. ''%%$animals's frog%%'' and ''%%frog of $animals%%''\\
3743refers to the value associated with the name 'frog'. You can add new names or change existing values by using [[harlowe:set|(set:)]] -\\
3744''%%(set: $animals's wolf to "howl")%%''.
3745
3746You can express the name as a bare word if it doesn't have a space or other punctuation in it - ''%%$animals's frog%%'' is OK, but\\
3747''%%$animals's komodo dragon%%'' is not. In that case, you'll need to always supply it as a string - ''%%$animals's "komodo dragon"%%''.
3748
3749Datamaps may be joined by adding them together: ''%%(dm: "goose", "honk") + (dm: "robot", "whirr")%%'' is the same as\\
3750''%%(dm: "goose", "honk", "robot", "whirr")%%''. In the event that the second datamap has the same name as the first one,\\
3751it will override the first one's value - ''%%(dm: "dog", "woof") + (dm: "dog", "bark")%%'' will act as\\
3752''%%(dm: "dog", "bark")%%''.
3753
3754You may notice that you usually need to know the names a datamap contains in order to access its values. There are certain\\
3755macros which provide other ways of examining a datamap's contents: [[harlowe:datanames|(datanames:)]] provides a sorted array of its names,\\
3756[[harlowe:datavalues|(datavalues:)]] provides a sorted array of its values, and [[harlowe:dataentries|(dataentries:)]] provides an array of names and values.
3757
3758To summarise, the following operators work on datamaps.
3759
3760^Operator ^
3761|''%%is%%'' |
3762|''%%is not%%'' |
3763|''%%contains%%''|
3764|''%%is in%%'' |
3765|''%%+%%'' |
3766|''%%'s%%'' |
3767|''%%of%%'' |
3768
3769<HTML>
3770<h2 class='def_title type_title' id=type_dataset><a class='heading_link' href=#type_dataset></a>Dataset data
3771</h2>
3772</HTML>
3773[[harlowe:Array|array]] are useful for dealing with a sequence of related data values, especially if\\
3774they have a particular order. There are occasions, however, where you don't really\\
3775care about the order, and instead would simply use the [[harlowe:array|array]] as a storage place for\\
3776values - using ''%%contains%%'' and ''%%is in%%'' to check which values are inside.
3777
3778Think of datasets as being like arrays, but with specific restrictions:
3779
3780 * You can't access any positions within the dataset (so, for instance, the ''%%1st%%'', ''%%2ndlast%%''\\
3781and ''%%last%%'' aren't available, although the ''%%length%%'' still is) and can only use ''%%contains%%''\\
3782and ''%%is in%%'' to see whether a value is inside (or, by using ''%%any%%'' and ''%%all%%'', many values).
3783 * Datasets only contain unique values: adding the [[harlowe:string|string]] "Go" to a dataset already\\
3784containing "Go" will do nothing.
3785 * Datasets are considered equal (by the ''%%is%%'' operator) if they have the same items, regardless\\
3786of order (as they have no order).
3787
3788These restrictions can be helpful in that they can stop programming mistakes from\\
3789occurring - you might accidentally try to modify a position in an array, but type the name of\\
3790a different array that should not be modified as such. Using a dataset for the second\\
3791array, if that is what best suits it, will cause an error to occur instead of allowing\\
3792this unintended operation to continue.
3793
3794^Operator ^
3795|''%%is%%'' |
3796|''%%is not%%'' |
3797|''%%contains%%''|
3798|''%%is in%%'' |
3799|''%%+%%'' |
3800|''%%-%%'' |
3801|''%%...%%'' |
3802
3803<HTML>
3804<h2 class='def_title type_title' id=type_hookname><a class='heading_link' href=#type_hookname></a>HookName data
3805</h2>
3806</HTML>
3807A hook name is like a variable name, but with ''%%?%%'' replacing the ''%%$%%'' sigil. When given to a macro that accepts it,\\
3808it signifies that //all// hooks with the given name should be affected by the macro.\\
3809For instance, ''%%(click: ?red)%%'' will cause //all// hooks with a ''%%<red|%%'' or ''%%|red>%%'' nametag to be subject to the [[harlowe:click|(click:)]]\\
3810macro's behaviour.
3811
3812In earlier Harlowe versions, it was possible to also use hook names with [[harlowe:set|(set:)]], [[harlowe:put|(put:)]] and [[harlowe:move|(move:)]] to modify the\\
3813text of the hooks, but macros such as [[harlowe:replace|(replace:)]] should be used to accomplish this instead.
3814
3815If you only want some of the hooks with the given name to be affected, you can treat the hook name as a sort of read-only\\
3816[[harlowe:array|array]]: access its ''%%1st%%'' element (such as by ''%%?red's 1st%%'') to only affect the first such named hook in the passage, access\\
3817the ''%%last%%'' to affect the last, and so forth. (Even specifying an array of positions, like ''%%?red's (a:1,3,5)%%'', will work.)\\
3818Unlike arrays, though, you can't access their ''%%length%%'', nor can you spread them with ''%%...%%''.
3819
3820If you need to, you cal also add hook names together to affect both at the same time: ''%%(click: ?red + ?blue's 1st)%%'' will\\
3821affect all hooks tagged ''%%<red|%%'', as well as the first hook tagged ''%%<blue|%%''.
3822
3823Note: if a hook name does not apply to a single hook in the given passage (for instance, if you type ''%%?rde%%'' instead of\\
3824''%%?red%%'') then no error will be produced. This is to allow macros such as [[harlowe:click|(click:)]] to be placed in the ''%%header%%'' or ''%%footer%%''\\
3825passages, and thus easily affect hooks in every passage, even if individual passages lack the given hook name. Of course, it\\
3826means that you'll have to be extra careful while typing the hook name, as misspellings will not be easily identified\\
3827by Harlowe itself.\\
3828<html><h2 class='def_title type_title' id=type_instant><a class='heading_link' href=#type_instant></a></html>Instant data\\
3829<html></h2></html>
3830
3831A few special macros in Harlowe perform actions immediately, as soon as they're evaluated.\\
3832These can be used in passages, but cannot have their values saved using [[harlowe:set|(set:)]] or [[harlowe:put|(put:)]],\\
3833or stored in data structures.\\
3834<html><h2 class='def_title type_title' id=type_lambda><a class='heading_link' href=#type_lambda></a></html>Lambda data\\
3835<html></h2></html>
3836
3837Suppose you want to do a complicated task with an [[harlowe:array|array]], like, say, convert all of its [[harlowe:string|string]] to lowercase,\\
3838or check if its [[harlowe:datamap|datamap]] have "health" data equal to 0, or join all of its strings together\\
3839into a single string. You want to be able to tell Harlowe to search for "each string where the string's 1st\\
3840letter is A". You want to write a "function" for how the search is to be conducted.
3841
3842Lambdas are user-created functions that let you tell certain macros, like [[harlowe:find|(find:)]], [[harlowe:altered|(altered:)]] and [[harlowe:folded|(folded:)]],\\
3843precisely how to search, alter, or combine the data provided to them.
3844
3845There are several types of lambdas.
3846
3847 * "where" lambdas, used by the [[harlowe:find|(find:)]] macro, are used to search for and filter data. The lambda ''%%_item where _item's 1st is "A"%%'' tells the macro to searches for items whose ''%%1st%%'' is the string "A".
3848 * "via" lambdas, used by the [[harlowe:altered|(altered:)]] macro, are used to transform and change data. The lambda ''%%_item via _item + "s"%%''\\
3849tells the macro to add the string "s" to the end of each item.
3850 * "making" lambdas, used by the [[harlowe:folded|(folded:)]] are used to build or "make" a single data value by adding something from\\
3851each item to it. The lambda ''%%_item making _total via _total + (max: _item, 0)%%'' tells the macro to add each item to\\
3852the total, but only if the item is greater than 0. (Incidentally, you can also use "where" inside a "making" lambda -\\
3853you could rewrite that lambda as ''%%_item making _total via _total + _item where _item > 0%%''.)
3854 * For certain macros, like [[harlowe:for|(for:)]], you may want to use a "where" lambda that doesn't filter out any of the values -\\
3855''%%_item where true%%'', for instance, will include every item. There is a special, more readable shorthand for this type\\
3856of "where" lambda: writing just ''%%each _item%%'' is equivalent.
3857
3858Lambdas use temp variables as "placeholders" for the actual values. For instance, in ''%%(find: _num where _num > 2, 5,6,0)%%'',\\
3859the temp variable ''%%_num%%'' is used to mean each individual value given to the macro, in turn. It will be 5, 6 and 0, respectively.\\
3860Importantly, this will //not// alter any existing temp variable called ''%%_num%%'' - the inside of a lambda can be thought\\
3861of as a hook, so just as the inner ''%%_x%%'' in ''%%(set: _x to 1) |a>[ (set:_x to 2) ]%%'' is different from the outer ''%%_x%%'', the ''%%_num%%'' in the\\
3862lambda will not affect any other ''%%_num%%''.
3863
3864An important feature is that you can save lambdas into variables, and reuse them in your story easily. You\\
3865could, for instance, ''%%(set: $statsReadout to (_stat making _readout via _readout + "|" + _stat's name + ":" + _stat's value))%%'',\\
3866and then use $printStats with the [[harlowe:folded|(folded:)]] macro in different places, such as ''%%(folded: $statsReadout, ...(dataentries: $playerStats))%%'' for displaying the player's stats, ''%%(folded: $statsReadout, ...(dataentries: $monsterStats))%%'' for a monster's stats, etc.
3867
3868Lambdas are named after the lambda calculus, and the "lambda" keyword used in many popular programming languages.\\
3869They may seem complicated, but as long as you think of them as just a special way of writing a repeating instruction,\\
3870and understand how their macros work, you may find that they are very convenient.\\
3871<html><h2 class='def_title type_title' id=type_number><a class='heading_link' href=#type_number></a></html>Number data\\
3872<html></h2></html>
3873
3874Number data is just numbers, which you can perform basic mathematical calculations with.\\
3875You'll generally use numbers to keep track of statistics for characters, count how many times\\
3876an event has occurred, and numerous other uses.
3877
3878You can do all the basic mathematical operations you'd expect to numbers:\\
3879''%%(1 + 2) / 0.25 + (3 + 2) * 0.2%%'' evaluates to the number 13. The computer follows the normal order of\\
3880operations in mathematics: first multiplying and dividing, then adding and subtracting. You can group\\
3881subexpressions together and force them to be evaluated first with parentheses.
3882
3883If you're not familiar with some of those symbols, here's a review, along with various other operations you can perform.
3884
3885^Operator ^
3886|''%%+%%'' |
3887|''%%-%%'' |
3888|''%%*%%'' |
3889|''%%/%%'' |
3890|''%%%%%'' |
3891|''%%>%%'' |
3892|''%%>=%%'' |
3893|''%%<%%'' |
3894|''%%<=%%''~|
3895
3896You can only perform these operations (apart from ''%%is%%'') on two pieces of data if they're both numbers. Adding the\\
3897[[harlowe:string|string]] "5" to the number 2 would produce an error, and not the number 7 nor the string "52". You must\\
3898convert one side or the other using the [[harlowe:num|(num:)]] or [[harlowe:text|(text:)]] macros.\\
3899<html><h2 class='def_title type_title' id=type_string><a class='heading_link' href=#type_string></a></html>String data\\
3900<html></h2></html>
3901
3902A string is just a block of text - a bunch of text characters strung together.
3903
3904When making a story, you'll mostly work with strings that you intend to insert into\\
3905the passage source. If a string contains markup, then the markup will be processed when it's\\
3906inserted. For instance, ''%%"The ''biiiiig'' bellyblob"%%'' will print as "The <html><b></html>biiiiig<html></b></html> bellyblob".\\
3907Even macro calls inside strings will be processed: printing ''%%"The (print:2*3) bears"%%'' will print "The 6 bears".\\
3908If you wish to avoid this, simply include the verbatim markup inside the string:''%%"`It's (exactly: as planned)`"%%'' will\\
3909print "It's (exactly: as planned)".
3910
3911You can add strings together to join them: ''%%"The" + ' former ' + "Prime Minister's"%%''\\
3912pushes the strings together, and evaluates to "The former Prime Minister's". Notice\\
3913that spaces had to be added between the words in order to produce a properly spaced final string.\\
3914Also, notice that you can only add strings together. You can't subtract them, much less multiply or divide them.
3915
3916Strings are similar to [[harlowe:array|array]], in that their individual characters can be accessed: ''%%"ABC"'s 1st%%'' evaluates to "A",\\
3917''%%"Gosh"'s 2ndlast%%'' evaluates to "s", and ''%%"Exeunt"'s last%%'' evaluates to "t". They, too, have a "length":\\
3918''%%"Marathon"'s length%%'' is 8. If you don't know the exact position of a character, you can use an expression,\\
3919in brackers, after it: ''%%$string's ($pos - 3)%%''. And, you can access a substring by providing an array of positions\\
3920in place of a single position: ''%%"Dog"'s (a: 2,3)%%'' is "og".
3921
3922Also, you can use the ''%%contains%%'' and ''%%is in%%'' operators to see if a certain string is contained within another: ''%%"mother" contains "moth"%%'' is true, as is ''%%"a" is in "a"%%''. Again, like arrays, strings have special ''%%any%%'' and ''%%all%%'' data names which\\
3923can be used with ''%%contains%%'' and ''%%is in%%'' to check all their characters - ''%%all of $string is not "w"%%'' is true if the string doesn't\\
3924contain "w", and ''%%$string contains any of "aeiou"%%'' is true if the string contains those five letters.
3925
3926To summarise, here are the operations you can perform on strings.
3927
3928^Operator ^
3929|''%%+%%'' |
3930|''%%is%%'' |
3931|''%%is not%%'' |
3932|''%%contains%%''|
3933|''%%is in%%'' |
3934|''%%'s%%'' |
3935|''%%of%%'' |
3936
3937<HTML>
3938<h2 class='def_title type_title' id=type_variabletovalue><a class='heading_link' href=#type_variabletovalue></a>VariableToValue data
3939</h2>
3940</HTML>
3941This is a special value that only [[harlowe:set|(set:)]] and [[harlowe:put|(put:)]] make use of.\\
3942It's created by joining a variable and a value with the ''%%to%%'' or ''%%into%%'' keywords:\\
3943''%%$emotion to 'flustered'%%'' is an example of a VariableToValue. It exists primarily to\\
3944make [[harlowe:set|(set:)]] and [[harlowe:put|(put:)]] more readable.\\
3945<html><h1 id=section_keyword></html>Special keywords<html></h1></html>
3946
3947<HTML>
3948<h2 class='def_title keyword_title' id=keyword_it><a class='heading_link' href=#keyword_it></a>it keyword
3949</h2>
3950</HTML>
3951This keyword is a shorthand for the closest leftmost value in an expression. It lets you write\\
3952''%%(if: $candles < 2 and it > 5)%%'' instead of ''%%(if: $candles < 2 and $candles > 5)%%'', or ''%%(set: $candles to it + 3)%%''\\
3953instead of ''%%(set: $candles to $candles + 3)%%''. (You can't, however, use it in a [[harlowe:put|(put:)]] or [[harlowe:move|(move:)]] macro:\\
3954''%%(put:$red + $blue into it)%%'' is invalid.)
3955
3956Since ''%%it%%'' uses the closest leftmost value, ''%%(print: $red > 2 and it < 4 and $blue > 2 and it < 4)%%'' is the same as\\
3957''%%(print: $red > 2 and $red < 4 and $blue > 2 and $blue < 4)%%''.
3958
3959''%%it%%'' is case-insensitive: ''%%IT%%'', ''%%iT%%'' and ''%%It%%'' are all acceptable as well.
3960
3961In some situations, the ''%%it%%'' keyword will be //inserted automatically// by Harlowe when the story runs. If you write an\\
3962incomplete comparison expression where the left-hand side is missing, like ''%%(print: $red > 2 and < 4)%%'',\\
3963then, when running, the ''%%it%%'' keyword will automatically be inserted into the absent spot - producing, in this case,\\
3964''%%(print: $red > 2 and it < 4)%%''. Note that in situations where the ''%%it%%'' keyword would not have an obvious value, such as\\
3965''%%(print: < 4)%%'', an error will result nonetheless.
3966
3967If the ''%%it%%'' keyword equals a [[harlowe:datamap|datamap]], [[harlowe:string|string]], [[harlowe:array|array]], or other "collection" data type, then you can access data values\\
3968using the ''%%its%%'' variant - ''%%(print: $red is 'egg' and its length is 3)%%'' or ''%%(set:$red to its 1st)%%''. Much like the ''%%'s%%''\\
3969operator, you can use computed values with ''%%its%%'' - ''%%(if: $red's length is 3 and its $position is $value)%%'' will work as\\
3970expected.\\
3971<html><h2 class='def_title keyword_title' id=keyword_time><a class='heading_link' href=#keyword_time></a></html>time keyword\\
3972<html></h2></html>
3973
3974This keyword evaluates to the [[harlowe:number|number]] of milliseconds passed since the passage\\
3975was displayed. Its main purpose is to be used alongside [[harlowe:changer|changer]]\\
3976such as [[harlowe:live|(live:)]] or [[harlowe:link|(link:)]]. ''%%(link:"Click")[(if: time > 5s)[...]]%%'', for instance,\\
3977can be used to determine if 5 seconds have passed since this passage was displayed,\\
3978and thus whether the player waited 5 seconds before clicking the link.
3979
3980When the passage is initially being rendered, ''%%time%%'' will be 0.
3981
3982''%%time%%'' used in [[harlowe:display|(display:)]] macros will still produce the time of the host passage, not the\\
3983contained passage. So, you can't use it to determine how long the [[harlowe:display|(display:)]]ed passage\\
3984has been present in the host passage.\\
3985<html><h1 id=section_passagetag></html>Special passage tags<html></h1></html>
3986
3987<HTML>
3988<h2 class='def_title passagetag_title' id=passagetag_header><a class='heading_link' href=#passagetag_header></a>header tag
3989</h2>
3990</HTML>
3991It is often very useful to want to reuse a certain set of macro calls in every passage,\\
3992or to reuse an opening block of text. You can do this by giving the passage the special\\
3993tag ''%%header%%'', or ''%%footer%%''. All passages with these tags will have their source text included at the top\\
3994(or, for ''%%footer%%'', the bottom) of every passage in the story, as if by an invisible [[harlowe:display|(display:)]] macro call.
3995
3996If many passages have the ''%%header%%'' tag, they will all be displayed, ordered by their passage\\
3997name, sorted alphabetically, and by case (capitalised names appearing before lowercase names).\\
3998<html><h2 class='def_title passagetag_title' id=passagetag_footer><a class='heading_link' href=#passagetag_footer></a></html>footer tag\\
3999<html></h2></html>
4000
4001This special tag is identical to the ''%%header%%'' tag, except that it places the passage\\
4002at the bottom of all visited passages, instead of the top.\\
4003<html><h2 class='def_title passagetag_title' id=passagetag_startup><a class='heading_link' href=#passagetag_startup></a></html>startup tag\\
4004<html></h2></html>
4005
4006This special tag is similar to ''%%header%%'', but it will only cause the passage\\
4007to be included in the very first passage in the game.
4008
4009This is intended to simplify the story testing process: if you have setup\\
4010code which creates variables used throughout the entire story, you should put it in\\
4011a passage with this tag, instead of the starting passage. This allows you to test your\\
4012story from any passage, and, furthermore, easily change the starting passage if you wish.
4013
4014All passages tagged with ''%%startup%%'' will run, in alphabetical order\\
4015by their passage name, before the passages tagged ''%%header%%'' will run.\\
4016<html><h2 class='def_title passagetag_title' id=passagetag_debug-header><a class='heading_link' href=#passagetag_debug-header></a></html>debug-header tag\\
4017<html></h2></html>
4018
4019This special tag is similar to the ''%%header%%'' tag, but only causes the passage\\
4020to be included if you're running the story in debug mode.
4021
4022This has a variety of uses: you can put special debug display code in this\\
4023passage, which can show the status of certain variables or provide links\\
4024to change the game state as you see fit, and have that code\\
4025be present in every passage in the story, but only during testing.
4026
4027All passages tagged with ''%%debug-header%%'' will run before the passages tagged ''%%header%%'' will run,\\
4028ordered by their passage name, sorted alphabetically, and by case (capitalised names appearing\\
4029before lowercase names).\\
4030<html><h2 class='def_title passagetag_title' id=passagetag_debug-footer><a class='heading_link' href=#passagetag_debug-footer></a></html>debug-footer tag\\
4031<html></h2></html>
4032
4033This special tag is identical to the ''%%debug-header%%'' tag, except that it places the passage\\
4034at the bottom of all visited passages, instead of the top.
4035
4036All passages tagged with ''%%debug-footer%%'' will run, in alphabetical order\\
4037by their passage name, after the passages tagged ''%%footer%%'' have been run.\\
4038<html><h2 class='def_title passagetag_title' id=passagetag_debug-startup><a class='heading_link' href=#passagetag_debug-startup></a></html>debug-startup tag\\
4039<html></h2></html>
4040
4041This special tag is similar to the ''%%startup%%'' tag, but only causes the passage\\
4042to be included if you're running the story in debug mode.
4043
4044This has a variety of uses: you can put special debugging code into this\\
4045passage, or set up a late game state to test, and have that code run\\
4046whenever you use debug mode, no matter which passage you choose to test.
4047
4048All passages tagged with ''%%debug-startup%%'' will run, in alphabetical order\\
4049by their passage name, after the passages tagged ''%%startup%%'' will run.\\
4050<html><h1 id=section_changes></html>Change log<html></h1></html>
4051
4052<HTML>
4053<h2 class='def_title changes_title' id=changes_2.0.1-changes><a class='heading_link' href=#changes_2.0.1-changes></a>2.0.1 changes</h2>
4054</HTML>
4055=== Bugfixes ===
4056
4057 * Fixed a bug where ''%%(enchant:)%%'' applied to ?Page couldn't override CSS properties for ''%%<tw-story>%%'' (including the default background colour and colour).
4058 * Fixed a Passage Editor display bug where the left margin obscured the first letter of lines.
4059
4060<HTML>
4061<h2 class='def_title changes_title' id=changes_2.0.0-changes><a class='heading_link' href=#changes_2.0.0-changes></a>2.0.0 changes</h2>
4062</HTML>
4063=== Bugfixes ===
4064
4065 * Fixed a bug where comparing a value with an error (such as ''%%2 is (3 + 'X')%%'') would suppress the error.
4066 * Fixed a bug where subtracting non-subtractable values (such as booleans) wouldn't produce an error, instead implicitly converting the values to numbers, and potentially producing the Javascript value ''%%NaN%%''.
4067 * Fixed a bug where subtracting arrays and datasets wouldn't correctly compare contained data structures - for instance, ''%%(a:(a:1)) - (a:(a:1))%%'' wouldn't work correctly.
4068 * Fixed a bug where the ''%%(dataset:)%%'' macro, and adding datasets, wouldn't correctly compare data structures - for instance, ''%%(dataset: (a:),(a:))%%'' would contain both identical arrays, as would ''%%(dataset: (a:)) + (dataset: (a:))%%''.
4069 * Additionally fixed a bug where data structures were storied in datasets by reference, allowing two variables to reference (and remotely alter) the same data.
4070 * Fixed a bug where using ''%%(move:)%%'' to move a subarray or substring (such as ''%%(move: $a's (a:2,3) to $b))%%'' wouldn't work.
4071 * Fixed a bug where using ''%%(set:)%%'' to set a substring, when the given array of positions contained "length" (such as ''%%(set: $a's (a:1,"length")) to "foo")%%''), wouldn't produce an error.
4072 * Fixed a bug where the ''%%(count:)%%'' macro would give the wrong result when the data to count (the second value) was an empty string.
4073 * Now, a ''%%(print:)%%'' command that contains a command will only execute the contained command if itself is actually displayed in the passage - the code ''%%(set: $x to (print:(goto:'X')))%%'' would formerly perform the (goto:) immediately, even though the (print:) was never displayed.
4074 * Now, datasets contained in other datasets should be printed correctly, listing their contents.
4075 * ''%%(alert:)%%'', ''%%(open-url:)%%'', ''%%(reload:)%%'' and ''%%(goto-url:)%%'' now correctly return command values rather than the non-Harlowe value ''%%undefined%%'' (or, for ''%%(open-url:)%%'' a Javascript Window object). This means that ''%%(alert:)%%'''s' time of execution changes relative to ''%%(prompt:)%%'' and ''%%(confirm:)%%'' - ''%%(set: $x to (prompt:"X"))%%'' will display a JS dialog immediately, but ''%%(set: $x to (alert:"X"))%%'' will not - although this is conceptually reasonable given that ''%%(prompt:)%%'' and ''%%(confirm:)%%'' are essentially "input" commands obtaining data from the player, and ''%%(alert:)%%'' is strictly an "output" command.
4076 * Now, line breaks between raw HTML ''%%<table>%%'', ''%%<tr>%%'', ''%%<tbody>%%'', ''%%<thead>%%'' and ''%%<tfoot>%%'' elements are no longer converted into erroneous ''%%<br>%%'' elements, which are moved to just above the table. Thus, one can write or paste multi-line ''%%<table>%%'' markup with fewer problems arising.
4077 * Fixed bugs where various macros (''%%(subarray:)%%'', ''%%(shuffled:)%%'', ''%%(rotated:)%%'', ''%%(datavalues:)%%'', ''%%(datamap:)%%'', ''%%(dataset:)%%'') would end up passing nested data structures by reference (which shouldn't be allowed in Harlowe code). For instance, if you did ''%%(set:$b to (rotated: 1, 0, $a))%%'', where $a is an array, then modifying values inside $b's 1st would also modify $a.
4078 * Fixed a bug where setting custom values in a datamap returned by ''%%(passage:)%%'' would save the data in all subsequent identical ''%%(passage:)%%'' datamaps. (For instance, ''%%(set: (passage:'A')'s foo to 1))%%'' would cause all future datamaps produced by ''%%(passage:'A')%%'' to have a "foo" data name containing 1.) The ''%%(passage:)%%'' macro, or any other built-in macros' return values, are NOT intended as data storage (and, furthermore, are not saved by ''%%(savegame:)%%'' etc).
4079 * Fixed the bug where a ''%%(goto:)%%'' command inside a hook would prevent subsequent commands inside the hook from running, but subsequent commands outside it would still continue - for instance, ''%%(if:true)[(go-to:'flunk')](set:$a to 2)%%'' would still cause the ''%%(set:)%%'' command to run.
4080 * Fixed the bug where ''%%(current-time:)%%'' wouldn't pad the minutes value with a leading 0 when necessary.
4081 * Fixed the bug where referring to a variable multiple times within a single ''%%(set:)%%'' command, like ''%%(set: $a to 1, $b to $a)%%'', wouldn't work as expected.
4082 * The "pulse" transition (provided by ''%%(transition:)%%'') now gives its attached hook the ''%%display:inline-block%%'' CSS property for the duration of the transition. This fixes a bug where block HTML elements inside such hooks would interfere with the transition animation.
4083 * Revision changers (''%%(replace:)%%'', ''%%(append:)%%'', ''%%(prepend:)%%'') that use hook names can now work when they're stored in a variable and used in a different passage. So, running ''%%(set: $x to (replace:?1))%%'' in one passage and ''%%$x[Hey]%%'' in the next will work as expected.
4084 * Differing revision changers can be added together - ''%%(append: ?name) + (prepend: ?title)%%'', for instance, no longer produces a changer which only prepends to both hooks.
4085 * Fixed various mistakes or vaguaries in numerous error messages.
4086
4087=== Alterations ===
4088
4089== Removed behaviour ==
4090
4091 * In order to simplify the purpose of hook names such as ''%%?room%%'', you can no longer convert them to strings, ''%%(set:)%%'' their value, ''%%(set:)%%'' another variable to them, or use them bare in passage text. The ''%%(replace:)%%'' macro, among others, should be used to achieve most of these effects.
4092 * Using ''%%contains%%'' and ''%%is in%%'' on numbers and booleans (such as ''%%12 contains 12%%'') will now produce an error. Formerly, doing so would test whether the number equalled the other value. (The rationale for this was that, since the statement ''%%"a" contains "a"%%'' is the same as ''%%"a" is "a"%%'', then so should it be for numbers and booleans, which arguably "contain" only themselves. However, this seems to be masking certain kinds of errors when incorrect or uninitialised variables or properties were used).
4093 * Now, various macros (''%%(range:)%%'', ''%%(subarray:)%%'', ''%%(substring:)%%'', ''%%(rotated:)%%'' etc.) which require integers (positive or negative whole numbers) will produce errors if they are given fractional numbers.
4094 * It is now an error to alter data structures that aren't in variables - such as ''%%(set: (a:)'s 1st to 1)%%'' or ''%%(set: (passage:)'s name to "X")%%'' - because doing so accomplishes nothing.
4095 * Attaching invalid values to hooks, such as ''%%(either:"String")[text]%%'', ''%%(a:2,3,4)[text]%%'' or ''%%(set: $x to 1) $x[text]%%'', will now result in an error instead of printing both the value and the hook's contents.
4096 * Writing a URL in brackets, like ''%%(http://...)%%'', will no longer be considered an invalid macro call. (To be precise, neither will any macro whose ''%%:%%'' is immediately followed by a ''%%/%%'', so other protocol URLs are also capable of being written.)
4097
4098== Markup ==
4099
4100 * Now, if you write ''%%[text]%%'' by itself, it will be treated as a hook, albeit with no name (it cannot be referenced like ''%%?this%%'') and no attached changer commands. This, I believe, simplfies what square brackets "mean" in passage prose. Incidentally, temporary variables (see below) can be ''%%(set:)%%'' inside nameless unattached hooks without leaking out, so they do have some semantic meaning.
4101 * Now, you can attach changer macros to nametagged hooks: ''%%(if: true) |moths>[Several moths!]%%'', for instance, is now valid. However, as with all hooks, trying to attach plain data, such as a number or an array, will cause an error.
4102 * Hook-attached macros may now have whitespace and line breaks between them and their hooks. This means that ''%%(if: $x) [text]%%'' and such are now syntactically acceptable - the whitespace is removed, and the macro is treated as if directly attached. (This means that, if after a macro call you have plain passage text that resembles a hook, you'll have to use the verbatim markup to keep it from being interpreted as such.)
4103
4104== Code ==
4105
4106 * Now, when given expressions such as ''%%$a < 4 and 5%%'', where ''%%and%%'' or ''%%or%%'' joins a non-boolean value with a comparison operation (''%%>%%'', ''%%<=%%'', ''%%is%%'', ''%%contains%%'', etc.), Harlowe will now infer that you meant to write ''%%$a < 4 and it < 5%%'', and treat the expression as that, instead of producing an error. This also applies to expressions like ''%%$a and $b < 5%%'', which is inferred to be ''%%5 > $a and it > $b%%''. This is a somewhat risky addition, but removes a common pitfall for new authors in writing expressions. (Observe that the above change does not apply when ''%%and%%'' or ''%%or%%'' joins a boolean - expressions like ''%%$a < 4 and $visitedBasement%%'', where the latter variable contains a boolean, will continue to work as usual.)
4107 * However, this is forbidden with ''%%is not%%'', because the meaning of expressions like ''%%$a is not 4 and 5%%'', or ''%%$a is not 4 or 5%%'' is ambiguous in English, and thus error-prone. So, you'll have to write ''%%$a is not 4 and is not 5%%'' as usual.
4108 * Now, when working with non-positive numbers as computed indexes (such as ''%%$array's (-1)%%''), Harlowe no longer uses ''%%0%%'' for ''%%last%%'', ''%%-1%%'' for ''%%2ndlast%%'', and so forth - instead, ''%%-1%%'' means ''%%last%%'', ''%%-2%%'' means ''%%2ndlast%%'', and using ''%%0%%'' produces an error. (So, ''%%"Red"'s (-1)%%'' produces "d", not "e".)
4109 * Now, you can optionally put 'is' at the start of inequality operators - you can write ''%%$a is < 3%%'' as a more readable alternative to ''%%$a < 3%%''. Also, ''%%$a is not > 3%%'' can be written as well, which negates the operator (making it behave like ''%%$a is <= 3%%'').
4110 * Now, trying to use the following words as operators will result in an error message telling you what the correct operator is: ''%%=>%%'', ''%%=<%%'', ''%%gte%%'', ''%%lte%%'', ''%%gt%%'', ''%%lt%%'', ''%%eq%%'', ''%%isnot%%'', ''%%neq%%'', ''%%are%%'', ''%%x%%''.
4111 * Passage links can now be used as values inside macros - ''%%(set: $x to [[Go down->Cellar]])%%'' is now valid. You may recall that passage links are treated as equivalent to ''%%(link-goto:)%%'' macro calls. As such, ''%%(set: $x to [[Go down->Cellar]])%%'' is treated as identical to ''%%(set: $x to (link-goto:"Go down","Cellar"))%%''.
4112 * Revision macros such as ''%%(replace:)%%'', ''%%(append:)%%'' and ''%%(prepend:)%%'' can now accept multiple values: ''%%(replace:?ape, ?hen)%%'', for instance, can affect both hooks equally, and ''%%(replace:'red', 'green')%%'' can affect occurrences of either string.
4113 * Now, adding two ''%%(append:)%%'' or ''%%(prepend:)%%'' macros which target the same hook, such as ''%%(append:?elf) + (append:?elf)%%'', no longer creates a changer that appends/prepends to that same hook twice.
4114 * Hook names, even added together, can now be recognised as the same by the ''%%is%%'' operator if they target the same hooks (including sub-elements).
4115 * The ''%%(move:)%%'' macro now accepts multiple ''%%into%%'' values, like ''%%(put:)%%''.
4116 * The ''%%(count:)%%'' macro now accepts multiple data values, and will count the total occurences of every value. For instance, ''%%(count: "AMAZE", "A", "Z")%%'' produces 3.
4117 * Now, ''%%debug-header%%'' tagged passages are run after ''%%header%%'' tagged passages in debug mode, for consistency with the order of ''%%debug-startup%%'' and ''%%startup%%''.
4118 * Link macros like ''%%(link-replace:)%%'' will now produce an error when given an empty string.
4119
4120== HTML/CSS ==
4121
4122 * The default Harlowe colour scheme is now white text on black, in keeping with SugarCube and Sugarcane, rather than black text on white. The light colour scheme can be reinstated by putting ''%%(enchant: ?page, (text-colour:black)+(background:white))%%'' in a passage with the ''%%header%%'' tag.
4123 * The ''%%<tw-story>%%'' element is now kept inside whatever element originally enclosed it, instead of being moved to inside ''%%<html>%%''.
4124 * Now, the default CSS applies the default Harlowe ''%%font%%'' (Georgia) to the ''%%<tw-story>%%'' element instead of ''%%html%%'' - so, to override it, write CSS ''%%font%%'' properties for ''%%tw-story%%'' (which is what most custom CSS should be altering now) instead of ''%%html%%'' or ''%%body%%''.
4125 * Fixed a bug where the "Story stylesheet" ''%%<style>%%'' element was attached between ''%%<head>%%'' and ''%%<body>%%''. This should have had no obvious effects in any browser, but was untidy anyway.
4126 * Altered the CSS of ''%%<tw-story>%%'' to use vertical padding instead of vertical margins, and increased the line-height slightly.
4127 * Altered the CSS of ''%%<h1>%%'', ''%%<h2>%%'', ''%%<h3>%%'', ''%%<h4>%%'', ''%%<h5>%%'' and ''%%<h6>%%'' elements to have a slightly lower margin-top.
4128 * Now, ''%%<tw-passage>%%'' elements (that is, passages' HTML elements) have a ''%%tags%%'' attribute containing all of the passage's tags in a space-separated list. This allows such elements to be styled using author CSS, or selected using author Javascript, in a manner similar to Twine 1.4 (but using the ''%%[tags~= ]%%'' selector instead of ''%%[data-tags~= ]%%'').
4129 * Removed the CSS directives that reduce the font size based on the player's device width, because this functionality seems to be non-obvious to users, and can interfere with custom CSS in an unpleasant way.
4130 * Now, hooks and expressions which contain nothing (due to, for instance, having a false ''%%(if:)%%'' attached) will now have ''%%display:none%%'', so that styling specific to their borders, etc. won't still be visible.
4131
4132=== Additions ===
4133
4134== Markup ==
4135
4136 * Added column markup, which is, like aligner markup, a special single-line token indicating that the subsequent text should be separated into columns. They consist of a number of ''%%|%%'' marks, indicating the size of the column relative to the other columns, and a number of ''%%=%%'' marks surrounding it, indicating the size of the column's margins in CSS "em" units (which are about the width of a capital M). Separate each column's text with tokens like ''%%|===%%'' and ''%%==||%%'', and end them with a final ''%%|==|%%'' token to return to normal page layout.
4137 * Now, it's possible to attach multiple changers to a single hook by joining them with ''%%+%%'', even outside of a macro - ''%%(text-style:'bold')+(align:'==>')+$robotFont[Text]%%'' will apply ''%%(text-style:'bold')%%'', ''%%(align:'==>')%%'' and the changer in the variable $robotFont, as if they had been added together in a single variable. Again, you can put whitespace between them – ''%%(text-style:'bold') + (align:'==>') + $robotFont [Text]%%'' is equally valid, and causes the whitespace between each changer and the hook itself to be discarded.
4138 * Now, you can make hooks which are hidden when the passage is initially displayed, to be revealed when a macro (see below) is run. Simply replace the ''%%<%%'' and ''%%>%%'' symbol with a ''%%(%%'' or ''%%)%%''. For example: ''%%|h)[This hook is hidden]%%''. (You can think of this as being visually similar to comic speech balloons vs. thought balloons.) This is an alternative to the revision macros, and can be used in situations where the readability of the passage prose is improved by having hidden hooks alongside visible text, rather than separate ''%%(replace:)%%'' hooks. (Of course, the revision macros are still useful in a variety of other situations, including ''%%header%%'' passages.)
4139
4140== Code ==
4141
4142 * Arrays, strings and datasets now have special data names, ''%%any%%'', and ''%%all%%'', which can be used with comparison operators like ''%%contains%%'', ''%%is%%'' and ''%%<=%%'' to compare every value inside them. For instance, you can now write ''%%(a:1,2,3) contains all of (a:2,3)%%'', or ''%%any of (a:3,2) <= 2%%'', or ''%%"Fox" contains any of "aeiou"%%'' (all of which are true). You can't use them anywhere else, though - ''%%(set: all of $a to true)%%'' is an error (and wouldn't be too useful anyway).
4143 * Now, certain hard-coded hook names will also select elements of the HTML page, letting you style the page using enchantment macros. ''%%?page%%'' selects the page element (to be precise, the ''%%<tw-story>%%''), ''%%?passage%%'' selects the passage element (to be precise, the ''%%<tw-passage>%%''), ''%%?sidebar%%'' selects the passage's sidebar containing undo/redo icons (''%%<tw-sidebar>%%''), and ''%%?link%%'' selects any links in the passage. (Note that if you use these names for yourself, such as ''%%|passage>[]%%'', then they will, of course, be included in the selection.)
4144 * Added temporary variables, a special kind of variable that only exists inside the passage or hook in which they're ''%%(set:)%%''. Outside of the passage or hook, they disappear. Simply use ''%%_%%'' instead of ''%%$%%'' as the sigil for variables - write ''%%(set: _a to 2)%%'', ''%%(if: _a > 1)%%'', etc. Their main purpose is to allow you to make "reusable" Twine code - code which can be pasted into any story, without accidentally overwriting any variables that the story has used. (For instance, suppose you had some code which uses the variable ''%%$a%%'' for some quick computation, but you pasted it into a story that already used ''%%$a%%'' for something else in another passage. If you use a temporary variable ''%%_a%%'' instead, this problem won't occur.)
4145 * Also note that temp variables that are ''%%(set:)%%'' inside hooks won't affect same-named temp variables outside them: ''%%(set: _a to 1) |hook>[(set: _a to 2)]%%'' will make ''%%_a%%'' be 2 inside the hook, but remain as 1 outside of it.
4146 * Lambdas are a new data type - they are, essentially, user-created functions. You can just think of them as "data converters" - reusable instructions that convert values into different values, filter them, or join multiple values together. They use temporary variables (which only exist inside the lambda) to hold values while computing them, and this is shown in their syntax. An example is ''%%_a where _a > 2%%'', which filters out data that's smaller than 2, or ''%%_name via "a " + _name%%'', which converts values by adding 1 to them. Various new macros use these to easily apply the same conversion to sequences of data.
4147 * Colour values now have read-only data names: ''%%r%%'', ''%%g%%'' and ''%%b%%'' produce the red, green and blue components of the colour (from 0 to 255), and ''%%h%%'', ''%%s%%'' and ''%%l%%'' produce, in order, the hue (in degrees), and the saturation and lightness percentages (from 0 to 1).
4148 * You can now access sub-elements in hook names, as if they were an array: ''%%(click: ?red's 1st)%%'' will only affect the first such named hook in the passage, for instance, and you can also specify an array of positions, like ''%%?red's (a:1,3,5)%%''. Unlike arrays, though, you can't access their ''%%length%%'', nor can you spread them with ''%%...%%''.
4149 * You can now add hook names together to affect both at the same time: ''%%(click: ?red + ?blue's 1st)%%'' will affect all hooks tagged ''%%<red|%%'', as well as the first hook tagged ''%%<blue|%%''.
4150
4151== Macros ==
4152
4153 * Added ''%%(undo:)%%'', a command similar to ''%%(go-to:)%%'' which performs the same function as the undo button in the default sidebar. Use it as an alternative to ''%%(go-to: (history:)'s last)%%'' which forgets the current turn as well as going back.
4154 * Also added a link shorthand of the above, ''%%(link-undo:)%%'', which is used similarly to ''%%(link-goto:)%%''.
4155 * Added ''%%(for:)%%'', a command that repeats the attached hook, using a lambda to set a temporary variable to a different value on each repeat. It uses "where" lambdas, and accepts the "each" shorthand for ''%%where true%%'', which accepts every value. ''%%(for: each _item, ...$array) [You have the _item]%%'' prints "You have the " and the item, for each item in ''%%$array%%''.
4156 * Added ''%%(find:)%%'', which uses a lambda to filter a sequence of values, and place the results in an array. For instance, ''%%(find: _item where _item's 1st is "A", "Arrow", "Shield", "Axe", "Wand")%%'' produces the array ''%%(a: "Arrow", "Axe")%%''. (This macro is similar to Javascript's ''%%filter()%%'' array method.)
4157 * Added ''%%(altered:)%%'', which takes a lambda as its first value, and any number of other values, and uses the lambda to convert the values, placing the results in an array. For instance, ''%%(altered: _material via _material + " Sword", "Iron", "Wood", "Bronze", "Plastic")%%'' will create an array ''%%(a:"Iron Sword", "Wood Sword", "Bronze Sword", "Plastic Sword")%%''. (This macro is similar to Javascript's ''%%map()%%'' array method.)
4158 * Added ''%%(all-pass:)%%'', ''%%(some-pass:)%%'' and ''%%(none-pass:)%%'', which check if the given values match the lambda, and return ''%%true%%'' or ''%%false%%''. ''%%(all-pass: _a where _a > 2, 1, 3, 5)%%'' produces ''%%false%%'', ''%%(some-pass: _a where _a > 2, 1, 3, 5)%%'' produces ''%%true%%'', and ''%%(none-pass: _a where _a > 2, 1, 3, 5)%%'' produces ''%%false%%''.
4159 * Added ''%%(folded:)%%'', which is used to combine many values into one (a "total"), using a lambda that has a ''%%making%%'' clause. ''%%(folded: _a making _total via _total + "." + _a, "E", "a", "s", "y")%%'' will first set ''%%_total%%'' to "E", then progressively add ".a", ".s", and ".y" to it, thus producing the resulting string, "E.a.s.y".
4160 * Added ''%%(show:)%%'', a command to show a hidden named hook (see above). ''%%(show: ?secret)%%'' will show all hidden hooks named ''%%|secret)%%''. This can also be used to reveal named hooks hidden with ''%%(if:)%%'', ''%%(else-if:)%%'', ''%%(else:)%%'' and ''%%(unless:)%%''.
4161 * Added ''%%(hidden:)%%'', which is equivalent to ''%%(if:false)%%'', and can be used to produce a changer to hide its attached hook.
4162 * Added the aliases ''%%(dm:)%%'' and ''%%(ds:)%%'' for ''%%(datamap:)%%'' and ''%%(dataset:)%%'', respectively.
4163 * Added ''%%(lowercase:)%%'' and ''%%(uppercase:)%%'', which take a string and convert it to all-lowercase or all-uppercase, as well as ''%%(lowerfirst:)%%'' and ''%%(upperfirst:)%%'', which only convert the first non-whitespace character in the string and leave the rest untouched.
4164 * Added ''%%(words:)%%'', which takes a string and produces an array of the words (that is, the sequences of non-whitespace characters) in it. For instance, ''%%(words: "2 big one's")%%'' produces ''%%(a: "2", "big", "one's")%%''.
4165 * Added ''%%(repeated:)%%'', which creates an array containing the passed values repeated a given number of times. ''%%(repeated: 3, 1,2,0)%%'' produces ''%%(a: 1,2,0,1,2,0,1,2,0)%%''.
4166 * Added ''%%(interlaced:)%%'', which interweaves the values of passed-in arrays. ''%%(interlaced: (a: 'A','B','C','D'),(a: 1,2,3))%%'' is the same as ''%%(a: 'A',1,'B',2,'C',3)%%''. (For functional programmers, this is just a flat zip.) This can be useful alongside the ''%%(datamap:)%%'' macro.
4167 * Added ''%%(rgb:)%%'', ''%%(rgba:)%%'', ''%%(hsl:)%%'' and ''%%(hsla:)%%'', which produce colour values, similar to the CSS colour functions. ''%%(rgb:252,180,0)%%'' produces the colour #fcb400, and ''%%(hsl:150,0.2,0.6)%%'' produces the colour #84ad99.
4168 * Added ''%%(dataentries:)%%'', which complements ''%%(datanames:)%%'' and ''%%(datavalues:)%%'' by producing, from a datamap, an array of the datamap's name-value pairs. Each pair is a datamap with "name" and "value" data, which can be examined using the lambda macros.
4169 * Added ''%%(hover-style:)%%'', which, when given a style-altering changer, like ''%%(hover-style:(text-color:green))%%'', makes its style only apply when the hook or expression is hovered over with the mouse pointer, and removed when hovering off.
4170 * Now, you can specify ''%%"none"%%'' as a ''%%(text-style:)%%'' and produce a changer which, when added to other ''%%(text-style:)%%'' combined changers, removes their styles.
4171
4172<HTML>
4173<h1 id=section_appendix>Appendix</h1>
4174<h2 class='def_title appendix_title' id=appendix_syntax-comparison-with-sugarcube-1><a class='heading_link' href=#appendix_syntax-comparison-with-sugarcube-1></a>Syntax comparison with SugarCube 1</h2>
4175</HTML>
4176[[http://www.motoslave.net/sugarcube/1/|SugarCube 1]], one of the other story formats included in Twine 2, uses different markup and syntax to Harlowe.\\
4177Additionally, its offered features and design philosophy also differ. This table offers a //very rough guide// to some of the major differences.\\
4178(Note that a feature which is "not offered" may still be possible to implement by the addition of story CSS or JavaScript, or a combination of\\
4179other extant features.)
4180
4181^Markup or syntax feature ^
4182|**Special passages** |
4183|Startup passages |
4184|Pre-render passages |
4185|Post-render passages |
4186|Story sidebar modification |
4187|Debug-only passages |
4188|**Styling markup** |
4189|Aligner markup |
4190|Strikethrough markup |
4191|Underline markup |
4192|Subscript markup |
4193|Highlight markup |
4194|Verbatim markup |
4195|Other styles |
4196|Coloured text |
4197|Custom text styles |
4198|Adding and saving styles |
4199|**White-space control** |
4200|Escaped line break |
4201|Collapsing [[harlowe:whitespace |
4202|"No <br>" macro |
4203|"Silently" macro |
4204|**Image and link markup** |
4205|Images |
4206|Image links |
4207|Setter links |
4208|Image setter links |
4209|**Multimedia macros** |
4210|Audio macros |
4211|**Operators** |
4212|"Loosely equals" operators |
4213|"Strictly does not equal" operator |
4214|Inequality operators |
4215|"Is variable defined" operator |
4216|"Contains" operation for arrays |
4217|"Contains all" operation for arrays |
4218|"Contains any" operation for arrays |
4219|"Count" operation |
4220|Increment/decrement |
4221|Spread operator |
4222|**Data model** |
4223|Passing |
4224|Type coercion |
4225|**Element access** |
4226|Array/string element access |
4227|Last element access |
4228|Array/string slicing |
4229|**Randomness** |
4230|"Either" macro/function |
4231|Random whole numbers |
4232|Random floating-point numbers |
4233|Random array elements |
4234|PRNG seeding |
4235|"Shuffled" macro/function |
4236|**Game state** |
4237|"Time" identifier/function |
4238|Number of turns elapsed |
4239|Current passage's name |
4240|Previous passage's name |
4241|Current passage's tags |
4242|Times a passage is visited |
4243|Times a tag is visited |
4244|**Basic macros** |
4245|"Print" macro |
4246|"Set" macro |
4247|"Unset" macro |
4248|"Remember" macro |
4249|"Run" macro |
4250|Inline Javascript |
4251|"Display" macro |
4252|"If" macro |
4253|"For" macro |
4254|**Data value macros** |
4255|Converting to string |
4256|Converting to number |
4257|Creating arrays |
4258|Maths macros |
4259|**Navigation macros** |
4260|"Choice" macro |
4261|"Actions" macro |
4262|"Go to" macro |
4263|"Return" macro |
4264|"Undo" macro |
4265|**UI element macros** |
4266|"Click/Link" macro |
4267|"Mouseover" macro |
4268|"Mouseout" macro |
4269|"Checkbox" macro |
4270|"Radio Button" macro |
4271|"Text Area" macro |
4272|"Textbox" macro |
4273|DOM class macros |
4274|**Revision macros** |
4275|"Append" macro |
4276|"Prepend" macro |
4277|"Replace" macro |
4278|Append/prepend/replace arbitrary text|
4279|**Structured programming** |
4280|Custom macros |
4281|**Game saving** |
4282|Saving and loading macros/functions |
4283|Built-in save menu |