# IDE Scripts

IDE Scripts let you automate Objo Studio with ordinary Objo code. Choose
**Scripts > New IDE Script**, type some code, then click **Run** or **Debug**.

An IDE Script is a plain UTF-8 file with the `.objoscript` extension. It can read
the current solution, edit source through Studio's undo-aware operations,
compile projects, open documents, write output, show notifications, and start or
stop the active project.

## Your First Script

1. Open a workspace in Objo Studio.
2. Choose **Scripts > New IDE Script**.
3. Enter:

   ```objo
   Var solution As StudioSolution = Studio.Solution.Current

   If solution = Nothing Then
       Studio.Output.WriteLine("No solution is open.")
   Else
       Studio.Output.WriteLine("Current solution: " + solution.Name)
   End If
   ```

4. Click **Run** in the script tab, or choose **Scripts > Run Current Script**.
5. Read the result in Studio's output panel.
6. Save the file when you want to keep it. Studio adds `.objoscript` when
   necessary.

Run always uses the exact text currently in the editor. You can run an unsaved
script, and you do not have to save recent changes before rerunning it.

## Script Commands and Shortcuts

| Action | macOS | Windows and Linux |
|---|---|---|
| New IDE Script | Cmd+Shift+N | Ctrl+Shift+N |
| Open IDE Script | Cmd+Shift+O | Ctrl+Shift+O |
| Run Current Script | Cmd+Option+R | Ctrl+Alt+R |
| Debug Current Script | Cmd+Option+D | Ctrl+Alt+D |
| Stop Script | Cmd+Option+S | Ctrl+Alt+S |

The main Studio **Run** command continues to run the active application. Use the
script tab's buttons or the dedicated **Scripts** menu to run an IDE Script.

Only one IDE Script invocation runs at a time. Click **Stop** to request
cooperative cancellation. If the script does not stop within a short grace
period, Studio terminates its child process and remains available.

## Personal Scripts

Choose **Scripts > Open IDE Scripts Folder** to create and reveal your personal
scripts folder. Saved `.objoscript` files in that folder appear alphabetically
at the bottom of the **Scripts** menu the next time it opens.

Choose a script from that list to run its saved contents directly. Choose
**Scripts > Open IDE Script...** when you want to inspect or edit a file first.
Opening a script never runs it.

## Samples

These six plain `.objoscript` files cover the initial workflows:

- [Report Solution Structure](https://docs.objo.dev/samples/ide-scripts/Report%20Solution%20Structure.objoscript)
  reads the solution without changing it.
- [Add Standard Header](https://docs.objo.dev/samples/ide-scripts/Add%20Standard%20Header.objoscript)
  must be copied into the personal IDE Scripts folder and run from the
  **Scripts** menu while a project method is selected. It inserts a comment
  at the top of that method's visible body using a version-checked edit and
  handles a conflict.
- [Create and Open Module](https://docs.objo.dev/samples/ide-scripts/Create%20and%20Open%20Module.objoscript)
  performs a structural edit and navigates to the result.
- [Compile and Report Diagnostics](https://docs.objo.dev/samples/ide-scripts/Compile%20and%20Report%20Diagnostics.objoscript)
  compiles without modifying the project.
- [Transform JSON Data](https://docs.objo.dev/samples/ide-scripts/Transform%20JSON%20Data.objoscript)
  combines an ordinary Objo class with JSON, a generic dictionary, regular
  expressions, and cryptography.
- [Debug the Average](https://docs.objo.dev/samples/ide-scripts/Debug%20the%20Average.objoscript)
  contains a documented logic error for the
  [interactive debugging walkthrough](ide-scripts-debugging.md#walk-through-the-debugging-sample).

Studio's installed payload contains the same files in its
`IDE Script Samples` folder. The files have no manifest or permission
declaration; open one as normal source or copy it into your personal scripts
folder.

## The Studio API

The shared `Studio` module is available only to IDE Scripts. Its services are:

| Service | Purpose |
|---|---|
| `Studio.Application` | Product and Studio Scripting API version information |
| `Studio.Solution` | Solution snapshots, projects, documents, and structural edits |
| `Studio.Editor` | The active editor, selection, text edits, and navigation |
| `Studio.Diagnostics` | Current diagnostics and explicit project compilation |
| `Studio.Commands` | Typed Save, Run, and Stop application commands |
| `Studio.Output` | Output belonging to the current script invocation |
| `Studio.Notifications` | Rate-limited information and warning notifications |

See the [Studio Scripting API 1.0 reference](ide-scripts-api.md) for
the exact types and members.

All eligible source changes made by one script invocation form one Studio undo
action. Changes you make yourself while a script is running remain separate.
The script's undo group closes whether the script succeeds, fails, is stopped,
or loses its host process.

## AI Assistant

The [AI Assistant](ai-assistant.md) can help author the IDE Script in the active
script tab. It can read the exact current buffer and selection, use the
`StudioScript` completion and symbol catalogue, search this guide and the
generated API reference, make guarded undoable edits when code editing is
enabled, and compile the current buffer to report diagnostics.

Assistant edits remain unsaved. Each response stays bound to the script tab
that was active when you sent the message. Studio also rejects an edit if the
buffer or selected range changes after the assistant reads it, so another tab
is not silently retargeted and newer work is not overwritten.

The assistant cannot save, run, debug, or stop an IDE Script. Review its
changes, then use the script tab or **Scripts** menu yourself. In particular,
generating a script in chat never executes it.

## Language and Standard-Library Profile

IDE scripts are written in normal Objo code. Scripts use the normal parser,
type checker, bytecode emitter, VM semantics, classes, generics, collections,
async features, error handling, and introspection. This means you can use all
of the language's features such as:

- arrays, dictionaries, text, numbers, dates, JSON, XML, and regular
  expressions;
- tasks, cancellation, timers, critical sections, and semaphores;
- introspection and text-based cryptography;
- `Print`, `System.Write`, `System.ErrorWrite`, and `Input`.

It deliberately omits some aspects that could be dangerous including:

- filesystem, special-folder, volume, file-backed stream, and archive APIs;
- networking, sockets, databases, serial devices, shell, and process APIs;
- environment-variable access, URL launching, command-line application state,
  and desktop UI classes; and
- file-backed cryptography such as `Crypto.HashFile`.

## Output, Input, Diagnostics, and Errors

`Studio.Output` writes to the current script's output channel. `Print`,
`System.Write`, and `System.ErrorWrite` remain useful for ordinary program-style
output. Studio keeps script output ordered and distinguishes normal output,
error output, compiler diagnostics, runtime failures, and Objo stack frames.
Output is bounded, so a very noisy script retains the newest text with a
truncation marker.

`Input(...)` writes its prompt and reads a line through Studio's terminal. Stop
also cancels a pending input request.

Compile errors prevent the script from starting and link back to the script
source. Runtime errors include an Objo stack trace. `StudioOperationException`
reports an operation rejected by Studio, while more specific exceptions report
unavailable state, optimistic conflicts, cancellation, and timeouts.

## Authority and Trust

The Studio IDE is protected from from script crashes and hangs but it does not
provide a bullet proof security sandbox.

An IDE Script can edit application source and invoke
`Studio.Commands.RunActiveProject()`. The application then executes with its
normal authority, including any filesystem, network, database, or process APIs
used by that application. Read a script before running it and do not treat
untrusted code as harmless merely because its filename ends in `.objoscript`.

## Read Next

- [Debugging IDE Scripts](ide-scripts-debugging.md)
- [Studio Scripting API 1.0](ide-scripts-api.md)
- [Language Guide](language-guide.md)
- [Debugging applications](debugging.md)