help.c

   1 /*
   2  * This program is free software; you can redistribute it and/or
   3  * modify it under the terms of the GNU General Public
   4  * License v2 as published by the Free Software Foundation.
   5  *
   6  * This program is distributed in the hope that it will be useful,
   7  * but WITHOUT ANY WARRANTY; without even the implied warranty of
   8  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   9  * General Public License for more details.
  10  *
  11  * You should have received a copy of the GNU General Public
  12  * License along with this program; if not, write to the
  13  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  14  * Boston, MA 021110-1307, USA.
  15  */
  16
  17 #include <stdio.h>
  18 #include <stdlib.h>
  19 #include <string.h>
  20 #include <limits.h>
  21
  22 #include "commands.h"
  23 #include "utils.h"
  24 #include "help.h"
  25
  26 #define USAGE_SHORT             1U
  27 #define USAGE_LONG              2U
  28 #define USAGE_OPTIONS           4U
  29 #define USAGE_LISTING           8U
  30
  31 static int do_usage_one_command(const char * const *usagestr,
  32                                 unsigned int flags, FILE *outf)
  33 {
  34         int pad = 4;
  35
  36         if (!usagestr || !*usagestr)
  37                 return -1;
  38
  39         fprintf(outf, "%s%s", (flags & USAGE_LISTING) ? "    " : "usage: ",
  40                 *usagestr++);
  41
  42         /* a short one-line description (mandatory) */
  43         if ((flags & USAGE_SHORT) == 0)
  44                 return 0;
  45         else if (!*usagestr)
  46                 return -2;
  47         fputc('\n', outf);
  48
  49         if (flags & USAGE_LISTING)
  50                 pad = 8;
  51         else
  52                 fputc('\n', outf);
  53
  54         fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
  55
  56         /* a long (possibly multi-line) description (optional) */
  57         if (!*usagestr || ((flags & USAGE_LONG) == 0))
  58                 return 0;
  59
  60         if (**usagestr)
  61                 fputc('\n', outf);
  62         while (*usagestr && **usagestr)
  63                 fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
  64
  65         /* options (optional) */
  66         if (!*usagestr || ((flags & USAGE_OPTIONS) == 0))
  67                 return 0;
  68
  69         /*
  70          * options (if present) should always (even if there is no long
  71          * description) be prepended with an empty line, skip it
  72          */
  73         usagestr++;
  74
  75         fputc('\n', outf);
  76         while (*usagestr)
  77                 fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
  78
  79         return 0;
  80 }
  81
  82 static int usage_command_internal(const char * const *usagestr,
  83                                   const char *token, int full, int lst,
  84                                   int alias, FILE *outf)
  85 {
  86         unsigned int flags = 0;
  87         int ret;
  88
  89         if (!alias)
  90                 flags |= USAGE_SHORT;
  91         if (full)
  92                 flags |= USAGE_LONG | USAGE_OPTIONS;
  93         if (lst)
  94                 flags |= USAGE_LISTING;
  95
  96         ret = do_usage_one_command(usagestr, flags, outf);
  97         switch (ret) {
  98         case -1:
  99                 fprintf(outf, "No usage for '%s'\n", token);
 100                 break;
 101         case -2:
 102                 fprintf(outf, "No short description for '%s'\n", token);
 103                 break;
 104         }
 105
 106         return ret;
 107 }
 108
 109 static void usage_command_usagestr(const char * const *usagestr,
 110                                    const char *token, int full, int err)
 111 {
 112         FILE *outf = err ? stderr : stdout;
 113         int ret;
 114
 115         ret = usage_command_internal(usagestr, token, full, 0, 0, outf);
 116         if (!ret)
 117                 fputc('\n', outf);
 118 }
 119
 120 void usage_command(const struct cmd_struct *cmd, int full, int err)
 121 {
 122         usage_command_usagestr(cmd->usagestr, cmd->token, full, err);
 123 }
 124
 125 void usage(const char * const *usagestr)
 126 {
 127         usage_command_usagestr(usagestr, NULL, 1, 1);
 128         exit(1);
 129 }
 130
 131 static void usage_command_group_internal(const struct cmd_group *grp, int full,
 132                                          FILE *outf)
 133 {
 134         const struct cmd_struct *cmd = grp->commands;
 135         int do_sep = 0;
 136
 137         for (; cmd->token; cmd++) {
 138                 if (cmd->flags & CMD_HIDDEN)
 139                         continue;
 140
 141                 if (full && cmd != grp->commands)
 142                         fputc('\n', outf);
 143
 144                 if (!cmd->next) {
 145                         if (do_sep) {
 146                                 fputc('\n', outf);
 147                                 do_sep = 0;
 148                         }
 149
 150                         usage_command_internal(cmd->usagestr, cmd->token, full,
 151                                                1, cmd->flags & CMD_ALIAS, outf);
 152                         if (cmd->flags & CMD_ALIAS)
 153                                 putchar('\n');
 154                         continue;
 155                 }
 156
 157                 /* this is an entry point to a nested command group */
 158
 159                 if (!full && cmd != grp->commands)
 160                         fputc('\n', outf);
 161
 162                 usage_command_group_internal(cmd->next, full, outf);
 163
 164                 if (!full)
 165                         do_sep = 1;
 166         }
 167 }
 168
 169 void usage_command_group_short(const struct cmd_group *grp)
 170 {
 171         const char * const *usagestr = grp->usagestr;
 172         FILE *outf = stdout;
 173         const struct cmd_struct *cmd;
 174
 175         if (usagestr && *usagestr) {
 176                 fprintf(outf, "usage: %s\n", *usagestr++);
 177                 while (*usagestr)
 178                         fprintf(outf, "   or: %s\n", *usagestr++);
 179         }
 180
 181         fputc('\n', outf);
 182
 183         fprintf(outf, "Command groups:\n");
 184         for (cmd = grp->commands; cmd->token; cmd++) {
 185                 if (cmd->flags & CMD_HIDDEN)
 186                         continue;
 187
 188                 if (!cmd->next)
 189                         continue;
 190
 191                 fprintf(outf, "  %-16s  %s\n", cmd->token, cmd->next->infostr);
 192         }
 193
 194         fprintf(outf, "\nCommands:\n");
 195         for (cmd = grp->commands; cmd->token; cmd++) {
 196                 if (cmd->flags & CMD_HIDDEN)
 197                         continue;
 198
 199                 if (cmd->next)
 200                         continue;
 201
 202                 fprintf(outf, "  %-16s  %s\n", cmd->token, cmd->usagestr[1]);
 203         }
 204
 205         fputc('\n', outf);
 206         fprintf(stderr, "For an overview of a given command use 'btrfs command --help'\n");
 207         fprintf(stderr, "or 'btrfs [command...] --help --full' to print all available options.\n");
 208         fprintf(stderr, "Any command name can be shortened as far as it stays unambiguous,\n");
 209         fprintf(stderr, "however it is recommended to use full command names in scripts.\n");
 210         fprintf(stderr, "All command groups have their manual page named 'btrfs-<group>'.\n");
 211 }
 212
 213 void usage_command_group(const struct cmd_group *grp, int full, int err)
 214 {
 215         const char * const *usagestr = grp->usagestr;
 216         FILE *outf = err ? stderr : stdout;
 217
 218         if (usagestr && *usagestr) {
 219                 fprintf(outf, "usage: %s\n", *usagestr++);
 220                 while (*usagestr)
 221                         fprintf(outf, "   or: %s\n", *usagestr++);
 222         }
 223
 224         fputc('\n', outf);
 225         usage_command_group_internal(grp, full, outf);
 226         fputc('\n', outf);
 227
 228         if (grp->infostr)
 229                 fprintf(outf, "%s\n", grp->infostr);
 230 }
 231
 232 void help_unknown_token(const char *arg, const struct cmd_group *grp)
 233 {
 234         fprintf(stderr, "%s: unknown token '%s'\n", get_argv0_buf(), arg);
 235         usage_command_group(grp, 0, 1);
 236         exit(1);
 237 }
 238
 239 void help_ambiguous_token(const char *arg, const struct cmd_group *grp)
 240 {
 241         const struct cmd_struct *cmd = grp->commands;
 242
 243         fprintf(stderr, "%s: ambiguous token '%s'\n", get_argv0_buf(), arg);
 244         fprintf(stderr, "\nDid you mean one of these ?\n");
 245
 246         for (; cmd->token; cmd++) {
 247                 if (!prefixcmp(cmd->token, arg))
 248                         fprintf(stderr, "\t%s\n", cmd->token);
 249         }
 250
 251         exit(1);
 252 }
 253
 254 void help_command_group(const struct cmd_group *grp, int argc, char **argv)
 255 {
 256         int full = 0;
 257
 258         if (argc > 1) {
 259                 if (!strcmp(argv[1], "--full"))
 260                         full = 1;
 261         }
 262
 263         usage_command_group(grp, full, 0);
 264 }
 265
 266 int prefixcmp(const char *str, const char *prefix)
 267 {
 268         for (; ; str++, prefix++)
 269                 if (!*prefix)
 270                         return 0;
 271                 else if (*str != *prefix)
 272                         return (unsigned char)*prefix - (unsigned char)*str;
 273 }
 274