Current section
Files
Jump to
Current section
Files
GETTING_STARTED.md
# Valence — Getting Started
Guia curto para o Valence 1.0: tipos em Elixir normal, arquivos `.val` e LSP.
## Requisitos
- Elixir **1.20+** (OTP 27+).
- Mix.
- Opcional: Zed para o LSP.
## Instalação
No `mix.exs` do projeto:
```elixir
defp deps do
[
{:valence, "~> 1.0", runtime: false}
]
end
def project do
[
compilers: [:valence, :phoenix_live_view] ++ Mix.compilers(),
deps: deps()
]
end
```
Sem Phoenix, use `compilers: [:valence] ++ Mix.compilers()`.
```bash
mix deps.get
mix compile
```
## Primeiro `.val`
`lib/minha_app/scoring.val`:
```elixir
defmodule MinhaApp.Scoring do
@spec classificar(non_neg_integer()) :: :low | :mid | :high
def classificar(score) when score < 50, do: :low
def classificar(score) when score < 100, do: :mid
def classificar(_score), do: :high
end
```
O modo estrito exige `@spec` em `def` público, confere o corpo contra o
retorno e trata `case` não-exaustivo como erro. `@impl` isenta callbacks.
```bash
mix compile
mix valence.check "lib/**/*.ex" "lib/**/*.val"
mix valence.type lib/minha_app/scoring.val:2:5
```
## LSP no Zed
Adicione a dep acima e instale a extensão:
1. `Cmd+Shift+P` → **zed: install dev extension** → `zed-valence/`.
2. Abra um `.val`. A extensão inicia `mix valence.lsp` no projeto.
3. Para formatar ao salvar:
```json
"languages": {
"Val": {
"formatter": "language_server",
"format_on_save": "on"
}
}
```
Fora de um projeto Mix, instale o escript (`mix escript.install hex valence`)
e use `valence lsp`.
## LiveView
```elixir
defmodule MinhaAppWeb.ProducersLive do
use MinhaAppWeb, :live_view
@impl true
def mount(_params, _session, socket) do
{:ok, assign(socket, :producers, MinhaApp.Producers.list())}
end
@impl true
def render(assigns) do
~H"""
<ul id="producers">
<li :for={producer <- @producers}>{producer.name}</li>
</ul>
"""
end
end
```
Com `reloadable_compilers` no endpoint de dev, alterações em `.val` recarregam
sem reiniciar o servidor:
```elixir
# config/dev.exs
config :minha_app, MinhaAppWeb.Endpoint,
reloadable_compilers: [:phoenix_live_view, :gettext, :elixir, :valence, :app]
```
## Recursos úteis
- Hover/completion/diagnóstico no LSP, inclusive de Ecto/Phoenix.
- Assigns `@nome` tipados no HEEx.
- PubSub: `handle_info({:evento, payload}, ...)` tipado pelo broadcast.
- Cmd+S formata; Cmd+. oferece `# valence:ignore` e `@impl true`.
- Snippets de callbacks (`mount`, `render`, `handle_event`, …).
## Problemas comuns
| sintoma | causa | correção |
| --- | --- | --- |
| task `valence.*` não encontrada | dep não compilada | `mix deps.get`/`mix compile` |
| LSP não inicia no Zed | projeto sem dep `valence` | adicione a dep e reinicie o LSP |
| hover de função própria em `dynamic()` | sem `@spec` e corpo dinâmico | declare `@spec` |
| `mix format` ignora `.val` | fora dos inputs | adicione `lib/**/*.val` ao `.formatter.exs` |
Mais detalhes: [README.md](README.md) e [docs/VAL_AND_ZED.md](docs/VAL_AND_ZED.md).