> For the complete documentation index, see [llms.txt](https://craftscript.kenzie.mx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://craftscript.kenzie.mx/libraries/reflection.md).

# Reflection

This library gives a script access to itself.

Reflection is a concept where a program can examine itself and its current state while running. This may also include the ability to access, edit or manipulate features.

{% hint style="danger" %}
Reflection is **dangerous** by nature.

The program is not in a constant state and so, when accessing parts reflectively, the programmer must anticipate what could be happening at any time.
{% endhint %}

## Variables

The `variables` function returns the current environment's variable container.

This object acts like a key<->value [map](/syntax/language-features.md#map-literal), where the keys are the variable names and the values are the variable values.

```java
import [reflection]

number = 10
assert number == 10

variables = run reflection[variables]
assert variables[number] == 10

variables[number=5]
assert number == 5
```

This object **is** the variable container. Changes to the container are immediately reflected in the variables available.

{% hint style="info" %}
Storing the container in a variable means the container contains itself.

```java
import [reflection]

variables = run reflection[variables]
assert variables == variables[variables]
```

{% endhint %}

This can be used to pass the entire variable environment to a function, essentially running its code in the same environment.

{% hint style="danger" %}
Passing the environment to another function or process is not advised and can lead to variable pollution and data corruption.
{% endhint %}

```java
import [reflection]

number = 10
word = "hello"

func = function {
    number = 5
    word = "there"
}

run func run reflection[variables]

assert number == 5
assert word == "there"
```

## Line

The `line` function returns the current line being executed.

```java
import [reflection]

line = run reflection[line]
```

## Script

The `script` function returns the current script being executed.

This allows code to retrieve a script object without knowing its name.

```java
import [reflection]

script = run reflection[script]
/print currently running {script}
```

Inside a function or other anonymous executable the script will be wherever that process was started from.

## Root

The `root` function returns the original script that was run.

```java
import [reflection]

script = run reflection[root]
/print we started at {script}
```

The root script is wherever the current program started, e.g. a script that was run from a command.

## Interpolate

The `interpolate` function attempts to parse interpolations in a text based on the current environment.

A text containing the `{` and `}` interpolation brackets is converted to a formatted version, with the statements inside the brackets having been executed.

```java
import [reflection]

word = "there"
text = "hello {" + "word}"

result = run reflection[interpolate] text

assert result == "hello there"
assert text != "hello there"
```