**(replace: // ...[[harlowe:HookName|HookName]] or [[harlowe:String|String]]//) -> //[[harlowe:Changer|Changer]]//**

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

=== Example usage: ===

This example changes the words "categorical catastrophe" to "**dog**egorical **dog**astrophe"

<code>
A categorical catastrophe!
(replace: "cat")[**dog**]
</code>
This example changes the ''%%|face>%%'' and ''%%|heart>%%'' hooks to read "smile":

<code>
A |heart>[song] in your heart, a |face>[song] on your face.
(replace: ?face, ?heart)[smile]
</code>
=== 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 [[harlowe:link|(link:)]], [[harlowe:click|(click:)]] or [[harlowe:live|(live:)]], and you can make these changes using macros
such as (replace:).

Using (replace:) is only one way of providing this dynamism, however - the [[harlowe:show|(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.

(replace:) (and its variations) cannot affects hooks or text that haven't been printed yet - if the (replace:) runs at the same time that the passage is appearing (as in, it isn't inside a hook that's delayed [[harlowe:live|(live:)]], [[harlowe:link|(link:)]], [[harlowe:show|(show:)]] or similar macros), and a hook or line of text appears after it in the passage, the macro won't replace its contents even if it's a valid target. For example: ''%%(replace: "cool")[hot] cool water%%'' won't work because the (replace:) runs immediately, but ''%%cool water (replace: "cool")[hot]%%'' and ''%%(event: when time > 5)[(replace: "cool")[hot]] cool water%%'' will.

As a result of the above, putting these in ''%%header%%'' tagged passages instead of ''%%footer%%'' tagged passages won't do much good, as they are printed before the rest of the passage.

=== See also: ===

[[harlowe:append|(append:)]], [[harlowe:prepend|(prepend:)]], [[harlowe:show|(show:)]]