# 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"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://craftscript.kenzie.mx/libraries/reflection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.