src/util/pmix_show_help.h

0001 /*
0002  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0003  *                         University Research and Technology
0004  *                         Corporation.  All rights reserved.
0005  * Copyright (c) 2004-2006 The University of Tennessee and The University
0006  *                         of Tennessee Research Foundation.  All rights
0007  *                         reserved.
0008  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0009  *                         University of Stuttgart.  All rights reserved.
0010  * Copyright (c) 2004-2005 The Regents of the University of California.
0011  *                         All rights reserved.
0012  * Copyright (c) 2008-2011 Cisco Systems, Inc.  All rights reserved.
0013  * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
0014  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0015  * $COPYRIGHT$
0016  *
0017  * Additional copyrights may follow
0018  *
0019  * $HEADER$
0020  */
0021 /**
0022  * @file
0023  *
0024  * The "show help" subsystem (SHS) in PMIX is intended to help the
0025  * developer convey meaningful information to the user (read longer
0026  * than is convenient in a single printf), particularly when errors
0027  * occur.  The SHS allows the storage of arbitrary-length help
0028  * messages in text files which can be parameterized by text filename,
0029  * message name, POSIX locale, and printf()-style parameters (e.g.,
0030  * "%s", "%d", etc.).  Note that the primary purpose of the SHS is to
0031  * display help messages, but it can actually be used to display any
0032  * arbitrary text messages.
0033  *
0034  * The function pmix_show_help() is used to find a help message and
0035  * display it.  Its important parameters are a filename, message name,
0036  * and printf()-style varargs parameters used to substitute into the
0037  * message.
0038  *
0039  * It was originally intended that this system would support a very
0040  * simple version of i18n-like support, but we got (strong) feedback
0041  * that i18n support was not desired.  So it never happened.
0042  *
0043  * As such, the file lookup is quite straightforward -- the caller
0044  * passes in the filename to find the help message, and the SHS looks
0045  * for that file in $pkgdatadir (typically $prefix/share/pmix).
0046  *
0047  * Once the file is successfully opened, the SHS looks for the
0048  * appropriate help message to display.  It looks for the message name
0049  * in the file, reads in the message, and displays it.  printf()-like
0050  * substitutions are performed (e.g., %d, %s, etc.) --
0051  * pmix_show_help() takes a variable length argument list that are
0052  * used for these substitutions.
0053  *
0054  * The format of the help file is simplistic:
0055  *
0056  * - Comments begin with #.  Any characters after a # on a line are
0057  *   ignored.  It is not possible to escape a #.
0058  * - Message names are on a line by themselves and marked with [].
0059  *   Names can be any ASCII string within the [] (excluding the
0060  *   characters newline, linefeed, [, ], and #).
0061  * - Messages are any characters between message names and/or the end
0062  *   of the file.
0063  *
0064  * Here's a sample helpfile:
0065  *
0066  * \verbatimbegin
0067  * # This is a comment.
0068  * [topic 1]
0069  * Here's the first message.  Let's substitute in an integer: %d.
0070  * The quick brown fox jumped over the lazy %s.
0071  * # This is another comment -- it's not displayed in the first message.
0072  * [another:topic:foo:foo:foo]
0073  * This is the second message.  Let's just keep rolling along to get
0074  * to the second line in the message for this example.
0075  * \verbatimend
0076  *
0077  * It is expected that help messages will be grouped by filename;
0078  * similar messages should be in a single file.  For example, an MCA
0079  * component may install its own helpfile in PMIX's $pkgdatadir,
0080  * and therefore the component can invoke pmix_show_help() to display
0081  * its own help messages.
0082  *
0083  * Message files in $pkgdatadir have a naming convention: they
0084  * generally start with the prefix "help-" and are followed by a name
0085  * descriptive of what kind of messages they contain.  MCA components
0086  * should generally abide by the MCA prefix rule, with the exception
0087  * that they should start the filename with "help-", as mentioned
0088  * previously.
0089  */
0090
0091 #ifndef PMIX_SHOW_HELP_H
0092 #define PMIX_SHOW_HELP_H
0093
0094 #include "src/include/pmix_config.h"
0095 #include "pmix_common.h"
0096
0097 #include <stdarg.h>
0098
0099 BEGIN_C_DECLS
0100
0101 /**
0102  * \internal
0103  *
0104  * Initialization of show_help subsystem
0105  */
0106 PMIX_EXPORT pmix_status_t pmix_show_help_init(char *helpdir);
0107
0108 /**
0109  * \internal
0110  *
0111  * Finalization of show_help subsystem
0112  */
0113 PMIX_EXPORT pmix_status_t pmix_show_help_finalize(void);
0114
0115 /**
0116  * Look up a text message in a text file and display it to the
0117  * stderr using printf()-like substitutions (%d, %s, etc.).
0118  *
0119  * @param filename File where the text messages are contained.
0120  * @param topic String index of which message to display from the
0121  * text file.
0122  * @param want_error_header Display error-bar line header and
0123  * footer with the message.
0124  * @param varargs Any additional parameters are substituted,
0125  * printf()-style into the help message that is displayed.
0126  *
0127  * This function looks for the filename in the $pkgdatadir
0128  * (typically $prefix/share/pmix), and looks up the message
0129  * based on the topic, and displays it.  If want_error_header is
0130  * true, a header and footer of asterisks are also displayed.
0131  *
0132  * Note that the "want_error_header" argument is int instead of bool,
0133  * because passing a parameter that undergoes default argument
0134  * promotion to va_start() has undefined behavior (according to clang
0135  * warnings on MacOS High Sierra).
0136  */
0137 PMIX_EXPORT pmix_status_t pmix_show_help(const char *filename,
0138                                          const char *topic,
0139                                          int want_error_header, ...);
0140
0141 /**
0142  * This function does the same thing as pmix_show_help(), but accepts
0143  * a va_list form of varargs.
0144  */
0145 PMIX_EXPORT pmix_status_t pmix_show_vhelp(const char *filename,
0146                                           const char *topic,
0147                                           int want_error_header,
0148                                           va_list ap);
0149
0150 /**
0151  * This function does the same thing as pmix_show_help(), but returns
0152  * its output in a string (that must be freed by the caller).
0153  */
0154 PMIX_EXPORT char *pmix_show_help_string(const char *filename, const char *topic,
0155                                         int want_error_header, ...);
0156
0157 /**
0158  * This function does the same thing as pmix_show_help_string(), but
0159  * accepts a va_list form of varargs.
0160  */
0161 PMIX_EXPORT char *pmix_show_help_vstring(const char *filename,
0162                                          const char *topic,
0163                                          int want_error_header,
0164                                          va_list ap);
0165
0166 /**
0167  * This function adds another search location for the files that
0168  * back show_help messages. Locations will be searched starting
0169  * with the prefix installation directory, then cycled through
0170  * any additional directories in the order they were added
0171  *
0172  * This interface allows libraries that use OMPI to take advantage
0173  * of the show_help functionality. OMPI defines the show_help directory
0174  * based on where OMPI was installed. However, if the library wants to
0175  * use show_help to provide error output specific to itself, then it
0176  * needs to tell pmix_show_help.how to find its own show_help files - without
0177  * interfering with the linked ORTE libs when they need to do show_help.
0178  */
0179 PMIX_EXPORT pmix_status_t pmix_show_help_add_dir(const char *directory);
0180
0181 PMIX_EXPORT pmix_status_t pmix_help_check_dups(const char *filename,
0182                                                const char *topic);
0183
0184 PMIX_EXPORT pmix_status_t pmix_show_help_norender(const char *filename,
0185                                                   const char *topic,
0186                                                   const char *output);
0187
0188 PMIX_EXPORT extern bool pmix_show_help_enabled;
0189
0190 END_C_DECLS
0191
0192 #endif