gdext/nameformats

Search:
Group by:

Provides formatter functions for transforming Nim identifiers when exporting them to Godot. This module defines common naming style conversions (snake_case, PascalCase, etc.) and Godot-specific conventions for function and internal function identifiers.

Types

Formatter = proc (str: string): string
A function type that maps an identifier string to a formatted string.

Vars

defaultClassFormatter: Formatter

The default formatter intended for exported classes when neither {.name.} nor {.rename.} is specified.

By default this is asIs, but it can be overridden at compile time.

Example:

import gdext/nameformats
proc set_formatters {.execon: EntryPoint.} =
  nameformats.defaultClassFormatter = nameformats.toGodotClassCase

defaultConstFormatter: Formatter

The default formatter intended for exported constants when neither {.name.} nor {.rename.} is specified.

By default this is asIs, but it can be overridden at compile time.

Example:

import gdext/nameformats
proc set_formatters {.execon: EntryPoint.} =
  nameformats.defaultConstFormatter = nameformats.toUpperSnakeCase

defaultFunctionFormatter: Formatter

The default formatter applied to exported functions when neither {.name.} nor {.rename.} is specified.

By default this is asIs, but it can be overridden at compile time.

Example:

import gdext/nameformats
proc set_formatters {.execon: EntryPoint.} =
  nameformats.defaultFunctionFormatter = nameformats.toGodotFuncCase

defaultPropertyFormatter: Formatter

The default formatter intended for exported properties and signals when neither {.name.} nor {.rename.} is specified.

By default this is asIs, but it can be overridden at compile time.

Example:

import gdext/nameformats
proc set_formatters {.execon: EntryPoint.} =
  nameformats.defaultPropertyFormatter = nameformats.toGodotFuncCase

defaultVirtualMethodFormatter: Formatter

The default formatter intended for exported virtual methods when neither {.name.} nor {.rename.} is specified.

By default this is asIs, but it can be overridden at compile time.

Example:

import gdext/nameformats
proc set_formatters {.execon: EntryPoint.} =
  nameformats.defaultVirtualMethodFormatter = nameformats.toGodotInternalFuncCase

Procs

proc asIs(str: string): string {....raises: [], tags: [], forbids: [].}
Returns str unchanged. Useful for opting out of formatting when exporting identifiers. 
proc ensureLeadingUnderscore(str: string): string {....raises: [], tags: [],
    forbids: [].}
proc multiReplace(replacements: varargs[tuple[sub, by: string]]): Formatter {.
    ...raises: [], tags: [], forbids: [].}

Returns a formatter that applies multiple substring replacements at once. Each (sub, by) pair is replaced in order.

Example:

let f = multiReplace(("foo", "bar"), ("baz", "qux"))
assert f("foo_baz_foo") == "bar_qux_bar"

proc prefix(prefix: string): Formatter {....raises: [], tags: [], forbids: [].}

Returns a formatter that prepends prefix to the input string.

Example:

let f = prefix("godot_")
assert f("signal") == "godot_signal"

proc removePrefix(prefix: string): Formatter {....raises: [], tags: [], forbids: [].}

Returns a formatter that removes prefix from the beginning of the string, if it exists. If str does not start with prefix, the string is returned unchanged.

Example:

let f = removePrefix("gd_")
assert f("gd_player") == "player"
assert f("player") == "player"

proc removeSuffix(suffix: string): Formatter {....raises: [], tags: [], forbids: [].}

Returns a formatter that removes suffix from the end of the string, if it exists. If str does not end with suffix, the string is returned unchanged.

Example:

let f = removeSuffix("_gd")
assert f("player_gd") == "player"
assert f("player") == "player"

proc replace(sub, by: string): Formatter {....raises: [], tags: [], forbids: [].}

Returns a formatter that replaces all occurrences of substring sub with by inside the input string.

Example:

let f = replace("foo", "bar")
assert f("foo_test_foo") == "bar_test_bar"

