[m-rev.] for post-commit review: improve consistency of usage message for mmc, mprof and mcov
Julien Fischer
jfischer at opturion.com
Mon Sep 4 17:20:24 AEST 2023
Note: I intend to add proper --help and --version messages to any
of the user-facing programs in the Mercury system that currently lack
them. I also intend to add man pages where those are missing.
--------------------------------------
Improve consistency of usage messages for mmc, mprof and mcov.
Hoist code that prints copyright notices out into separate predicates,
so that they can be updated in a single spot.
Use io.format more when generating usage messages.
compiler/handle_options.m:
As above.
Rename usage/2 -> short_usage/2 for consistency with elsewhere.
Add an XXX about a comment that looks to be out-of-date.
compiler/mercury_compile_main.m:
Conform to the above change.
profiler/mercury_profile.m:
As above.
profiler/options.m:
Delete a stray newline.
slice/mcov.m:
As above.
Julien.
diff --git a/compiler/handle_options.m b/compiler/handle_options.m
index 54bb8e6..6b8b11c 100644
--- a/compiler/handle_options.m
+++ b/compiler/handle_options.m
@@ -53,9 +53,9 @@
:- pred usage_errors(io.text_output_stream::in, globals::in,
list(error_spec)::in, io::di, io::uo) is det.
- % Display usage message.
+ % Display short usage message.
%
-:- pred usage(io.text_output_stream::in, io::di, io::uo) is det.
+:- pred short_usage(io.text_output_stream::in, io::di, io::uo) is det.
% Display long usage message for help.
%
@@ -3116,12 +3116,10 @@ disable_smart_recompilation(ProgressStream, OptionDescr, !Globals, !IO) :-
%---------------------------------------------------------------------------%
display_compiler_version(ProgressStream, !IO) :-
- library.version(Version, Fullarch),
- io.write_strings(ProgressStream, [
- "Mercury Compiler, version ", Version, ", on ", Fullarch, "\n",
- "Copyright (C) 1993-2012 The University of Melbourne\n",
- "Copyright (C) 2013-2023 The Mercury team\n"
- ], !IO).
+ library.version(Version, FullArch),
+ io.format(ProgressStream, "Mercury Compiler, version %s, on %s\n",
+ [s(Version), s(FullArch)], !IO),
+ write_copyright_notice(ProgressStream, !IO).
usage_errors(ErrorStream, Globals, Specs, !IO) :-
io.progname_base("mercury_compile", ProgName, !IO),
@@ -3131,9 +3129,10 @@ usage_errors(ErrorStream, Globals, Specs, !IO) :-
:- mutable(already_printed_usage, bool, no, ground,
[untrailed, attach_to_io_state]).
-usage(ProgressStream, !IO) :-
- % usage is called from many places; ensure that we don't print the
+short_usage(ProgressStream, !IO) :-
+ % short_usage is called from many places; ensure that we don't print the
% duplicate copies of the message.
+ % XXX The above doesn't seem to be true anymore.
get_already_printed_usage(AlreadyPrinted, !IO),
(
AlreadyPrinted = no,
@@ -3152,21 +3151,31 @@ long_usage(ProgressStream, !IO) :-
% copies of the long usage message. We can print both a short and along
% usage message, but there is no simple way to avoid that.
library.version(Version, Fullarch),
- Template =
- "Name: mmc -- Melbourne Mercury Compiler, version %s on %s\n" ++
- "Copyright (C) 1993-2012 The University of Melbourne\n" ++
- "Copyright (C) 2013-2023 The Mercury team\n" ++
- "Usage: mmc [<options>] <arguments>\n" ++
- "Arguments:\n" ++
- "\tArguments ending in `.m' are assumed to be source file names.\n" ++
- "\tArguments that do not end in `.m' " ++
- "are assumed to be module names.\n" ++
- "\tArguments in the form @file " ++
- "are replaced with the contents of the file.\n",
- io.format(ProgressStream, Template, [s(Version), s(Fullarch)], !IO),
+ io.format(ProgressStream,
+ "Name: mmc - Melbourne Mercury Compiler, version %s, on %s\n",
+ [s(Version), s(Fullarch)], !IO),
+ write_copyright_notice(ProgressStream, !IO),
+ io.write_strings(ProgressStream, [
+ "Usage: mmc [<options>] <arguments>\n",
+ "Arguments:\n",
+ "\tArguments ending in `.m' are assumed to be source file names.\n",
+ "\tArguments that do not end in `.m' ",
+ "are assumed to be module names.\n",
+ "\tArguments in the form @file ",
+ "are replaced with the contents of the file.\n"
+ ], !IO),
io.write_string(ProgressStream, "Options:\n", !IO),
options_help(ProgressStream, !IO).
+:- pred write_copyright_notice(io.text_output_stream::in, io::di, io::uo)
+ is det.
+
+write_copyright_notice(Stream, !IO) :-
+ io.write_strings(Stream, [
+ "Copyright (C) 1993-2012 The University of Melbourne\n",
+ "Copyright (C) 2013-2023 The Mercury team\n"
+ ], !IO).
+
%---------------------------------------------------------------------------%
% This predicate converts a symbolic name for a set of verbosity options
diff --git a/compiler/mercury_compile_main.m b/compiler/mercury_compile_main.m
index 60e4633..9ecdbc3 100644
--- a/compiler/mercury_compile_main.m
+++ b/compiler/mercury_compile_main.m
@@ -651,7 +651,7 @@ do_op_mode(ProgressStream, ErrorStream, Globals, OpMode, DetectedGradeFlags,
FileNamesFromStdin = no
then
io.stderr_stream(StdErr, !IO),
- usage(StdErr, !IO)
+ short_usage(StdErr, !IO)
else
do_op_mode_args(ProgressStream, ErrorStream, Globals,
OpModeArgs, InvokedByMmcMake, FileNamesFromStdin,
diff --git a/profiler/mercury_profile.m b/profiler/mercury_profile.m
index 677941b..3c703d2 100644
--- a/profiler/mercury_profile.m
+++ b/profiler/mercury_profile.m
@@ -87,7 +87,7 @@ postprocess_options(Args, !IO) :-
Args = [_ | _]
).
- % Display error message and then usage message.
+ % Display error message and then short usage message.
%
:- pred usage_error(string::in, io::di, io::uo) is det.
@@ -96,33 +96,33 @@ usage_error(ErrorMessage, !IO) :-
io.stderr_stream(StdErr, !IO),
io.format(StdErr, "%s: %s\n", [s(ProgName), s(ErrorMessage)], !IO),
io.set_exit_status(1, !IO),
- usage(StdErr, !IO).
+ short_usage(StdErr, !IO).
- % Display usage message.
+ % Display short_usage message.
%
-:- pred usage(io.text_output_stream::in, io::di, io::uo) is det.
+:- pred short_usage(io.text_output_stream::in, io::di, io::uo) is det.
-usage(OutputStream, !IO) :-
+short_usage(OutputStream, !IO) :-
io.progname_base("mprof", ProgName, !IO),
- library.version(Version, Fullarch),
- io.write_strings(OutputStream, [
- "mprof - Mercury profiler, version ", Version, ", on ", Fullarch, "\n",
- "Copyright (C) 1995-2012 The University of Melbourne\n",
- "Copyright (C) 2013-2023 The Mercury team\n",
- "Usage: ", ProgName, " [<options>] [<files>]\n",
- "Use `", ProgName, " --help' for more information.\n"
- ], !IO).
+ library.version(Version, FullArch),
+ io.format(OutputStream, "mprof - Mercury profiler, version %s, on %s\n",
+ [s(Version), s(FullArch)], !IO),
+ write_copyright_notice(OutputStream, !IO),
+ io.format(OutputStream, "Usage: %s[<options>] [<files>]\n",
+ [s(ProgName)], !IO),
+ io.format(OutputStream, "Use `%s --help' for more information.\n",
+ [s(ProgName)], !IO).
:- pred long_usage(io.text_output_stream::in, io::di, io::uo) is det.
long_usage(OutputStream, !IO) :-
io.progname_base("mprof", ProgName, !IO),
- library.version(Version, Fullarch),
+ library.version(Version, FullArch),
+ io.format(OutputStream,
+ "Name: mprof - Mercury profiler, version %s, on %s\n",
+ [s(Version), s(FullArch)], !IO),
+ write_copyright_notice(OutputStream, !IO),
io.write_strings(OutputStream, [
- "Name: mprof - Mercury profiler, version ", Version, ", on ",
- Fullarch, "\n",
- "Copyright (C) 1995-2012 The University of Melbourne\n",
- "Copyright (C) 2013-2023 The Mercury team\n\n",
"Usage: ", ProgName, " [<options>] [<files>]\n",
"\n",
"Description:\n",
@@ -143,6 +143,15 @@ long_usage(OutputStream, !IO) :-
], !IO),
options_help(OutputStream, !IO).
+:- pred write_copyright_notice(io.text_output_stream::in, io::di, io::uo)
+ is det.
+
+write_copyright_notice(OutputStream, !IO) :-
+ io.write_strings(OutputStream, [
+ "Copyright (C) 1995-2012 The University of Melbourne\n",
+ "Copyright (C) 2013-2023 The Mercury team\n"
+ ], !IO).
+
%---------------------------------------------------------------------------%
:- pred main_2(list(string)::in, io::di, io::uo) is det.
diff --git a/profiler/options.m b/profiler/options.m
index 4276131..8d66d0a 100644
--- a/profiler/options.m
+++ b/profiler/options.m
@@ -231,7 +231,7 @@ options_help(Stream, !IO) :-
io.write_prefixed_lines(Stream, "\t", [
"-v, --verbose",
"\tOutput progress messages at each stage.",
- "-V, --very-verbose\n",
+ "-V, --very-verbose",
"\tOutput very verbose progress messages."
], !IO).
diff --git a/slice/mcov.m b/slice/mcov.m
index bbf86e7..bc18068 100644
--- a/slice/mcov.m
+++ b/slice/mcov.m
@@ -436,26 +436,23 @@ write_path_port_for_user(OutStream, port_and_path(Port, Path), !IO) :-
short_usage(OutStream, !IO) :-
io.progname_base("mcov", ProgName, !IO),
library.version(Version, FullArch),
- io.write_strings(OutStream, [
- "Mercury Coverage Testing Tool, version ", Version,
- ", on ", FullArch, ".\n",
- "Copyright (C) 2006-2007, 2010-2012 The University of Melbourne\n",
- "Copyright (C) 2014-2016, 2020-2023 The Mercury team\n",
- "Usage: ", ProgName, " [<options>] [<files>]\n",
- "Use `", ProgName, " --help' for more information.\n"
- ], !IO).
+ io.format(OutStream,
+ "Mercury Coverage Testing Tool, version %s, on %s\n",
+ [s(Version), s(FullArch)], !IO),
+ write_copyright_notice(OutStream, !IO),
+ io.format(OutStream, "Usage: %s [<options>] [<files>]\n",
+ [s(ProgName)], !IO),
+ io.format(OutStream, "Use `%s --help' for more information.\n",
+ [s(ProgName)], !IO).
:- pred long_usage(io.text_output_stream::in, io::di, io::uo) is det.
long_usage(OutStream, !IO) :-
library.version(Version, FullArch),
io.format(OutStream,
- "Name: mcov -- Mercury Coverage Testing Tool, version %s, on %s\n",
+ "Name: mcov - Mercury Coverage Testing Tool, version %s, on %s\n",
[s(Version), s(FullArch)], !IO),
- io.write_string(OutStream,
- "Copyright (C) 2006-2007, 2010-2012 The University of Melbourne\n", !IO),
- io.write_string(OutStream,
- "Copyright (C) 2014-2016, 2020-2023 The Mercury team\n", !IO),
+ write_copyright_notice(OutStream, !IO),
io.write_string(OutStream, "Usage: mcov [<options>] <arguments>\n", !IO),
io.write_string(OutStream, "Arguments:\n", !IO),
io.write_string(OutStream,
@@ -488,6 +485,15 @@ long_usage(OutStream, !IO) :-
%"\treports.".
], !IO).
+:- pred write_copyright_notice(io.text_output_stream::in, io::di, io::uo)
+ is det.
+
+write_copyright_notice(OutStream, !IO) :-
+ io.write_strings(OutStream, [
+ "Copyright (C) 2006-2007, 2010-2012 The University of Melbourne\n",
+ "Copyright (C) 2014-2016, 2020-2023 The Mercury team\n"
+ ], !IO).
+
%---------------------------------------------------------------------------%
:- type option
More information about the reviews
mailing list