---
slug: 30-io-files
title: Archivos e I/O
description: Leé, escribí, buscá y navegá el filesystem en Synsema — escrituras atómicas, rangos de líneas, list_dir, grep — todo gateado por la capacidad file.
example_ids: [io]
---

# Archivos e I/O

Todo acceso a archivos está gateado por la capacidad `file` (`file.read` / `file.write` para mínimo privilegio). Las escrituras son **atómicas** (archivo temporal + rename).

```synsema
-- Doc example: files & I/O. Needs file capability (deny-by-default).
intent: "doc example: files and I/O"
require file("_doctest_io.txt")

write_file("_doctest_io.txt", "hi from the io demo")
print("read back → " + read_file("_doctest_io.txt"))

test "write then read round-trips (atomic write)"
    write_file("_doctest_io.txt", "hello\nworld")
    assert_eq(read_file("_doctest_io.txt"), "hello\nworld")
    assert(file_exists("_doctest_io.txt"))
```

## Leer

```synsema
read_file(path)                 -- archivo completo como texto
read_file(path, 1, 100)         -- rango de líneas: 1–100 (1-based, conserva EOLs)
read_file(path, 500)            -- desde la línea 500 hasta el final
read_file_bytes(path)           -- byte-exacto, para binarios
```

## Escribir y editar

```synsema
write_file(path, text)          -- sobrescritura atómica
append_file(path, text)         -- append
edit_file(path, old, new)       -- reemplazo de string exacto (old debe ser único; replace_all? para todos)
```

## Navegar y buscar

```synsema
file_exists(path)               -- bool
file_info(path)                 -- {name, is_dir, size, ...}
list_dir(path)                  -- lista de {name, is_dir, size}
grep(target, pattern, opts?)    -- {matches: [{file, line, col, text}], truncated} — por línea, streaming
```

Los scopes de ruta son fieles — un escape con `..` fuera del scope declarado se deniega. Ver **[Capacidades](/es/0.6.x/20-capabilities)**.