Kiedy piszę narzędzia do interfejsu CLI systemu UNIX, jak powinienem sprawić, aby program wydrukował pomoc i / lub użycie?
Zwykle używam fprintf(stderr, "help text here");
, ale jest z tym kilka problemów.
- Po pierwsze, nie jestem pewien, czy powinienem użyć
stderr
. Czy to w porządku, czy powinienem użyćstdout
? - Jak możesz sobie wyobrazić, tekst pomocy jest dość długi, w zależności od liczby opcji dostępnych w narzędziu. Teraz zwykle umieszczam kilka
"strings like that\n"
w drugim parametrze. To jednak wypełnia mój kod źródłowy pięćdziesięcioma lub więcej liniami tekstu pomocy. To wcale nie jest łatwe do opanowania. Co powinienem zamiast tego zrobić? - Kiedy narzędzie nie jest napisane w języku C lub języku podobnym do C, zwykle używam tu-dokumentów tam, gdzie to możliwe (najlepiej w Perlu). Nie mogę tego użyć w C, ale czy jest coś takiego, czego mógłbym użyć?
- Zastanawiałem się nad umieszczeniem go w
headerfile.h
środku#define HELP "help text here"
, nigdy nie widziałem go na wolności, nie wiem, czy powinienem go użyć.
Najlepiej byłoby umieścić tekst w zewnętrznym pliku i dołączyć go. Korzystanie #include
z tego wydaje się jednak niewłaściwe. Więc co powinienem zrobić?
Chodzi o to, aby mieć tekst pomocy, który jest łatwy do zarządzania. Posiadanie go w kodzie źródłowym nie jest naprawdę wygodne.
programming-practices
code-quality
polemon
źródło
źródło
Odpowiedzi:
Zainspiruj się elementami wewnętrznymi platformy docelowej
Zobacz kod źródłowy BSD. Oto na przykład:
usage(void)
dla/usr/bin/uname
narzędzia NetBSD [ źródło ]:usage(void)
dla NetBSD/usr/bin/telnet
[ źródło ]usage(void)
dla OpenBSD/bin/ls
[ źródło ]Spójrz na alternatywy
I sam zdecyduj, czy są lepsze czy gorsze. Możesz użyć Google CodeSearch, aby znaleźć inne, takie jak:
Jak widać, inny styl między nimi a zintegrowanymi narzędziami systemów BSD wymienionymi powyżej. Nie oznacza to, że musisz podążać za jednym lub drugim. Ale zwykle dobrze jest rozejrzeć się i zadowolić spójnym rozwiązaniem.
Niestandardowe rozwiązanie do 50 linii pomocy ...
Jeśli nie lubisz unikać 50 wierszy tekstu, możesz po prostu przeczytać pomoc z pliku tekstowego (w postaci zwykłego tekstu lub bezpośrednio przeanalizować
man
źródło, jeśli je utworzyłeś). Uważam, że jest to dość elegancki sposób (ponieważ możesz nawet przejrzeć dokument tekstowy), jednak w przypadku podstawowych programów systemowych, które z natury sprawiłyby, że byłyby niebezpieczne i spowodowałyby błąd. Inni ludzie będą argumentować, że jest ciężki dla wiadomościusage
lubhelp
wiadomości, ale to nie tak, że są one wywoływane w ciasnych pętlach ...W razie wątpliwości podążaj za gigantami.
źródło
Używam
stdout
, ponieważ pomoc nie jest błędem.Jeśli jest to długa pomoc w C, staram się naśladować tutaj-docs:
Ale przez większość czasu piszę
man
stronę przy użyciunroff -man
dedykowanych tagów. Pomoc w aplikacji polega po prostu na odwoływaniu się do tejman
strony.źródło
stdlog
?stdlog
standard C?cin
,cout
,cerr
, iclog
), więc myślę, że myślałem, żestdlog
był w standardzie C. Mój błąd.Jeśli byłbym ci, że ja po prostu otworzył źródła
grep
,tail
,cat
,your_other_favorite_unix_shell_command
aby zobaczyć, jak to się robi tam. Jestem prawie pewien, że ich sposoby są dość dobrze przemyślane i mogą być utrzymywane przez wiele osób.O
stderr
lubstdout
. To naprawdę proste, jeśli wystąpi błąd - napisz dostderr
, jeśli to tylko informacja -stdout
. Na przykład, jeśli uruchomię twoje narzędzie z niewłaściwymi opcjami, możesz chcieć wyświetlić błąd, powiedzmyUse --help for usage
, że ten należy dostderr
. Jeśli uruchomię Twoje narzędzie z prawidłową opcją--help
, użyjstdout
.Jeśli wolisz nie mieć długich ciągów pomocy w pobliżu swojego kodu, nie rób tego. #define w pliku nagłówkowym jest w porządku, ale tak naprawdę jest to osobista preferencja. Gdybym musiał odczytać kod narzędzia wiersza poleceń, wolałbym, aby jego ciąg pomocy znajdował się w pliku obsługującym opcje podane przez użytkownika.
źródło
Korzystam z biblioteki gnu getopts . Aby uzyskać przykład z pomocą, zobacz ten przykładowy projekt , w szczególności główną metodę na dole parser.y .
Ponieważ jest zawinięty w nawiasy klamrowe, używany przeze mnie edytor vim może złożyć razem linie i nawet ich nie zauważam, kiedy nie muszę.
źródło
Jeśli używam C lub wolę nie polegać na bibliotekach Boost, to trzymam się GNU
getopt
. W przeciwnym razie wolę Opcje programu doładowania, które automatycznie drukują pomoc.Uważam również, że odgadnięcie odpowiedniej opcji jest jedną z najlepszych praktyk, jeśli chodzi o obsługę opcji. Nauczyłem się tego od Gita i teraz używam tego samego w moich projektach. Zasadniczo używa odległości Damerau – Levenshteina do drukowania najlepszych dopasowań, jeśli użytkownik wprowadzi nieznaną opcję wiersza poleceń.
Napisałem o tym mały artykuł , który możesz wykorzystać jako przykład.
Mam nadzieję, że to pomoże :)
źródło
Oczywiście pisanie strony dziury w kodzie cout << lub printf () jest kłopotliwe, szczególnie jeśli trzeba zmienić i ponownie wypełnić akapity. Dlatego oczywiście dobrym pomysłem jest edytowanie tego tekstu w osobnym pliku, na przykład za pomocą emacsa, w którym można łatwiej sformatować tekst.
Następnie możesz użyć następującego skryptu sed, aby przekonwertować ten plik tekstowy na legalny plik nagłówka C:
Następnie, po #include- wpisaniu pliku nagłówka do kodu źródłowego, możesz po prostu napisać tekst za pomocą
źródło