src/gromacs/commandline/pargs.cpp

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2004, The GROMACS development team.
   6  * Copyright (c) 2013,2014,2015,2016,2017 by the GROMACS development team.
   7  * Copyright (c) 2018,2019,2020, by the GROMACS development team, led by
   8  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   9  * and including many others, as listed in the AUTHORS file in the
  10  * top-level source directory and at http://www.gromacs.org.
  11  *
  12  * GROMACS is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Lesser General Public License
  14  * as published by the Free Software Foundation; either version 2.1
  15  * of the License, or (at your option) any later version.
  16  *
  17  * GROMACS is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public
  23  * License along with GROMACS; if not, see
  24  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  26  *
  27  * If you want to redistribute modifications to GROMACS, please
  28  * consider that scientific software is very special. Version
  29  * control is crucial - bugs must be traceable. We will be happy to
  30  * consider code for inclusion in the official distribution, but
  31  * derived work must not be called official GROMACS. Details are found
  32  * in the README & COPYING files - if they are missing, get the
  33  * official version at http://www.gromacs.org.
  34  *
  35  * To help us fund GROMACS development, we humbly ask that you cite
  36  * the research papers on the package. Check out http://www.gromacs.org.
  37  */
  38 #include "gmxpre.h"
  39
  40 #include "pargs.h"
  41
  42 #include <cstdlib>
  43 #include <cstring>
  44
  45 #include <algorithm>
  46 #include <list>
  47
  48 #include "gromacs/commandline/cmdlinehelpcontext.h"
  49 #include "gromacs/commandline/cmdlinehelpwriter.h"
  50 #include "gromacs/commandline/cmdlineparser.h"
  51 #include "gromacs/fileio/oenv.h"
  52 #include "gromacs/fileio/timecontrol.h"
  53 #include "gromacs/options/basicoptions.h"
  54 #include "gromacs/options/behaviorcollection.h"
  55 #include "gromacs/options/filenameoption.h"
  56 #include "gromacs/options/filenameoptionmanager.h"
  57 #include "gromacs/options/options.h"
  58 #include "gromacs/options/timeunitmanager.h"
  59 #include "gromacs/utility/arrayref.h"
  60 #include "gromacs/utility/basenetwork.h"
  61 #include "gromacs/utility/classhelpers.h"
  62 #include "gromacs/utility/enumerationhelpers.h"
  63 #include "gromacs/utility/exceptions.h"
  64 #include "gromacs/utility/fatalerror.h"
  65 #include "gromacs/utility/gmxassert.h"
  66 #include "gromacs/utility/path.h"
  67 #include "gromacs/utility/programcontext.h"
  68 #include "gromacs/utility/stringutil.h"
  69
  70 /* The source code in this file should be thread-safe.
  71       Please keep it that way. */
  72
  73 int nenum(const char* const enumc[])
  74 {
  75     int i;
  76
  77     i = 1;
  78     /* we *can* compare pointers directly here! */
  79     while (enumc[i] && enumc[0] != enumc[i])
  80     {
  81         i++;
  82     }
  83
  84     return i;
  85 }
  86
  87 int opt2parg_int(const char* option, int nparg, t_pargs pa[])
  88 {
  89     int i;
  90
  91     for (i = 0; (i < nparg); i++)
  92     {
  93         if (strcmp(pa[i].option, option) == 0)
  94         {
  95             return *pa[i].u.i;
  96         }
  97     }
  98
  99     gmx_fatal(FARGS, "No integer option %s in pargs", option);
 100 }
 101
 102 gmx_bool opt2parg_bool(const char* option, int nparg, t_pargs pa[])
 103 {
 104     int i;
 105
 106     for (i = 0; (i < nparg); i++)
 107     {
 108         if (strcmp(pa[i].option, option) == 0)
 109         {
 110             return *pa[i].u.b;
 111         }
 112     }
 113
 114     gmx_fatal(FARGS, "No boolean option %s in pargs", option);
 115
 116     return FALSE;
 117 }
 118
 119 real opt2parg_real(const char* option, int nparg, t_pargs pa[])
 120 {
 121     int i;
 122
 123     for (i = 0; (i < nparg); i++)
 124     {
 125         if (strcmp(pa[i].option, option) == 0)
 126         {
 127             return *pa[i].u.r;
 128         }
 129     }
 130
 131     gmx_fatal(FARGS, "No real option %s in pargs", option);
 132 }
 133
 134 const char* opt2parg_str(const char* option, int nparg, t_pargs pa[])
 135 {
 136     int i;
 137
 138     for (i = 0; (i < nparg); i++)
 139     {
 140         if (strcmp(pa[i].option, option) == 0)
 141         {
 142             return *(pa[i].u.c);
 143         }
 144     }
 145
 146     gmx_fatal(FARGS, "No string option %s in pargs", option);
 147 }
 148
 149 gmx_bool opt2parg_bSet(const char* option, int nparg, const t_pargs* pa)
 150 {
 151     int i;
 152
 153     for (i = 0; (i < nparg); i++)
 154     {
 155         if (strcmp(pa[i].option, option) == 0)
 156         {
 157             return pa[i].bSet;
 158         }
 159     }
 160
 161     gmx_fatal(FARGS, "No such option %s in pargs", option);
 162
 163     return FALSE; /* Too make some compilers happy */
 164 }
 165
 166 const char* opt2parg_enum(const char* option, int nparg, t_pargs pa[])
 167 {
 168     int i;
 169
 170     for (i = 0; (i < nparg); i++)
 171     {
 172         if (strcmp(pa[i].option, option) == 0)
 173         {
 174             return pa[i].u.c[0];
 175         }
 176     }
 177
 178     gmx_fatal(FARGS, "No such option %s in pargs", option);
 179 }
 180
 181 /********************************************************************
 182  * parse_common_args()
 183  */
 184
 185 namespace gmx
 186 {
 187
 188 namespace
 189 {
 190
 191 //! Names for XvgFormat
 192 const gmx::EnumerationArray<XvgFormat, const char*> c_xvgFormatNames = {
 193     { "xmgrace", "xmgr", "none" }
 194 };
 195
 196 /*! \brief Returns the default xvg format, as modified by GMX_VIEW_XVG
 197  * if that environment variable is set.
 198  *
 199  * \ingroup module_commandline
 200  */
 201 XvgFormat getDefaultXvgFormat()
 202 {
 203     const char* const select = getenv("GMX_VIEW_XVG");
 204     if (select != nullptr)
 205     {
 206         for (XvgFormat c : keysOf(c_xvgFormatNames))
 207         {
 208             if (std::strcmp(select, c_xvgFormatNames[c]) == 0)
 209             {
 210                 return c;
 211             }
 212         }
 213         return XvgFormat::None;
 214     }
 215     return XvgFormat::Xmgrace;
 216 }
 217
 218 /*! \brief
 219  * Conversion helper between t_pargs/t_filenm and Options.
 220  *
 221  * This class holds the necessary mapping between the old C structures and
 222  * the new C++ options to allow copying values back after parsing for cases
 223  * where the C++ options do not directly provide the type of value required for
 224  * the C structures.
 225  *
 226  * \ingroup module_commandline
 227  */
 228 class OptionsAdapter
 229 {
 230 public:
 231     /*! \brief
 232      * Initializes the adapter to convert from a specified command line.
 233      *
 234      * The command line is required, because t_pargs wants to return
 235      * strings by reference to the original command line.
 236      * OptionsAdapter creates a copy of the `argv` array (but not the
 237      * strings) to make this possible, even if the parser removes
 238      * options it has recognized.
 239      */
 240     OptionsAdapter(int argc, const char* const argv[]) : argv_(argv, argv + argc) {}
 241
 242     /*! \brief
 243      * Converts a t_filenm option into an Options option.
 244      *
 245      * \param options Options object to add the new option to.
 246      * \param fnm     t_filenm option to convert.
 247      */
 248     void filenmToOptions(Options* options, t_filenm* fnm);
 249     /*! \brief
 250      * Converts a t_pargs option into an Options option.
 251      *
 252      * \param     options Options object to add the new option to.
 253      * \param     pa      t_pargs option to convert.
 254      */
 255     void pargsToOptions(Options* options, t_pargs* pa);
 256
 257     /*! \brief
 258      * Copies values back from options to t_pargs/t_filenm.
 259      */
 260     void copyValues();
 261
 262 private:
 263     struct FileNameData
 264     {
 265         //! Creates a conversion helper for a given `t_filenm` struct.
 266         explicit FileNameData(t_filenm* fnm) : fnm(fnm), optionInfo(nullptr) {}
 267
 268         //! t_filenm structure to receive the final values.
 269         t_filenm* fnm;
 270         //! Option info object for the created FileNameOption.
 271         FileNameOptionInfo* optionInfo;
 272         //! Value storage for the created FileNameOption.
 273         std::vector<std::string> values;
 274     };
 275     struct ProgramArgData
 276     {
 277         //! Creates a conversion helper for a given `t_pargs` struct.
 278         explicit ProgramArgData(t_pargs* pa) :
 279             pa(pa),
 280             optionInfo(nullptr),
 281             enumIndex(0),
 282             boolValue(false)
 283         {
 284         }
 285
 286         //! t_pargs structure to receive the final values.
 287         t_pargs* pa;
 288         //! Option info object for the created option.
 289         OptionInfo* optionInfo;
 290         //! Value storage for a non-enum StringOption (unused for other types).
 291         std::string stringValue;
 292         //! Value storage for an enum option (unused for other types).
 293         int enumIndex;
 294         //! Value storage for a BooleanOption (unused for other types).
 295         bool boolValue;
 296     };
 297
 298     std::vector<const char*> argv_;
 299     // These are lists instead of vectors to avoid relocating existing
 300     // objects in case the container is reallocated (the Options object
 301     // contains pointes to members of the objects, which would get
 302     // invalidated).
 303     std::list<FileNameData>   fileNameOptions_;
 304     std::list<ProgramArgData> programArgs_;
 305
 306     GMX_DISALLOW_COPY_AND_ASSIGN(OptionsAdapter);
 307 };
 308
 309 void OptionsAdapter::filenmToOptions(Options* options, t_filenm* fnm)
 310 {
 311     const bool        bRead     = ((fnm->flag & ffREAD) != 0);
 312     const bool        bWrite    = ((fnm->flag & ffWRITE) != 0);
 313     const bool        bOptional = ((fnm->flag & ffOPT) != 0);
 314     const bool        bLibrary  = ((fnm->flag & ffLIB) != 0);
 315     const bool        bMultiple = ((fnm->flag & ffMULT) != 0);
 316     const bool        bMissing  = ((fnm->flag & ffALLOW_MISSING) != 0);
 317     const char* const name      = (fnm->opt ? &fnm->opt[1] : &ftp2defopt(fnm->ftp)[1]);
 318     const char*       defName   = fnm->fn;
 319     int               defType   = -1;
 320     if (defName == nullptr)
 321     {
 322         defName = ftp2defnm(fnm->ftp);
 323     }
 324     else if (Path::hasExtension(defName))
 325     {
 326         defType = fn2ftp(defName);
 327         GMX_RELEASE_ASSERT(defType != efNR, "File name option specifies an invalid extension");
 328     }
 329     fileNameOptions_.emplace_back(fnm);
 330     FileNameData& data = fileNameOptions_.back();
 331     data.optionInfo    = options->addOption(FileNameOption(name)
 332                                                  .storeVector(&data.values)
 333                                                  .defaultBasename(defName)
 334                                                  .defaultType(defType)
 335                                                  .legacyType(fnm->ftp)
 336                                                  .legacyOptionalBehavior()
 337                                                  .readWriteFlags(bRead, bWrite)
 338                                                  .required(!bOptional)
 339                                                  .libraryFile(bLibrary)
 340                                                  .multiValue(bMultiple)
 341                                                  .allowMissing(bMissing)
 342                                                  .description(ftp2desc(fnm->ftp)));
 343 }
 344
 345 void OptionsAdapter::pargsToOptions(Options* options, t_pargs* pa)
 346 {
 347     const bool        bHidden = startsWith(pa->desc, "HIDDEN");
 348     const char* const name    = &pa->option[1];
 349     const char* const desc    = (bHidden ? &pa->desc[6] : pa->desc);
 350     programArgs_.emplace_back(pa);
 351     ProgramArgData& data = programArgs_.back();
 352     switch (pa->type)
 353     {
 354         case etINT:
 355             data.optionInfo = options->addOption(
 356                     IntegerOption(name).store(pa->u.i).description(desc).hidden(bHidden));
 357             return;
 358         case etINT64:
 359             data.optionInfo = options->addOption(
 360                     Int64Option(name).store(pa->u.is).description(desc).hidden(bHidden));
 361             return;
 362         case etREAL:
 363             data.optionInfo =
 364                     options->addOption(RealOption(name).store(pa->u.r).description(desc).hidden(bHidden));
 365             return;
 366         case etTIME:
 367             data.optionInfo = options->addOption(
 368                     RealOption(name).store(pa->u.r).timeValue().description(desc).hidden(bHidden));
 369             return;
 370         case etSTR:
 371         {
 372             const char* const defValue = (*pa->u.c != nullptr ? *pa->u.c : "");
 373             data.optionInfo            = options->addOption(StringOption(name)
 374                                                          .store(&data.stringValue)
 375                                                          .defaultValue(defValue)
 376                                                          .description(desc)
 377                                                          .hidden(bHidden));
 378             return;
 379         }
 380         case etBOOL:
 381             data.optionInfo = options->addOption(BooleanOption(name)
 382                                                          .store(&data.boolValue)
 383                                                          .defaultValue(*pa->u.b)
 384                                                          .description(desc)
 385                                                          .hidden(bHidden));
 386             return;
 387         case etRVEC:
 388             data.optionInfo = options->addOption(
 389                     RealOption(name).store(*pa->u.rv).vector().description(desc).hidden(bHidden));
 390             return;
 391         case etENUM:
 392         {
 393             // TODO This is the only use of LegacyEnumOption. It
 394             // exists to support dozens of analysis tools use that
 395             // don't make sense to fix without either test coverage or
 396             // automated refactoring. No new uses of LegacyEnumOption
 397             // should be made.
 398             const int defaultIndex = (pa->u.c[0] != nullptr ? nenum(pa->u.c) - 1 : 0);
 399             data.optionInfo        = options->addOption(LegacyEnumOption<int>(name)
 400                                                          .store(&data.enumIndex)
 401                                                          .defaultValue(defaultIndex)
 402                                                          .enumValueFromNullTerminatedArray(pa->u.c + 1)
 403                                                          .description(desc)
 404                                                          .hidden(bHidden));
 405             return;
 406         }
 407     }
 408     GMX_THROW(NotImplementedError("Argument type not implemented"));
 409 }
 410
 411 void OptionsAdapter::copyValues()
 412 {
 413     std::list<FileNameData>::const_iterator file;
 414     for (file = fileNameOptions_.begin(); file != fileNameOptions_.end(); ++file)
 415     {
 416         if (file->optionInfo->isSet())
 417         {
 418             file->fnm->flag |= ffSET;
 419         }
 420         file->fnm->filenames = file->values;
 421     }
 422     std::list<ProgramArgData>::const_iterator arg;
 423     for (arg = programArgs_.begin(); arg != programArgs_.end(); ++arg)
 424     {
 425         arg->pa->bSet = arg->optionInfo->isSet();
 426         switch (arg->pa->type)
 427         {
 428             case etSTR:
 429             {
 430                 if (arg->pa->bSet)
 431                 {
 432                     std::vector<const char*>::const_iterator pos =
 433                             std::find(argv_.begin(), argv_.end(), arg->stringValue);
 434                     GMX_RELEASE_ASSERT(pos != argv_.end(),
 435                                        "String argument got a value not in argv");
 436                     *arg->pa->u.c = *pos;
 437                 }
 438                 break;
 439             }
 440             case etBOOL: *arg->pa->u.b = arg->boolValue; break;
 441             case etENUM: *arg->pa->u.c = arg->pa->u.c[arg->enumIndex + 1]; break;
 442             default:
 443                 // For other types, there is nothing type-specific to do.
 444                 break;
 445         }
 446     }
 447 }
 448
 449 } // namespace
 450
 451 } // namespace gmx
 452
 453 gmx_bool parse_common_args(int*               argc,
 454                            char*              argv[],
 455                            unsigned long      Flags,
 456                            int                nfile,
 457                            t_filenm           fnm[],
 458                            int                npargs,
 459                            t_pargs*           pa,
 460                            int                ndesc,
 461                            const char**       desc,
 462                            int                nbugs,
 463                            const char**       bugs,
 464                            gmx_output_env_t** oenv)
 465 {
 466     // Lambda function to test the (local) Flags parameter against a bit mask.
 467     auto isFlagSet = [Flags](unsigned long bits) { return (Flags & bits) == bits; };
 468
 469     try
 470     {
 471         double                         tbegin = 0.0, tend = 0.0, tdelta = 0.0;
 472         bool                           bBeginTimeSet = false, bEndTimeSet = false, bDtSet = false;
 473         bool                           bView = false;
 474         gmx::OptionsAdapter            adapter(*argc, argv);
 475         gmx::Options                   options;
 476         gmx::OptionsBehaviorCollection behaviors(&options);
 477         gmx::FileNameOptionManager     fileOptManager;
 478
 479         fileOptManager.disableInputOptionChecking(isFlagSet(PCA_DISABLE_INPUT_FILE_CHECKING));
 480         options.addManager(&fileOptManager);
 481
 482         if (isFlagSet(PCA_CAN_SET_DEFFNM))
 483         {
 484             fileOptManager.addDefaultFileNameOption(&options, "deffnm");
 485         }
 486         if (isFlagSet(PCA_CAN_BEGIN))
 487         {
 488             options.addOption(
 489                     gmx::DoubleOption("b").store(&tbegin).storeIsSet(&bBeginTimeSet).timeValue().description("Time of first frame to read from trajectory (default unit %t)"));
 490         }
 491         if (isFlagSet(PCA_CAN_END))
 492         {
 493             options.addOption(
 494                     gmx::DoubleOption("e").store(&tend).storeIsSet(&bEndTimeSet).timeValue().description("Time of last frame to read from trajectory (default unit %t)"));
 495         }
 496         if (isFlagSet(PCA_CAN_DT))
 497         {
 498             options.addOption(gmx::DoubleOption("dt").store(&tdelta).storeIsSet(&bDtSet).timeValue().description(
 499                     "Only use frame when t MOD dt = first time (default unit %t)"));
 500         }
 501         gmx::TimeUnit timeUnit = gmx::TimeUnit::Default;
 502         if (isFlagSet(PCA_TIME_UNIT))
 503         {
 504             std::shared_ptr<gmx::TimeUnitBehavior> timeUnitBehavior(new gmx::TimeUnitBehavior());
 505             timeUnitBehavior->setTimeUnitStore(&timeUnit);
 506             timeUnitBehavior->setTimeUnitFromEnvironment();
 507             timeUnitBehavior->addTimeUnitOption(&options, "tu");
 508             behaviors.addBehavior(timeUnitBehavior);
 509         }
 510         if (isFlagSet(PCA_CAN_VIEW))
 511         {
 512             options.addOption(gmx::BooleanOption("w").store(&bView).description(
 513                     "View output [REF].xvg[ref], [REF].xpm[ref], "
 514                     "[REF].eps[ref] and [REF].pdb[ref] files"));
 515         }
 516
 517         bool bXvgr = false;
 518         for (int i = 0; i < nfile; i++)
 519         {
 520             bXvgr = bXvgr || (fnm[i].ftp == efXVG);
 521         }
 522         XvgFormat xvgFormat = gmx::getDefaultXvgFormat();
 523         if (bXvgr)
 524         {
 525             options.addOption(gmx::EnumOption<XvgFormat>("xvg")
 526                                       .enumValue(gmx::c_xvgFormatNames)
 527                                       .store(&xvgFormat)
 528                                       .description("xvg plot formatting"));
 529         }
 530
 531         /* Now append the program specific arguments */
 532         for (int i = 0; i < nfile; i++)
 533         {
 534             adapter.filenmToOptions(&options, &fnm[i]);
 535         }
 536         for (int i = 0; i < npargs; i++)
 537         {
 538             adapter.pargsToOptions(&options, &pa[i]);
 539         }
 540
 541         const gmx::CommandLineHelpContext* context = gmx::GlobalCommandLineHelpContext::get();
 542         if (context != nullptr)
 543         {
 544             GMX_RELEASE_ASSERT(gmx_node_rank() == 0,
 545                                "Help output should be handled higher up and "
 546                                "only get called only on the master rank");
 547             gmx::CommandLineHelpWriter(options)
 548                     .setHelpText(gmx::constArrayRefFromArray<const char*>(desc, ndesc))
 549                     .setKnownIssues(gmx::constArrayRefFromArray(bugs, nbugs))
 550                     .writeHelp(*context);
 551             return FALSE;
 552         }
 553
 554         /* Now parse all the command-line options */
 555         gmx::CommandLineParser(&options)
 556                 .skipUnknown(isFlagSet(PCA_NOEXIT_ON_ARGS))
 557                 .allowPositionalArguments(isFlagSet(PCA_NOEXIT_ON_ARGS))
 558                 .parse(argc, argv);
 559         behaviors.optionsFinishing();
 560         options.finish();
 561
 562         /* set program name, command line, and default values for output options */
 563         // NOLINTNEXTLINE(bugprone-misplaced-widening-cast)
 564         output_env_init(oenv, gmx::getProgramContext(), timeUnit, bView, xvgFormat, 0);
 565
 566         /* Extract Time info from arguments */
 567         if (bBeginTimeSet)
 568         {
 569             setTimeValue(TBEGIN, tbegin);
 570         }
 571         if (bEndTimeSet)
 572         {
 573             setTimeValue(TEND, tend);
 574         }
 575         if (bDtSet)
 576         {
 577             setTimeValue(TDELTA, tdelta);
 578         }
 579
 580         adapter.copyValues();
 581
 582         return TRUE;
 583     }
 584     GMX_CATCH_ALL_AND_EXIT_WITH_FATAL_ERROR
 585 }