|
17 | 17 | #ifndef INCLUDED_MQBCMD_PARSEUTIL |
18 | 18 | #define INCLUDED_MQBCMD_PARSEUTIL |
19 | 19 |
|
20 | | -//@PURPOSE: Provide a namespace of command parsing functions. |
21 | | -// |
22 | | -//@CLASSES: |
23 | | -// ParseUtil: namespace of command parsing functions |
24 | | -// |
25 | | -//@DESCRIPTION: |
26 | | -// This component provides a namespace, 'mqbcmd::ParseUtil', containing a |
27 | | -// utility function for parsing "trap-like" broker commands. The resulting |
28 | | -// object is an instance of a class generated from 'mqbcmd.xsd'. |
29 | | -// |
30 | | -/// Command Grammar |
31 | | -///--------------- |
32 | | -// The structure of the parsed command is defined by 'mqbcmd.xsd'. The input |
33 | | -// language, however, does not have a formal grammar. Its structure is defined |
34 | | -// by this parser component. An informal description of the language is |
35 | | -// returned by the broker in response to the "HELP" command. |
36 | | -// |
37 | | -/// Usage Example |
38 | | -///------------- |
39 | | -// This section illustrates intended use of this component. |
40 | | -// |
41 | | -/// Example 1: Parsing a Command in a "Trap" Handler |
42 | | -/// - - - - - - - - - - - - - - - - - - - - - - - - |
43 | | -// Suppose that a line of text is read by a command-line like interface and is |
44 | | -// then to be interpreted as a command (e.g. in an "m-trap handler"). The text |
45 | | -// can be parsed into a 'mqbcmd::Command' object using |
46 | | -// 'mqbcmd::ParseUtil::parse': |
47 | | -//.. |
48 | | -// void handleTrap(const bslstl::StringRef& line) |
49 | | -// { |
50 | | -// mqbcmd::Command command; |
51 | | -// bsl::string error; |
52 | | -// |
53 | | -// if (mqbcmd::ParseUtil::parse(&command, &error, line)) { |
54 | | -// BALL_LOG_ERROR << "Unable to parse command string: " << line |
55 | | -// << " due to the error: " << error; |
56 | | -// return; // RETURN |
57 | | -// } |
58 | | -// |
59 | | -// // The command has been successfully parsed. |
60 | | -// dispatch(command); |
61 | | -// } |
62 | | -//.. |
| 20 | +// Clang-format warns about an overlong line in this comment, which gives a |
| 21 | +// Markdown anchor to a header. Unfortunately, by Markdown syntax rules, this |
| 22 | +// has to on the same line as the header, meaning we cannot introduce a |
| 23 | +// line-break here. |
| 24 | + |
| 25 | +// clang-format off |
| 26 | + |
| 27 | +/// @file mqbcmd_parseutil.h |
| 28 | +/// |
| 29 | +/// @brief Provide a namespace of command parsing functions. |
| 30 | +/// |
| 31 | +/// This component provides a namespace, @bbref{mqbcmd::ParseUtil}, containing |
| 32 | +/// a utility function for parsing "trap-like" broker commands. The resulting |
| 33 | +/// object is an instance of a class generated from `mqbcmd.xsd`. |
| 34 | +/// |
| 35 | +/// Command Grammar {#mqbcmd_parseutil_grammar} |
| 36 | +/// =============== |
| 37 | +/// |
| 38 | +/// The structure of the parsed command is defined by `mqbcmd.xsd`. The input |
| 39 | +/// language, however, does not have a formal grammar. Its structure is |
| 40 | +/// defined by this parser component. An informal description of the language |
| 41 | +/// is returned by the broker in response to the "HELP" command. |
| 42 | +/// |
| 43 | +/// Usage Example {#mqbcmd_parseutil_usage} |
| 44 | +/// ============= |
| 45 | +/// |
| 46 | +/// This section illustrates intended use of this component. |
| 47 | +/// |
| 48 | +/// Example 1: Parsing a Command in a "Trap" Handler {#mqbcmd_parseutil_usage_ex1} |
| 49 | +/// ------------------------------------------------ |
| 50 | +/// |
| 51 | +/// Suppose that a line of text is read by a command-line like interface and is |
| 52 | +/// then to be interpreted as a command (e.g. in an "m-trap handler"). The |
| 53 | +/// text can be parsed into a @bbref{mqbcmd::Command} object using |
| 54 | +/// @bbref{mqbcmd::ParseUtil::parse}: |
| 55 | +/// |
| 56 | +/// ``` |
| 57 | +/// void handleTrap(const bslstl::StringRef& line) |
| 58 | +/// { |
| 59 | +/// mqbcmd::Command command; |
| 60 | +/// bsl::string error; |
| 61 | +/// |
| 62 | +/// if (mqbcmd::ParseUtil::parse(&command, &error, line)) { |
| 63 | +/// BALL_LOG_ERROR << "Unable to parse command string: " << line |
| 64 | +/// << " due to the error: " << error; |
| 65 | +/// return; // RETURN |
| 66 | +/// } |
| 67 | +/// |
| 68 | +/// // The command has been successfully parsed. |
| 69 | +/// dispatch(command); |
| 70 | +/// } |
| 71 | +/// ``` |
63 | 72 |
|
64 | | -// MQB |
| 73 | +// clang-format on |
65 | 74 |
|
66 | 75 | // BDE |
67 | 76 | #include <bsl_string.h> |
|
0 commit comments