Mam wiele zdefiniowanych funkcji .bashrc
, które mają być interaktywnie używane w terminalu. Zazwyczaj poprzedzałem je komentarzem opisującym jego zamierzone użycie:
# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
...
}
Jest to dobre, jeśli przeglądasz kod źródłowy, ale dobrze jest uruchomić type
w terminalu, aby szybko przypomnieć o tym, co robi ta funkcja. Jednak (co zrozumiałe) nie obejmuje komentarzy:
$ type foo
foo is a function
foo ()
{
...
}
Co sprawiło, że pomyślałem: „czy nie byłoby miło, gdyby tego rodzaju komentarze trwały, aby type
mogły zostać wyświetlone?” I w duchu Pythona docstrings wymyśliłem to:
foo() {
: Usage: foo [bar]
: "Foo's a bar into a baz"
...
}
$ type foo
foo is a function
foo ()
{
: Usage: foo [bar];
: "Foo's a bar into a baz";
...
}
Teraz użycie jest uwzględnione w danych type
wyjściowych! Oczywiście, jak widać, cytowanie staje się problemem, który może być podatny na błędy, ale jest przyjemniejszy dla użytkownika, gdy działa.
Moje pytanie brzmi: czy to okropny pomysł? Czy są lepsze alternatywy (takie jak funkcje a man
/ info
for) dla zapewnienia użytkownikom funkcji Bash dodatkowego kontekstu?
Idealnie nadal chciałbym, aby instrukcje użycia znajdowały się w pobliżu definicji funkcji, aby ludzie przeglądający kod źródłowy również skorzystali, ale jeśli istnieje „właściwy” sposób na zrobienie tego, jestem otwarty na alternatywy.
Edytuj to wszystkie dość proste funkcje w stylu pomocnika, a ja po prostu chcę interaktywnie uzyskać dodatkowy kontekst. Z pewnością w przypadku bardziej złożonych skryptów, które analizują flagi, dodałbym --help
opcję, ale dla nich byłoby trochę uciążliwe dodawanie flag pomocy do wszystkiego. Być może to tylko koszt, który powinienem zaakceptować, ale ten :
hack wydaje się działać całkiem dobrze, nie czyniąc źródła o wiele trudniejszym do odczytania naszej edycji.
źródło
--help
opcję.--help
jest również nieinwazyjna, co moim zdaniem jest moim głównym kryterium w tym przypadku. Mogę skończyć z tą:
sztuczką, ponieważ bardziej pasuje ona do mojego przypadku użycia, ale doceniam, że zauważyłeś, że nie jest trudno ją wspierać--help
i że większość użytkowników będzie tego oczekiwać.getopts
.Nigdy do końca nie przekonałem się, aby pogrążyć się i używać
:
poleceń jako komentarzy pseduo. W szczególności zawsze martwiłem się tym, że „komentarze” są w rzeczywistości argumentami, które podlegają ocenie i mogą potencjalnie mieć skutki uboczne (lub po prostu popsuć rzeczy, takie jak błąd'
). Wciąż podoba mi się prostota tego pomysłu, ale nigdy nie uznałem tego kompromisu za całkiem uzasadniony.Moje wahanie z dostarczeniem tekstu użycia za pomocą
--help
flagi lub podobnego zawsze było cruft, który się z tym wiąże. Gdy tylko zaczniesz akceptować flagi, szybko zaczniesz analizować argumenty, co zwykle (w Bash) wymaga całkiem sporej liczby szablonów .Aby częściowo wypełnić tę lukę, zebrałem razem małe narzędzie, które owija się
getopts
w celu zmniejszenia tej płyty kotłowej. Nadal zajmuje kilka linii, więc nie używałbym jej w innych drobnych funkcjach, ale jest o wiele bardziej zwięzły niżgetopts
bezpośrednie. Oto przykład użycia z-h
flagą (getopts
obsługuje tylko opcje jednoliterowe):źródło