Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions content/de/rendering/toolkit.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,78 @@ gelöschten Bereichs wird *darum herum* gelöscht und überlebt. Platzierung ist
eine Schätzung; ein Zeichen, das vor einem Augenblick auf jemandes Bildschirm
stand, ist keine.

### FileTree über einem versionierten Arbeitsverzeichnis {#filetree-vcs}

Seit v0.363.0 füllt `FileTree.SetRepository(vcs.Repository)` die Marken `M`, `A`,
`D`, `?` und `!` aus einem [`vcs`](https://github.com/go-widgets/vcs)-Repository:
der Host muss nicht jeden `Status` von Hand setzen. Das Toolkit importiert nur
`vcs` (nur die Standardbibliothek), nie einen Treiber: den registriert der Host.
Der Git-Treiber ist das separate Modul `vcs/git` (go-git, nie das Programm `git`);
`vcs.Detect(dir)` steigt bis zum nächsten Repository auf.

```go
import (
"context"

"github.com/go-widgets/toolkit"
"github.com/go-widgets/vcs"
_ "github.com/go-widgets/vcs/git" // registers the "git" driver
)

// newTree shows dir's files with their git state. post hands a closure to the
// host's UI goroutine.
func newTree(dir string, entries []toolkit.FileEntry, post func(func())) (*toolkit.FileTree, error) {
repo, err := vcs.Detect(dir) // walks up to the nearest repository
if err != nil {
return nil, err // vcs.ErrNoRepository when there is none
}
tree := toolkit.NewFileTree(entries)
tree.PostUI = post // Status runs off the UI goroutine
tree.SetRepository(repo)
tree.StatusError().Subscribe(func(err error) { /* show it */ })
return tree, nil
}

// After a change the tree was not told of, say a save:
func saved(tree *toolkit.FileTree) { tree.RefreshStatusAsync() }

// A refresh you can wait for, on a worker or in a test:
func wait(tree *toolkit.FileTree) error { return tree.RefreshStatus(context.Background()) }
```

Von den Zuständen des Repositorys zu den Marken:

- `Modified`, `Added`, `Deleted`, `Untracked` und `Conflicted` entsprechen dem
gleichnamigen `FileStatus`. `Renamed` wird zu `FileAdded` am neuen Pfad.
`Ignored` hat keine Marke: `FileIgnored` würde nichts zeichnen.
- **Ein Ordner ist `FileModified`, sobald etwas darunter eine Marke trägt, und
`FileConflicted`, sobald etwas darunter im Konflikt ist** (der Konflikt gewinnt).
Das ist die Regel, die der Absatz davor nicht raten will; ein angehängtes
Repository ist die Zustimmung. Ein Ordner, den das Repository selbst meldet (ein
Submodul), behält seinen Zustand, außer darunter liegt ein Konflikt. Ein vom Host
gesetzter `Status` an einem Eintrag gewinnt gegen den des Repositorys.
- Eine gelöschte Datei wird nur markiert, wenn der Host sie noch auflistet: der
Baum erfindet keine Zeilen.
- `Marks()` ist ein `Observable` aller Marken, Ordner eingeschlossen, für eine
Legende oder ein Abzeichen „3 Änderungen“; `StatusError()` ist der Fehler der
letzten Aktualisierung, die dann die vorherigen Marken behält.

Der Baum wendet Anlegen, Umbenennen, Löschen, Verschieben und Import nie selbst
an: das tut der Host und setzt `Entries`, und dieses `Set` aktualisiert die
Marken. `RefreshStatus(ctx)` fragt jetzt und kehrt zurück, wenn die Marken
angewendet sind.

**Warum `PostUI`** (v0.364.0). `Repository.Status` kann bei einem großen Repository
Sekunden dauern (go-git baut den ganzen Status im Speicher auf und nimmt keinen
Kontext), darf also nicht auf der UI-Goroutine laufen; im Browser würde es die
Ereignisschleife der Seite blockieren. Mit `PostUI` führt jede vom Baum gestartete
Aktualisierung (`SetRepository`, eine Änderung von `Entries`,
`RefreshStatusAsync`) `Status` auf einer eigenen Goroutine aus und gibt das
Ergebnis als Closure zurück, **die der Host auf seiner UI-Goroutine ausführt**,
wie bei `collabui.CollabText`. Eine neuere Aktualisierung bricht die laufende ab
und macht ihre verspätete Antwort wirkungslos. Ohne `PostUI` ist alles
synchron, was für einen Test oder einen kleinen Baum richtig ist.

## Binärgröße: ein Programm linkt, was es benutzt {#binary-size}

Das Toolkit ist ein großes Paket, und für den Linker ist das in Ordnung: Die
Expand Down
71 changes: 71 additions & 0 deletions content/en/rendering/toolkit.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,3 +276,74 @@ A folder's status is not derived from its children: "a folder holding a
modified file" is a policy rather than a fact, and git says nothing about
folders at all. An explicit `Dir` entry carries its own status — a submodule, a
directory a merge left conflicted — while an implied parent has none.

#### Filling the marks from a repository

Since v0.363.0, `SetRepository(vcs.Repository)` fills the marks from a
[`vcs`](https://github.com/go-widgets/vcs) repository, so a host does not set
each `Status` by hand. The toolkit imports only `vcs` (standard library only),
never a driver: the host registers one. The git driver is the separate module
`vcs/git` (go-git, never the `git` binary); `vcs.Detect(dir)` walks up to the
nearest repository once a driver is imported.

```go
import (
"context"

"github.com/go-widgets/toolkit"
"github.com/go-widgets/vcs"
_ "github.com/go-widgets/vcs/git" // registers the "git" driver
)

// newTree shows dir's files with their git state. post hands a closure to the
// host's UI goroutine.
func newTree(dir string, entries []toolkit.FileEntry, post func(func())) (*toolkit.FileTree, error) {
repo, err := vcs.Detect(dir) // walks up to the nearest repository
if err != nil {
return nil, err // vcs.ErrNoRepository when there is none
}
tree := toolkit.NewFileTree(entries)
tree.PostUI = post // Status runs off the UI goroutine
tree.SetRepository(repo)
tree.StatusError().Subscribe(func(err error) { /* show it */ })
return tree, nil
}

// After a change the tree was not told of, say a save:
func saved(tree *toolkit.FileTree) { tree.RefreshStatusAsync() }

// A refresh you can wait for, on a worker or in a test:
func wait(tree *toolkit.FileTree) error { return tree.RefreshStatus(context.Background()) }
```

How the repository's states become marks:

- `Modified`, `Added`, `Deleted`, `Untracked` and `Conflicted` map to the
`FileStatus` of the same name. `Renamed` is `FileAdded` at the new path.
`Ignored` has no mark, because `FileIgnored` would draw as nothing.
- **A folder is `FileModified` when anything under it has a mark, and
`FileConflicted` when anything under it is conflicted** (conflicts win). This
is the policy the paragraph above declines to guess; attaching a repository is
the opt-in. A folder the repository reports itself (a submodule) keeps its
state, unless a conflict lies beneath it. A `Status` a host set on an entry
wins over the repository's.
- A deleted file is marked only if the host still lists it: the tree invents no
rows.
- `Marks()` is an `Observable` of every mark, folders included, for a legend or a
"3 changes" badge; `StatusError()` is the last refresh's error. A failed
refresh keeps the previous marks.

The tree never applies a create, rename, delete, move or import: the host does,
and sets `Entries`, and that `Set` refreshes the marks. `RefreshStatus(ctx)`
asks now and returns when the marks are applied.

**Why `PostUI`** (v0.364.0)**.** `Repository.Status` can take seconds on a large repository
(go-git builds the whole status in memory and takes no context), so it must not
run on the UI goroutine, and in a browser it would block the page's event loop.
Set `PostUI` and every refresh the tree starts (`SetRepository`, a change of
`Entries`, `RefreshStatusAsync`) runs `Status` on a goroutine of its own and
hands the result back as a closure that **the host runs on its UI goroutine** —
the same contract as `collabui.CollabText`. A newer refresh cancels the one in
flight and makes its late answer a no-op, so a slow answer never overwrites a
newer one. Without `PostUI` every refresh is synchronous, which is right for a
test or a small tree.
72 changes: 72 additions & 0 deletions content/es/rendering/toolkit.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,78 @@ la persona podía ver y no los que no podía: la inserción de un par dentro del
rango borrado se borra *alrededor* y sobrevive. La colocación es una conjetura;
un carácter que hace un instante estaba en la pantalla de alguien no lo es.

### FileTree sobre un árbol de trabajo versionado {#filetree-vcs}

Desde v0.363.0, `FileTree.SetRepository(vcs.Repository)` rellena las marcas `M`,
`A`, `D`, `?` y `!` desde un repositorio de [`vcs`](https://github.com/go-widgets/vcs):
el anfitrión ya no fija cada `Status` a mano. El toolkit importa solo `vcs`
(solo la biblioteca estándar), nunca un controlador: el anfitrión registra uno.
El controlador de git es el módulo aparte `vcs/git` (go-git, nunca el binario
`git`); `vcs.Detect(dir)` sube hasta el repositorio más cercano.

```go
import (
"context"

"github.com/go-widgets/toolkit"
"github.com/go-widgets/vcs"
_ "github.com/go-widgets/vcs/git" // registers the "git" driver
)

// newTree shows dir's files with their git state. post hands a closure to the
// host's UI goroutine.
func newTree(dir string, entries []toolkit.FileEntry, post func(func())) (*toolkit.FileTree, error) {
repo, err := vcs.Detect(dir) // walks up to the nearest repository
if err != nil {
return nil, err // vcs.ErrNoRepository when there is none
}
tree := toolkit.NewFileTree(entries)
tree.PostUI = post // Status runs off the UI goroutine
tree.SetRepository(repo)
tree.StatusError().Subscribe(func(err error) { /* show it */ })
return tree, nil
}

// After a change the tree was not told of, say a save:
func saved(tree *toolkit.FileTree) { tree.RefreshStatusAsync() }

// A refresh you can wait for, on a worker or in a test:
func wait(tree *toolkit.FileTree) error { return tree.RefreshStatus(context.Background()) }
```

De los estados del repositorio a las marcas:

- `Modified`, `Added`, `Deleted`, `Untracked` y `Conflicted` se corresponden con
el `FileStatus` del mismo nombre. `Renamed` pasa a `FileAdded` en la nueva ruta.
`Ignored` no tiene marca: `FileIgnored` no dibujaría nada.
- **Una carpeta es `FileModified` cuando algo debajo tiene marca, y
`FileConflicted` cuando algo debajo está en conflicto** (el conflicto gana).
Es la política que el párrafo anterior se niega a adivinar; adjuntar un
repositorio es aceptarla. Una carpeta que el propio repositorio informa (un
submódulo) conserva su estado, salvo que haya un conflicto debajo. Un `Status`
fijado por el anfitrión en una entrada gana al del repositorio.
- Un archivo borrado solo se marca si el anfitrión aún lo lista: el árbol no
inventa filas.
- `Marks()` es un `Observable` de todas las marcas, carpetas incluidas, para una
leyenda o una insignia de «3 cambios»; `StatusError()` es el error de la última
actualización, que conserva entonces las marcas anteriores.

El árbol nunca aplica una creación, un cambio de nombre, un borrado, un traslado
o una importación: lo hace el anfitrión y fija `Entries`, y ese `Set` actualiza
las marcas. `RefreshStatus(ctx)` pregunta ahora y vuelve cuando las marcas están
aplicadas.

**Por qué `PostUI`** (v0.364.0). `Repository.Status` puede tardar segundos en un
repositorio grande (go-git construye todo el estado en memoria y no admite
contexto), así que no debe ejecutarse en la goroutine de la interfaz; en un
navegador bloquearía el bucle de eventos de la página. Con `PostUI`, cada
actualización que inicia el árbol (`SetRepository`, un cambio de `Entries`,
`RefreshStatusAsync`) ejecuta `Status` en una goroutine propia y devuelve el
resultado como un cierre **que el anfitrión ejecuta en su goroutine de interfaz**,
igual que `collabui.CollabText`. Una actualización más nueva cancela la que está
en curso y deja sin efecto su respuesta tardía. Sin `PostUI` todo es síncrono, lo
cual vale para una prueba o un árbol pequeño.

## Tamaño del binario: un programa enlaza lo que usa {#binary-size}

El toolkit es un paquete grande, y para el enlazador eso no es un problema: la
Expand Down
72 changes: 72 additions & 0 deletions content/fr/rendering/toolkit.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,78 @@ l'insertion d'un pair à l'intérieur de la plage supprimée est supprimée *aut
et survit. Le placement est une estimation ; un caractère qui était sur l'écran
de quelqu'un il y a un instant n'en est pas une.

### FileTree sur une arborescence versionnée {#filetree-vcs}

Depuis v0.363.0, `FileTree.SetRepository(vcs.Repository)` remplit les marques
`M`, `A`, `D`, `?` et `!` à partir d'un dépôt [`vcs`](https://github.com/go-widgets/vcs) :
l'hôte n'a plus à fixer chaque `Status` à la main. Le toolkit n'importe que `vcs`
(bibliothèque standard seule), jamais un pilote : c'est l'hôte qui en enregistre un.
Le pilote git est le module séparé `vcs/git` (go-git, jamais le binaire `git`) ;
`vcs.Detect(dir)` remonte jusqu'au dépôt le plus proche.

```go
import (
"context"

"github.com/go-widgets/toolkit"
"github.com/go-widgets/vcs"
_ "github.com/go-widgets/vcs/git" // registers the "git" driver
)

// newTree shows dir's files with their git state. post hands a closure to the
// host's UI goroutine.
func newTree(dir string, entries []toolkit.FileEntry, post func(func())) (*toolkit.FileTree, error) {
repo, err := vcs.Detect(dir) // walks up to the nearest repository
if err != nil {
return nil, err // vcs.ErrNoRepository when there is none
}
tree := toolkit.NewFileTree(entries)
tree.PostUI = post // Status runs off the UI goroutine
tree.SetRepository(repo)
tree.StatusError().Subscribe(func(err error) { /* show it */ })
return tree, nil
}

// After a change the tree was not told of, say a save:
func saved(tree *toolkit.FileTree) { tree.RefreshStatusAsync() }

// A refresh you can wait for, on a worker or in a test:
func wait(tree *toolkit.FileTree) error { return tree.RefreshStatus(context.Background()) }
```

Des états du dépôt aux marques :

- `Modified`, `Added`, `Deleted`, `Untracked` et `Conflicted` correspondent au
`FileStatus` du même nom. `Renamed` devient `FileAdded` au nouveau chemin.
`Ignored` n'a pas de marque : `FileIgnored` ne dessinerait rien.
- **Un dossier est `FileModified` dès que quelque chose dessous porte une marque, et
`FileConflicted` dès que quelque chose dessous est en conflit** (le conflit
l'emporte). C'est la politique que le paragraphe précédent refuse de deviner ;
attacher un dépôt vaut adhésion. Un dossier que le dépôt signale lui-même (un
sous-module) garde son état, sauf conflit en dessous. Un `Status` fixé par l'hôte
sur une entrée l'emporte sur celui du dépôt.
- Un fichier supprimé n'est marqué que si l'hôte le liste encore : l'arbre
n'invente aucune ligne.
- `Marks()` est un `Observable` de toutes les marques, dossiers compris, pour une
légende ou un badge « 3 modifications » ; `StatusError()` est l'erreur du dernier
rafraîchissement, qui conserve alors les marques précédentes.

L'arbre n'applique jamais une création, un renommage, une suppression, un
déplacement ou un import : l'hôte le fait et fixe `Entries`, et ce `Set`
rafraîchit les marques. `RefreshStatus(ctx)` interroge maintenant et rend la main
quand les marques sont appliquées.

**Pourquoi `PostUI`** (v0.364.0). `Repository.Status` peut durer des secondes sur
un grand dépôt (go-git construit tout l'état en mémoire et ne prend aucun
contexte) : il ne doit pas s'exécuter sur la goroutine d'interface, et dans un
navigateur il bloquerait la boucle d'événements de la page. Avec `PostUI`, chaque
rafraîchissement lancé par l'arbre (`SetRepository`, un changement de `Entries`,
`RefreshStatusAsync`) exécute `Status` sur une goroutine à part et rend le résultat
sous forme de fermeture **que l'hôte exécute sur sa goroutine d'interface**, comme
`collabui.CollabText`. Un rafraîchissement plus récent annule celui en cours et
rend sa réponse tardive sans effet. Sans `PostUI`, tout est synchrone, ce qui
convient à un test ou à un petit arbre.

## Taille du binaire : un programme lie ce qu'il utilise {#binary-size}

La boîte à outils est un grand paquet, et l'éditeur de liens s'en accommode :
Expand Down
Loading
Loading