lib/zstd
1
0
Fork 0
mirror of https://github.com/facebook/zstd.git synced 2025-08-05 19:15:58 +03:00
Code Activity

Split help in long and short version, cleanup formatting

Browse Source 
Adopt the more standard Usage: formatting style
List short and long options alongside where available
Print lists as a table
Use command style description
This commit is contained in:
Dirk Müller
2022-03-10 01:34:12 +01:00
parent f229daaf42
commit 7fbe60d577
2 changed files with 100 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
programs/zstdcli.c
View File

@@ -143,51 +143,48 @@ static int exeNameMatch(const char* exeName, const char* test)
*/ */
static void usage(FILE* f, const char* programName) static void usage(FILE* f, const char* programName)
{ {
DISPLAY_F(f, "Usage : \n"); DISPLAY_F(f, "Usage: %s [OPTION]... [FILE]... [-o file]\n", programName);
DISPLAY_F(f, " %s [args] [FILE(s)] [-o file] \n", programName); DISPLAY_F(f, "Compress or uncompress FILEs (with no FILE or when FILE is `-`, read from standard input).\n\n");
DISPLAY_F(f, "\n"); DISPLAY_F(f, " -o file result stored into `file` (only 1 output file)\n");
DISPLAY_F(f, "FILE : a filename \n");
DISPLAY_F(f, " with no FILE, or when FILE is - , read standard input\n");
DISPLAY_F(f, "Arguments : \n");
#ifndef ZSTD_NOCOMPRESS #ifndef ZSTD_NOCOMPRESS
DISPLAY_F(f, " -# : # compression level (1-%d, default: %d) \n", ZSTDCLI_CLEVEL_MAX, ZSTDCLI_CLEVEL_DEFAULT); DISPLAY_F(f, " -1 .. -%d compression level (faster .. better; default: %d)\n", ZSTDCLI_CLEVEL_MAX, ZSTDCLI_CLEVEL_DEFAULT);
#endif #endif
#ifndef ZSTD_NODECOMPRESS #ifndef ZSTD_NODECOMPRESS
DISPLAY_F(f, " -d : decompression \n"); DISPLAY_F(f, " -d, --decompress decompression\n");
#endif #endif
DISPLAY_F(f, " -D DICT: use DICT as Dictionary for compression or decompression \n"); DISPLAY_F(f, " -f, --force disable input and output checks. Allows overwriting existing files,\n");
DISPLAY_F(f, " -o file: result stored into `file` (only 1 output file) \n");
DISPLAY_F(f, " -f : disable input and output checks. Allows overwriting existing files,\n");
DISPLAY_F(f, " input from console, output to stdout, operating on links,\n"); DISPLAY_F(f, " input from console, output to stdout, operating on links,\n");
DISPLAY_F(f, " block devices, etc.\n"); DISPLAY_F(f, " block devices, etc.\n");
DISPLAY_F(f, "--rm : remove source file(s) after successful de/compression \n"); DISPLAY_F(f, " --rm remove source file(s) after successful de/compression\n");
DISPLAY_F(f, " -k : preserve source file(s) (default) \n"); DISPLAY_F(f, " -k, --keep preserve source file(s) (default) \n");
#ifdef ZSTD_GZCOMPRESS #ifdef ZSTD_GZCOMPRESS
if (exeNameMatch(programName, ZSTD_GZ)) { /* behave like gzip */ if (exeNameMatch(programName, ZSTD_GZ)) { /* behave like gzip */
DISPLAY_F(f, " -n : do not store original filename when compressing \n"); DISPLAY_F(f, " -n, --no-name do not store original filename when compressing\n");
} }
#endif #endif
DISPLAY_F(f, " -h/-H : display help/long help and exit \n"); DISPLAY_F(f, " -D DICT use DICT as Dictionary for compression or decompression\n");
DISPLAY_F(f, " -h display usage and exit\n");
DISPLAY_F(f, " -H,--help display long help and exit\n");
DISPLAY_F(f, "\n");
} }
static void usage_advanced(const char* programName) static void usage_advanced(const char* programName)
{ {
DISPLAYOUT(WELCOME_MESSAGE); DISPLAYOUT(WELCOME_MESSAGE);
usage(stdout, programName); usage(stdout, programName);
DISPLAYOUT( "\n"); DISPLAYOUT("Advanced options :\n");
DISPLAYOUT( "Advanced arguments : \n"); DISPLAYOUT(" -V, --version display Version number and exit\n");
DISPLAYOUT( " -V : display Version number and exit \n");
DISPLAYOUT( " -c : write to standard output (even if it is the console), keep original file \n"); DISPLAYOUT(" -c, --stdout write to standard output (even if it is the console), keep original file\n");
DISPLAYOUT( " -v : verbose mode; specify multiple times to increase verbosity \n"); DISPLAYOUT(" -v, --verbose verbose mode; specify multiple times to increase verbosity\n");
DISPLAYOUT( " -q : suppress warnings; specify twice to suppress errors too \n"); DISPLAYOUT(" -q, --quiet suppress warnings; specify twice to suppress errors too\n");
DISPLAYOUT( "--[no-]progress : forcibly display, or never display the progress counter.\n"); DISPLAYOUT(" --[no-]progress forcibly display, or never display the progress counter\n");
DISPLAYOUT( " note: any (de)compressed output to terminal will mix with progress counter text. \n"); DISPLAYOUT(" note: any (de)compressed output to terminal will mix with progress counter text\n");
#ifdef UTIL_HAS_CREATEFILELIST #ifdef UTIL_HAS_CREATEFILELIST
DISPLAYOUT( " -r : operate recursively on directories \n"); DISPLAYOUT(" -r operate recursively on directories\n");
DISPLAYOUT( "--filelist FILE : read list of files to operate upon from FILE \n"); DISPLAYOUT(" --filelist FILE read list of files to operate upon from FILE\n");
DISPLAYOUT(" --output-dir-flat DIR : processed files are stored into DIR\n"); DISPLAYOUT(" --output-dir-flat DIR : processed files are stored into DIR\n");
#endif #endif
@@ -195,103 +192,101 @@ static void usage_advanced(const char* programName)
DISPLAYOUT(" --output-dir-mirror DIR : processed files are stored into DIR respecting original directory structure\n"); DISPLAYOUT(" --output-dir-mirror DIR : processed files are stored into DIR respecting original directory structure\n");
#endif #endif
if (AIO_supported()) if (AIO_supported())
DISPLAYOUT( "--[no-]asyncio : use asynchronous IO (default: enabled) \n"); DISPLAYOUT(" --[no-]asyncio use asynchronous IO (default: enabled)\n");
#ifndef ZSTD_NOCOMPRESS #ifndef ZSTD_NOCOMPRESS
DISPLAYOUT( "--[no-]check : during compression, add XXH64 integrity checksum to frame (default: enabled)"); DISPLAYOUT(" --[no-]check during compression, add XXH64 integrity checksum to frame (default: enabled)\n");
#ifndef ZSTD_NODECOMPRESS #ifndef ZSTD_NODECOMPRESS
DISPLAYOUT( ". If specified with -d, decompressor will ignore/validate checksums in compressed frame (default: validate)."); DISPLAYOUT(" if specified with -d, decompressor will ignore/validate checksums in compressed frame (default: validate)\n");
#endif #endif
#else #else
#ifdef ZSTD_NOCOMPRESS #ifdef ZSTD_NOCOMPRESS
DISPLAYOUT( "--[no-]check : during decompression, ignore/validate checksums in compressed frame (default: validate)."); DISPLAYOUT(" --[no-]check during decompression, ignore/validate checksums in compressed frame (default: validate)");
#endif #endif
DISPLAYOUT("\n");
#endif /* ZSTD_NOCOMPRESS */ #endif /* ZSTD_NOCOMPRESS */
#ifndef ZSTD_NOTRACE #ifndef ZSTD_NOTRACE
DISPLAYOUT( "\n"); DISPLAYOUT(" --trace FILE log tracing information to FILE\n");
DISPLAYOUT( "--trace FILE : log tracing information to FILE.");
#endif #endif
DISPLAYOUT( "\n"); DISPLAYOUT(" -- all arguments after \"--\" are treated as files\n");
DISPLAYOUT( "-- : All arguments after \"--\" are treated as files \n");
#ifndef ZSTD_NOCOMPRESS #ifndef ZSTD_NOCOMPRESS
DISPLAYOUT("\n"); DISPLAYOUT("\n");
DISPLAYOUT( "Advanced compression arguments : \n"); DISPLAYOUT("Advanced compression options :\n");
DISPLAYOUT( "--ultra : enable levels beyond %i, up to %i (requires more memory) \n", ZSTDCLI_CLEVEL_MAX, ZSTD_maxCLevel()); DISPLAYOUT(" --ultra enable levels beyond %i, up to %i (requires more memory)\n", ZSTDCLI_CLEVEL_MAX, ZSTD_maxCLevel());
DISPLAYOUT( "--long[=#]: enable long distance matching with given window log (default: %u) \n", g_defaultMaxWindowLog); DISPLAYOUT(" --long[=#] enable long distance matching with given window log (default: %u)\n", g_defaultMaxWindowLog);
DISPLAYOUT( "--fast[=#]: switch to very fast compression levels (default: %u) \n", 1); DISPLAYOUT(" --fast[=#] switch to very fast compression levels (default: %u)\n", 1);
#ifdef ZSTD_GZCOMPRESS #ifdef ZSTD_GZCOMPRESS
if (exeNameMatch(programName, ZSTD_GZ)) { /* behave like gzip */ if (exeNameMatch(programName, ZSTD_GZ)) { /* behave like gzip */
DISPLAYOUT( "--best : compatibility alias for -9 \n"); DISPLAYOUT(" --best compatibility alias for -9 \n");
DISPLAYOUT( "--no-name : do not store original filename when compressing \n"); DISPLAYOUT(" --no-name do not store original filename when compressing\n");
} }
#endif #endif
DISPLAYOUT( "--adapt : dynamically adapt compression level to I/O conditions \n"); DISPLAYOUT(" --adapt dynamically adapt compression level to I/O conditions\n");
DISPLAYOUT(" --[no-]row-match-finder : force enable/disable usage of fast row-based matchfinder for greedy, lazy, and lazy2 strategies\n"); DISPLAYOUT(" --[no-]row-match-finder : force enable/disable usage of fast row-based matchfinder for greedy, lazy, and lazy2 strategies\n");
DISPLAYOUT(" --patch-from=FILE : specify the file to be used as a reference point for zstd's diff engine. \n"); DISPLAYOUT(" --patch-from=FILE : specify the file to be used as a reference point for zstd's diff engine. \n");
# ifdef ZSTD_MULTITHREAD # ifdef ZSTD_MULTITHREAD
DISPLAYOUT( " -T# : spawns # compression threads (default: 1, 0==# cores) \n"); DISPLAYOUT(" -T# spawn # compression threads (default: 1, 0==# cores) \n");
DISPLAYOUT( " -B# : select size of each job (default: 0==automatic) \n"); DISPLAYOUT(" -B# select size of each job (default: 0==automatic) \n");
DISPLAYOUT( "--single-thread : use a single thread for both I/O and compression (result slightly different than -T1) \n"); DISPLAYOUT(" --single-thread use a single thread for both I/O and compression (result slightly different than -T1) \n");
DISPLAYOUT( "--auto-threads={physical,logical} (default: physical} : use either physical cores or logical cores as default when specifying -T0 \n"); DISPLAYOUT(" --auto-threads={physical,logical} : use either physical cores or logical cores as default when specifying -T0 (default: physical)\n");
DISPLAYOUT( "--rsyncable : compress using a rsync-friendly method (-B sets block size) \n"); DISPLAYOUT(" --rsyncable compress using a rsync-friendly method (-B sets block size) \n");
# endif # endif
DISPLAYOUT(" --exclude-compressed : only compress files that are not already compressed \n"); DISPLAYOUT(" --exclude-compressed : only compress files that are not already compressed \n");
DISPLAYOUT( "--stream-size=# : specify size of streaming input from `stdin` \n"); DISPLAYOUT(" --stream-size=# specify size of streaming input from `stdin` \n");
DISPLAYOUT(" --size-hint=# optimize compression parameters for streaming input of approximately this size \n"); DISPLAYOUT(" --size-hint=# optimize compression parameters for streaming input of approximately this size \n");
DISPLAYOUT(" --target-compressed-block-size=# : generate compressed block of approximately targeted size \n"); DISPLAYOUT(" --target-compressed-block-size=# : generate compressed block of approximately targeted size \n");
DISPLAYOUT( "--no-dictID : don't write dictID into header (dictionary compression only) \n"); DISPLAYOUT(" --no-dictID don't write dictID into header (dictionary compression only)\n");
DISPLAYOUT(" --[no-]compress-literals : force (un)compressed literals\n"); DISPLAYOUT(" --[no-]compress-literals : force (un)compressed literals\n");
DISPLAYOUT( "--format=zstd : compress files to the .zst format (default) \n"); DISPLAYOUT(" --format=zstd compress files to the .zst format (default)\n");
#ifdef ZSTD_GZCOMPRESS #ifdef ZSTD_GZCOMPRESS
DISPLAYOUT( "--format=gzip : compress files to the .gz format \n"); DISPLAYOUT(" --format=gzip compress files to the .gz format\n");
#endif #endif
#ifdef ZSTD_LZMACOMPRESS #ifdef ZSTD_LZMACOMPRESS
DISPLAYOUT( "--format=xz : compress files to the .xz format \n"); DISPLAYOUT(" --format=xz compress files to the .xz format\n");
DISPLAYOUT( "--format=lzma : compress files to the .lzma format \n"); DISPLAYOUT(" --format=lzma compress files to the .lzma format\n");
#endif #endif
#ifdef ZSTD_LZ4COMPRESS #ifdef ZSTD_LZ4COMPRESS
DISPLAYOUT( "--format=lz4 : compress files to the .lz4 format \n"); DISPLAYOUT( " --format=lz4 compress files to the .lz4 format\n");
#endif #endif
#endif /* !ZSTD_NOCOMPRESS */ #endif /* !ZSTD_NOCOMPRESS */
#ifndef ZSTD_NODECOMPRESS #ifndef ZSTD_NODECOMPRESS
DISPLAYOUT("\n"); DISPLAYOUT("\n");
DISPLAYOUT( "Advanced decompression arguments : \n"); DISPLAYOUT("Advanced decompression options :\n");
DISPLAYOUT( " -l : print information about zstd compressed files \n"); DISPLAYOUT(" -l print information about zstd compressed files\n");
DISPLAYOUT( "--test : test compressed file integrity \n"); DISPLAYOUT(" --test test compressed file integrity\n");
DISPLAYOUT( " -M# : Set a memory usage limit for decompression \n"); DISPLAYOUT(" -M# Set a memory usage limit for decompression\n");
# if ZSTD_SPARSE_DEFAULT # if ZSTD_SPARSE_DEFAULT
DISPLAYOUT( "--[no-]sparse : sparse mode (default: enabled on file, disabled on stdout) \n"); DISPLAYOUT(" --[no-]sparse sparse mode (default: enabled on file, disabled on stdout)\n");
# else # else
DISPLAYOUT( "--[no-]sparse : sparse mode (default: disabled) \n"); DISPLAYOUT(" --[no-]sparse sparse mode (default: disabled)\n");
# endif # endif
#endif /* ZSTD_NODECOMPRESS */ #endif /* ZSTD_NODECOMPRESS */
#ifndef ZSTD_NODICT #ifndef ZSTD_NODICT
DISPLAYOUT("\n"); DISPLAYOUT("\n");
DISPLAYOUT("Dictionary builder :\n"); DISPLAYOUT("Dictionary builder :\n");
DISPLAYOUT( "--train ## : create a dictionary from a training set of files \n"); DISPLAYOUT(" --train ## create a dictionary from a training set of files\n");
DISPLAYOUT(" --train-cover[=k=#,d=#,steps=#,split=#,shrink[=#]] : use the cover algorithm with optional args\n"); DISPLAYOUT(" --train-cover[=k=#,d=#,steps=#,split=#,shrink[=#]] : use the cover algorithm with optional args\n");
DISPLAYOUT(" --train-fastcover[=k=#,d=#,f=#,steps=#,split=#,accel=#,shrink[=#]] : use the fast cover algorithm with optional args\n"); DISPLAYOUT(" --train-fastcover[=k=#,d=#,f=#,steps=#,split=#,accel=#,shrink[=#]] : use the fast cover algorithm with optional args\n");
DISPLAYOUT(" --train-legacy[=s=#] : use the legacy algorithm with selectivity (default: %u)\n", g_defaultSelectivityLevel); DISPLAYOUT(" --train-legacy[=s=#] : use the legacy algorithm with selectivity (default: %u)\n", g_defaultSelectivityLevel);
DISPLAYOUT( " -o DICT : DICT is dictionary name (default: %s) \n", g_defaultDictName); DISPLAYOUT(" -o DICT DICT is dictionary name (default: %s)\n", g_defaultDictName);
DISPLAYOUT( "--maxdict=# : limit dictionary to specified size (default: %u) \n", g_defaultMaxDictSize); DISPLAYOUT(" --maxdict=# limit dictionary to specified size (default: %u)\n", g_defaultMaxDictSize);
DISPLAYOUT( "--dictID=# : force dictionary ID to specified value (default: random) \n"); DISPLAYOUT(" --dictID=# force dictionary ID to specified value (default: random)\n");
#endif #endif
#ifndef ZSTD_NOBENCH #ifndef ZSTD_NOBENCH
DISPLAYOUT("\n"); DISPLAYOUT("\n");
DISPLAYOUT( "Benchmark arguments : \n"); DISPLAYOUT("Benchmark options : \n");
DISPLAYOUT( " -b# : benchmark file(s), using # compression level (default: %d) \n", ZSTDCLI_CLEVEL_DEFAULT); DISPLAYOUT(" -b# benchmark file(s), using # compression level (default: %d)\n", ZSTDCLI_CLEVEL_DEFAULT);
DISPLAYOUT( " -e# : test all compression levels successively from -b# to -e# (default: 1) \n"); DISPLAYOUT(" -e# test all compression levels successively from -b# to -e# (default: 1)\n");
DISPLAYOUT( " -i# : minimum evaluation time in seconds (default: 3s) \n"); DISPLAYOUT(" -i# minimum evaluation time in seconds (default: 3s)\n");
DISPLAYOUT( " -B# : cut file into independent blocks of size # (default: no block) \n"); DISPLAYOUT(" -B# cut file into independent blocks of size # (default: no block)\n");
DISPLAYOUT( " -S : output one benchmark result per input file (default: consolidated result) \n"); DISPLAYOUT(" -S output one benchmark result per input file (default: consolidated result)\n");
DISPLAYOUT( "--priority=rt : set process priority to real-time \n"); DISPLAYOUT(" --priority=rt set process priority to real-time\n");
#endif #endif
} }
@@ -1099,8 +1094,8 @@ int main(int argCount, const char* argv[])
{ {
/* Display help */ /* Display help */
case 'V': printVersion(); CLEAN_RETURN(0); /* Version Only */ case 'V': printVersion(); CLEAN_RETURN(0); /* Version Only */
case 'H': case 'H': usage_advanced(programName); CLEAN_RETURN(0);
case 'h': usage_advanced(programName); CLEAN_RETURN(0); case 'h': usage(stdout, programName); CLEAN_RETURN(0);
/* Compress */ /* Compress */
case 'z': operation=zom_compress; argument++; break; case 'z': operation=zom_compress; argument++; break;

36
tests/cli-tests/basic/help.sh.stdout.glob
View File

@@ -1,34 +1,24 @@
+ zstd -h + zstd -h
*** zstd command line interface *-bits v1.*.*, by Yann Collet *** Usage: zstd *OPTION*... *FILE*... *-o file*
Usage : Compress or uncompress FILEs (with no FILE or when FILE is `-`, read from standard input).
zstd *args* *FILE(s)* *-o file*
FILE : a filename -o file result stored into `file` (only 1 output file)
with no FILE, or when FILE is - , read standard input -1 .. -19 compression level (faster .. better; default: 3)
Arguments : -d, --decompress decompression
-# : # compression level* -f, --force disable input and output checks. Allows overwriting existing files,
-d : decompression
-D DICT: use DICT as Dictionary for compression or decompression
-o file: result stored into `file` (only 1 output file)
-f : disable input and output checks. Allows overwriting existing files,
input from console, output to stdout, operating on links, input from console, output to stdout, operating on links,
block devices, etc. block devices, etc.
--rm : remove source file(s) after successful de/compression --rm remove source file(s) after successful de/compression
-k : preserve source file(s) (default) -k, --keep preserve source file(s) (default)
-h/-H : display help/long help and exit -D DICT use DICT as Dictionary for compression or decompression
-h display usage and exit
-H,--help display long help and exit
Advanced arguments :
-V : display Version number and exit
...
+ zstd -H + zstd -H
... ...
Arguments : Advanced options :
...
Advanced arguments :
... ...
+ zstd --help + zstd --help
... ...
Arguments : Advanced options :
...
Advanced arguments :
... ...