(namespacing)=
# Namespacing
Namespacing is a feature that allows you remap the namespaces used in your systems to something else in the generated files. This is very convenient when you want to keep your code reusable across different projects that use different namespaces. The workflow is simple: When you write your systems, you always use the same namespace, regardless of the project. Then, once you have the namespacing configured, you just let System Template remap that namespace to something that is specific to the project. 

## Filter Configuration
In order to properly use namespacing you have to configure 2 things - System Template settings in the `config.json` file (by adding the `namespace` property) and the `auto_map.json` to alter the paths of the AUTO mapping.

### System Template Configuration
In order to enable namespacing, you have to add the `namespace` property in System Template run {ref}`configuration<configuration-settings>`. Below is an example of how configuration of the `namespace` property might look like:

```json
"namespace": {
    "hook": "nusiq",
    "target": "xyz",
    "keep_hook": true
}
```

- `hook` is the namespace you use in your systems. System Tempalte will look for some variants of this string to replace it. More infrmation below.
- `target` is the namespace you want to replace the `hook` with or a string that you want to append to the `hook`.
- `keep_hook` determines if the `hook` should be kept in the generated files. 

**Example 1**\
hook: `nusiq`\
target: `xyz`\
keep_hook: `true`

This configuration will cause System Template to replace text in all of the text files generated by system template using the following rules:
1. "nusiq_" -> "nusiq_xyz_"
2. "nusiq:" -> "nusiq_xyz:"
3. "nusiq." -> "nusiq_xyz."
4. "nusiq/" -> "nusiq/xyz/" *Note that this one uses '/' not '_'*

With these rules:
- Command `tag @s nusiq_some_tag` would be replaced with `tag @s nusiq_xyz_some_tag`.
- Entity identifier `nusiq:some_entity` would be replaced with `nusiq_xyz:some_entity`.
- Animation `animation.nusiq.some_animation` would be replaced with `animation.nusiq_xyz.some_animation`.
- and function call `function nusiq/some_function` would be replaced with `function nusiq/xyz/some_function`.

**Example 2:**\
hook: `nusiq`\
target: `xyz`\
keep_hook: `false`

1. "nusiq_" -> "xyz_"
2. "nusiq:" -> "xyz:"
3. "nusiq." -> "xyz."
4. "nusiq/" -> "xyz/"

These rules are even simpler. Basically, the `hook` is just replaced with the `target` given it has one of the above characters after it.

## Auto Mapping
Since using the `namespace` property causes changes in the paths (see rule 4 in examples above), you have to adjust the export paths from `auto_map.json` to match that behavior. Luckily, you don't have to worry about doing that yourself. The [default data](https://github.com/Nusiq/regolith-filters/tree/system_template-3.12.0/system_template/data) folder of System Template already provides different configurations of the `auto_map.json` file. By defult, it assumes that you are not using the `namespace` property. If you want to use it, simply delete the default `auto_map.json` and replace it with `auto_map.namespaces.json` (that you can find in the same folder).

In case you want to know how to configure `auto_map.json` yourself, here is an example of one of the mapings:

```json
{
    ".mcfunction": "`f\"BP/functions/{__namespace__['hook']+'/'+__namespace__['target'] if __namespace__['keep_hook'] else __namespace__['target']}/\"`",
}
```

It may look intimidating at the first glance but when it's broken down it's actually really simple.

The `auto_map.json` is evaluated using {ref}`JSON Template<json-template>`. This means that every string that starts and ends with `` ` `` is a Python expression. In our code the expression is an f-string. The interesting part is between the curly braces `{}`. You can see that we are using the `__namespace__` variable. This variable is a dictionary that has the same content as the `namespace` property in the System Template run configuration.

The expression above means "if `keep_hook` is enabled, replace the `hook` with `hook/target`, otherwise just replace the `hook` with `target`".

The `__namespace__` property is added to the scope only if your System Template configuration has the `namespace` in its settings. It's a normal scope variable like any other, if you want you can access it in your systems.