Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Jak czytać dane wyjściowe na tych stronach

Większość stron w tej sekcji pokazuje zarówno dane wejściowe, jak i wyjściowe: plik, który kompilacja zapisała w dist/, tekst, który kompilacja wypisała w terminalu, albo to, co wypisało narzędzie takie jak tofu uruchomione na wyniku kompilacji.

Te bloki są skopiowane z rzeczywistego uruchomienia, a nie napisane ręcznie. Po samodzielnym zbudowaniu przykładu można porównać własne dane wyjściowe ze stroną wiersz po wierszu.

To porównanie jest jedynym powodem, dla którego dane wyjściowe w ogóle tu są. Kilka z tych stron prosi o zmianę jednego wiersza i ponowną kompilację albo o usunięcie wygenerowanego pliku i ponowne uruchomienie narzędzia, a następnie o odczytanie różnicy. Taką instrukcję warto wykonywać tylko wtedy, gdy blok, z którym się porównuje, jest dokładny — w przeciwnym razie nie da się odróżnić różnicy, którą strona miała pokazać, od takiej, o której po prostu nie wspomniała.

Dlatego blok pokazujący dane wyjściowe jest zawsze w jednym z dwóch stanów i nigdy w stanie pośrednim.

Kompletny

Blok pokazuje całość tego, co wskazała strona. Gdy wprowadzenie mówi o usłudze web, obecny jest każdy wiersz tej usługi. Gdy wskazuje plik, obecny jest cały plik.

Fragment z oznaczeniem miejsca pominięcia

Rzeczywiste dane wyjściowe są często długie, a wypisanie ich w całości ukryłoby jedyny wiersz, którego dotyczy strona. Tam, gdzie pominięto wiersze, blok informuje o tym w osobnym wierszu, w miejscu, w którym je pominięto:

[… omitted: what was left out]

Oto przykład zastosowania. To plan dla przykładu terraform-declared-sensitivity, w którym chodzi o jeden atrybut:

# module.store.terraform_data.reference will be created
+ resource "terraform_data" "reference" {
[… omitted: an id attribute, reported as known only after apply]
+ input = (sensitive value)
[… omitted: an output attribute, reported as known only after apply]
+ triggers_replace = [
+ "app-artifacts",
+ "AKIAEXAMPLE0001",
]
}

Własny plan będzie zawierał te dwa atrybuty. Oznaczenie pozwala wiedzieć, że mają tam być — że są to wiersze, których strona postanowiła nie powtarzać, a nie coś, co kompilacja zrobiła inaczej. Oznaczenie stoi w każdym miejscu, z którego usunięto wiersze, więc ich położenie jest równie czytelne jak ich brak.

Oznaczenie zawsze mówi, co pominięto, a nigdy tylko, że coś pominięto. „Atrybut id, zgłaszany jako znany dopiero po apply” mówi wystarczająco dużo, by rozpoznać ten wiersz po jego napotkaniu; sam wielokropek by nie wystarczył.

Nawiasy są celowe. Wiersz zaczynający się od [… nie jest poprawną treścią w YAML, HCL, JSON ani w żadnym innym formacie wypisywanym na tych stronach, a żadne z pokazanych tu narzędzi takiego wiersza nie wypisuje. Taki wiersz to więc zawsze głos strony, nigdy coś, co wytworzyła kompilacja — nie można go ani pomylić z danymi wyjściowymi, ani przeoczyć podczas pobieżnego czytania.

Co nie jest pominięciem

Cztery rzeczy zmieniają wygląd bloku, niczego nie pomijając, i żadna z nich nie wymaga oznaczenia:

  • Wskazanie mniejszego zakresu. Strona, która mówi o „usłudze web”, a następnie pokazuje tę usługę, niczego nie pominęła z tego, co wskazała. Reszta pliku leży poza zakresem, a nie jest z niego wycięta.
  • Wcięcia. Fragment wyjęty z głęboko zagnieżdżonej struktury jest zwykle pokazywany od lewego marginesu, aby był czytelny samodzielnie. Wiersze są wierszami wygenerowanymi; zmieniły się tylko spacje na początku.
  • Podpis lub uwaga. Wiersz # podający plik, z którego pochodzą wiersze, albo krótka uwaga obok wartości to wyraźnie głos strony, a nie kompilacji.
  • Znak # w każdym wierszu cytowanego komunikatu. Gdy strona pokazuje w jednym bloku polecenie i komunikat, który ono wypisało, komunikat jest zakomentowany, aby cały blok dało się uruchomić. Pojedynczy długi wypisany wiersz może zostać zawinięty na kilka wierszy #, aby pozostał czytelny przy tej szerokości. W obu przypadkach słowa są słowami wypisanymi, w wypisanej kolejności.

Oznaczenie istnieje dla jedynego przypadku, którego nie dałoby się inaczej wykryć: wierszy, których po prostu nie ma.

Blok, który ilustruje, a nie odtwarza

Kilka stron to opisane krok po kroku przykłady, a nie obszary robocze, które można zbudować, a jedna lub dwie pokazują kształt ładunku, a nie konkretne jego uruchomienie. Taki blok nie daje żadnej gwarancji, z którą można by porównywać, więc mówi o tym w otaczającym go tekście — nigdy po cichu nie udaje prawdziwych danych. Jeśli blok tego nie mówi, został skopiowany z uruchomienia i obowiązują go dwa opisane wyżej stany.

Adaptowanie jednej z tych stron

Należy zachować te same dwa stany. Gdy dane wyjściowe się zmieniają — z powodu zmiany przykładu albo dlatego, że nowsze wydanie generuje je inaczej — należy zastąpić blok wynikiem rzeczywistego uruchomienia zamiast edytować go ręcznie i oznaczyć wszystkie pominięte wiersze. Blok edytowany tak, by wyglądał poprawnie, to właśnie to, czemu ta konwencja ma zapobiegać, ponieważ czyta się go dokładnie tak samo jak blok, który sprawdzono.