proc suffix(suffix: string): Formatter {....raises: [], tags: [], forbids: [].}

Returns a formatter that appends suffix to the input string.

Example:

let f = suffix("_gd")
assert f("player") == "player_gd"

proc then(a, b: Formatter): Formatter {....raises: [], tags: [], forbids: [].}

Composes two formatters sequentially. The result of a is passed to b.

Example:

let f = toSnakeCase.then suffix("_gd")
assert f("PlayerID") == "player_id_gd"

proc toCamelCase(str: string): string {....raises: [], tags: [], forbids: [].}

Converts str into camelCase.

Example: "sendHTTPResponse200" -> "sendHttpResponse200"

proc toGodotClassCase(str: string): string {....raises: [], tags: [], forbids: [].}

Converts str into Godot’s recommended type/class naming convention (PascalCase).

Example: "my_custom_resource" -> "MyCustomResource"

proc toGodotConstCase(str: string): string {....raises: [], tags: [], forbids: [].}

Converts str into Godot’s recommended constant naming convention (UPPER_SNAKE_CASE).

Example: "maxSpeed" -> "MAX_SPEED"

proc toGodotFuncCase(str: string): string {....raises: [], tags: [], forbids: [].}

Converts str into Godot’s recommended function naming convention (snake_case).

Example: "sendHTTPResponse200" -> "send_http_response_200"

proc toGodotInternalFuncCase(str: string): string {....raises: [], tags: [],
    forbids: [].}

Converts str into Godot’s internal-function/virtual-method naming convention: snake_case with a leading underscore.

Example: "sendHTTPRequest" -> "_send_http_request"

proc toGodotPropertyCase(str: string): string {....raises: [], tags: [],
    forbids: [].}

Converts str into Godot’s recommended property naming convention (snake_case).

Example: "httpResponseCode" -> "http_response_code"

proc toPascalCase(str: string): string {....raises: [], tags: [], forbids: [].}

Converts str into PascalCase.

Example: "sendHTTPResponse200" -> "SendHttpResponse200"

proc toSnakeCase(str: string): string {....raises: [], tags: [], forbids: [].}

Converts str into lower snake_case.

Example: "sendHTTPResponse200" -> "send_http_response_200"

proc toUpperSnakeCase(str: string): string {....raises: [], tags: [], forbids: [].}

Converts str into UPPER_SNAKE_CASE.

Example: "sendHTTPResponse200" -> "SEND_HTTP_RESPONSE_200"

Iterators

iterator words(str: string): string {....raises: [], tags: [], forbids: [].}

Splits an identifier str into word-like segments.

The splitting rules are designed for converting between naming conventions (snake_case, camelCase, PascalCase, etc.):

  • Underscores (_) act as delimiters.
  • Transitions between lowercase → UPPERCASE, or UPPERCASE → lowercase create boundaries. (e.g. "XMLHttp" → ["XML", "Http"])
  • Digits are separated from letters. (e.g. "Version2Parser" → ["Version", "2", "Parser"])
  • Consecutive uppercase letters are grouped unless followed by a lowercase, in which case the last uppercase starts a new word.

Examples:

  • "sendHTTPResponse200" → ["send", "HTTP", "Response", "200"]
  • "XMLHttpRequest" → ["XML", "Http", "Request"]
  • "my_custom_resource" → ["my", "custom", "resource"]
  • "aaa111Aa" → ["aaa", "111", "Aa"]
  • "aaa111AAa" → ["aaa", "111A", "Aa"]
  • "aaa111aA" → ["aaa", "111a", "A"]

Useful as a foundation for implementing case-conversion formatters.

Templates

template `>>`(a, b: Formatter): Formatter

Operator alias for then, allowing formatter chaining with >>.

Example:

let f = toPascalCase >> prefix("Gd")
assert f("player_id") == "GdPlayerId"


Made with Nim. Generated: 2025-09-13 06:05:00 UTC