User Tools

Site Tools


Sidebar

Passage markup

basics

coding

extra

list

section

whitespace

Macros

basics

colour

data structure

date and time

game state

live

maths

number

revision

saving

showing and hiding

string

styling

url

deprecated

Types of data

Special keywords

Special passage tags

harlowe:replace

(replace: HookName or String) → Changer

Creates a command which you can attach to a hook, and replace target destinations with the hook's contents. The targets are either text strings within the current passage, or hook references.

Example usage:

This example changes the words “categorical catastrophe” to “dogegorical dogastrophe”

A categorical catastrophe!
(replace: "cat")[**dog**]

This example changes the |face> and |heart> hooks to read “smile”:

A |heart>[song] in your heart, a |face>[song] on your face.
(replace: ?face, ?heart)[smile]

Rationale:

A common way to make your stories feel dynamic is to cause their text to modify itself before the player's eyes, in response to actions they perform. You can check for these actions using macros such as (link:), (click:) or (live:), and you can make these changes using macros such as (replace:).

Using (replace:) is only one way of providing this dynamism, however - the (show:) macro also offers similar functionality. See that macro's article for an explanation of when you might prefer to use it over (replace:), and vice-versa.

Details:

(replace:) lets you specify a target, and a block of text to replace the target with. The attached hook will not be rendered normally - thus, you can essentially place (replace:) commands anywhere in the passage text without interfering much with the passage's visible text.

If the given target is a string, then every instance of the string in the current passage is replaced with a copy of the hook's contents. If the given target is a hook reference, then only named hooks with the same name as the reference will be replaced with the hook's contents. Use named hooks when you want only specific places in the passage text to change.

If the target doesn't match any part of the passage, nothing will happen. This is to allow you to place (replace:) commands in header tagged passages, if you want them to conditionally affect certain named hooks throughout the entire game, without them interfering with other passages.

See also:

harlowe/replace.txt · Last modified: 2017/06/18 22:49 by l