docs reference

[[clear-tokens]]

Clear_tokens

By Goblin Docs ~ 11 min read

clear_tokens removes every registered token from one token namespace.

Overview

Use clear_tokens when a whole namespace should be emptied:

register_token("THEME", "ACCENT", "purple")
register_token("THEME", "BACKGROUND", "black")
register_token("SITE", "TITLE", "Cave Journal")

clear_tokens("THEME")

:say(list_tokens("THEME"))  /// {}
:say(list_tokens("SITE"))   /// {TITLE: Cave Journal}

register_token("THEME", "ACCENT", "purple")
register_token("THEME", "BACKGROUND", "black")
register_token("SITE", "TITLE", "Cave Journal")

clear_tokens("THEME")

:say(list_tokens("THEME"))  /// {}
:say(list_tokens("SITE"))   /// {TITLE: Cave Journal}

Only the THEME namespace is cleared. Other namespaces remain registered.

Call Styles

clear_tokens can be called as a free function:

clear_tokens("THEME")

clear_tokens("THEME")

It also supports method style, with the namespace as the receiver:

"THEME".clear_tokens()

"THEME".clear_tokens()

Both forms clear the same namespace.

Clears One Namespace

clear_tokens removes every token inside the namespace you pass:

register_token("THEME", "ACCENT", "purple")
register_token("THEME", "BACKGROUND", "black")
register_token("THEME", "TEXT", "white")

clear_tokens("THEME")

:say(list_tokens("THEME"))  /// {}

register_token("THEME", "ACCENT", "purple")
register_token("THEME", "BACKGROUND", "black")
register_token("THEME", "TEXT", "white")

clear_tokens("THEME")

:say(list_tokens("THEME"))  /// {}

Use Clear Token when only one token should be removed.

Use Clear All Tokens when every namespace should be removed.

Namespace Capitalization

Token namespace names are case-insensitive. Goblin normalizes them to uppercase:

register_token("theme", "ACCENT", "purple")
register_token("theme", "BACKGROUND", "black")

clear_tokens("THEME")

:say(list_tokens("theme"))  /// {}

register_token("theme", "ACCENT", "purple")
register_token("theme", "BACKGROUND", "black")

clear_tokens("THEME")

:say(list_tokens("theme"))  /// {}

This only applies to the namespace name. Token identifiers inside the namespace keep their own spelling while they exist.

Missing Namespaces

Clearing a namespace that does not exist succeeds without an error:

clear_tokens("MISSING")

clear_tokens("MISSING")

The token registry is unchanged.

What It Does Not Clear

clear_tokens only removes registered tokens from one namespace. It does not remove ordinary variables:

accent | "purple"
register_token("THEME", "ACCENT", accent)

clear_tokens("THEME")

:say(accent)  /// purple

accent | "purple"
register_token("THEME", "ACCENT", accent)

clear_tokens("THEME")

:say(accent)  /// purple

Values already stored in variables remain available.

Return Value

clear_tokens returns unit:

result | clear_tokens("THEME")

:say(result.vt)  /// unit

result | clear_tokens("THEME")

:say(result.vt)  /// unit

Its purpose is the change it makes to the token registry.

Related Clearing Operations

Goblin provides three levels of token removal:

Operation	Removes
`clear_token(namespace, token)`	One token from one namespace.
`clear_tokens(namespace)`	Every token in one namespace.
`clear_all_tokens()`	Every token in every namespace.

Signature

clear_tokens(namespace)
namespace.clear_tokens()

clear_tokens(namespace)
namespace.clear_tokens()

Argument	Type	Description
`namespace`	string	The namespace to clear.

Returns unit.

Errors

clear_tokens requires exactly one namespace:

clear_tokens()
/// error: R0301 wrong-arity

clear_tokens("THEME", "SITE")
/// error: R0301 wrong-arity

clear_tokens()
/// error: R0301 wrong-arity

clear_tokens("THEME", "SITE")
/// error: R0301 wrong-arity

The namespace must be a string:

clear_tokens(42)
/// error: T0205 type-mismatch

clear_tokens(42)
/// error: T0205 type-mismatch

A missing namespace is not an error.