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-2025 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 #include "src/include/pmix_globals.h"
0100
0101 BEGIN_C_DECLS
0102
0103 /**
0104  * \internal
0105  *
0106  * Initialization of show_help subsystem
0107  */
0108 PMIX_EXPORT pmix_status_t pmix_show_help_init(void);
0109
0110 /**
0111  * \internal
0112  *
0113  * Finalization of show_help subsystem
0114  */
0115 PMIX_EXPORT pmix_status_t pmix_show_help_finalize(void);
0116
0117 /**
0118  * Look up a text message in a text file and display it to the
0119  * stderr using printf()-like substitutions (%d, %s, etc.).
0120  *
0121  * @param filename File where the text messages are contained.
0122  * @param topic String index of which message to display from the
0123  * text file.
0124  * @param want_error_header Display error-bar line header and
0125  * footer with the message.
0126  * @param varargs Any additional parameters are substituted,
0127  * printf()-style into the help message that is displayed.
0128  *
0129  * This function looks for the filename in the $pkgdatadir
0130  * (typically $prefix/share/pmix), and looks up the message
0131  * based on the topic, and displays it.  If want_error_header is
0132  * true, a header and footer of asterisks are also displayed.
0133  *
0134  * Note that the "want_error_header" argument is int instead of bool,
0135  * because passing a parameter that undergoes default argument
0136  * promotion to va_start() has undefined behavior (according to clang
0137  * warnings on MacOS High Sierra).
0138  */
0139 PMIX_EXPORT pmix_status_t pmix_show_help(const char *filename,
0140                                          const char *topic,
0141                                          int want_error_header, ...);
0142
0143 /**
0144  * This function does the same thing as pmix_show_help(), but returns
0145  * its output in a string (that must be freed by the caller).
0146  */
0147 PMIX_EXPORT char *pmix_show_help_string(const char *filename, const char *topic,
0148                                         int want_error_header, ...);
0149
0150 /**
0151  * This function does the same thing as pmix_show_help_string(), but
0152  * accepts a va_list form of varargs.
0153  */
0154 PMIX_EXPORT char *pmix_show_help_vstring(const char *filename,
0155                                          const char *topic,
0156                                          int want_error_header,
0157                                          va_list ap);
0158
0159 /**
0160  * This function adds another search location for the files that
0161  * back show_help messages. Locations will be searched starting
0162  * with the prefix installation directory, then cycled through
0163  * any additional directories in the order they were added
0164  */
0165 PMIX_EXPORT pmix_status_t pmix_show_help_add_data(const char *project,
0166                                                   pmix_show_help_file_t *array);
0167
0168 // check for duplicate entries
0169 PMIX_EXPORT pmix_status_t pmix_help_check_dups(const char *filename,
0170                                                const char *topic);
0171
0172 // output a previously rendered show-help message
0173 PMIX_EXPORT pmix_status_t pmix_show_help_norender(const char *filename,
0174                                                   const char *topic,
0175                                                   const char *output);
0176
0177 PMIX_EXPORT extern bool pmix_show_help_enabled;
0178
0179 END_C_DECLS
0180
0181 #endif