Add utility code for really nice command-line option parsing and start using it in the compiler (still WIP).
diff --git a/c++/src/kj/array.c++ b/c++/src/kj/array.c++
index dd01469..53f8ed6 100644
--- a/c++/src/kj/array.c++
+++ b/c++/src/kj/array.c++
@@ -54,6 +54,12 @@
}
}
+const NullArrayDisposer NullArrayDisposer::instance = NullArrayDisposer();
+
+void NullArrayDisposer::disposeImpl(
+ void* firstElement, size_t elementSize, size_t elementCount,
+ size_t capacity, void (*destroyElement)(void*)) const {}
+
namespace _ { // private
void* HeapArrayDisposer::allocateImpl(size_t elementSize, size_t elementCount, size_t capacity,
diff --git a/c++/src/kj/array.h b/c++/src/kj/array.h
index 2f7e86b..0bd0233 100644
--- a/c++/src/kj/array.h
+++ b/c++/src/kj/array.h
@@ -108,6 +108,17 @@
size_t capacity, void (*destroyElement)(void*)) const override;
};
+class NullArrayDisposer: public ArrayDisposer {
+ // An ArrayDisposer that does nothing. Can be used to construct a fake Arrays that doesn't
+ // actually own its content.
+
+public:
+ static const NullArrayDisposer instance;
+
+ void disposeImpl(void* firstElement, size_t elementSize, size_t elementCount,
+ size_t capacity, void (*destroyElement)(void*)) const override;
+};
+
// =======================================================================================
// Array
diff --git a/c++/src/kj/function-test.c++ b/c++/src/kj/function-test.c++
new file mode 100644
index 0000000..ce1ee75
--- /dev/null
+++ b/c++/src/kj/function-test.c++
@@ -0,0 +1,83 @@
+// Copyright (c) 2013, Kenton Varda <[email protected]>
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice, this
+// list of conditions and the following disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+// this list of conditions and the following disclaimer in the documentation
+// and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#include "function.h"
+#include <gtest/gtest.h>
+
+namespace kj {
+namespace {
+
+TEST(Function, Lambda) {
+ int i = 0;
+
+ Function<int(int, int)> f = [&](int a, int b) { return a + b + i++; };
+
+ EXPECT_EQ(123 + 456, f(123, 456));
+ EXPECT_EQ(7 + 8 + 1, f(7, 8));
+ EXPECT_EQ(9 + 2 + 2, f(2, 9));
+
+ EXPECT_EQ(i, 3);
+}
+
+struct TestType {
+ int callCount;
+
+ TestType(int callCount = 0): callCount(callCount) {}
+
+ ~TestType() { callCount = 1234; }
+ // Make sure we catch invalid post-destruction uses.
+
+ int foo(int a, int b) {
+ return a + b + callCount++;
+ }
+};
+
+TEST(Function, Method) {
+ TestType obj;
+ Function<int(int, int)> f = KJ_BIND_METHOD(obj, foo);
+ Function<uint(uint, uint)> f2 = KJ_BIND_METHOD(obj, foo);
+
+ EXPECT_EQ(123 + 456, f(123, 456));
+ EXPECT_EQ(7 + 8 + 1, f(7, 8));
+ EXPECT_EQ(9 + 2 + 2, f2(2, 9));
+
+ EXPECT_EQ(3, obj.callCount);
+
+ // Bind to a temporary.
+ f = KJ_BIND_METHOD(TestType(10), foo);
+
+ EXPECT_EQ(123 + 456 + 10, f(123, 456));
+ EXPECT_EQ(7 + 8 + 11, f(7, 8));
+ EXPECT_EQ(9 + 2 + 12, f(2, 9));
+
+ // Bind to a move.
+ f = KJ_BIND_METHOD(kj::mv(obj), foo);
+ obj.callCount = 1234;
+
+ EXPECT_EQ(123 + 456 + 3, f(123, 456));
+ EXPECT_EQ(7 + 8 + 4, f(7, 8));
+ EXPECT_EQ(9 + 2 + 5, f(2, 9));
+}
+
+} // namespace
+} // namespace kj
diff --git a/c++/src/kj/function.h b/c++/src/kj/function.h
new file mode 100644
index 0000000..bdb8428
--- /dev/null
+++ b/c++/src/kj/function.h
@@ -0,0 +1,155 @@
+// Copyright (c) 2013, Kenton Varda <[email protected]>
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice, this
+// list of conditions and the following disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+// this list of conditions and the following disclaimer in the documentation
+// and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#ifndef KJ_FUNCTION_H_
+#define KJ_FUNCTION_H_
+
+#include "memory.h"
+
+namespace kj {
+
+template <typename Signature>
+class Function;
+// Function wrapper using virtual-based polymorphism. Use this when template polymorphism is
+// not possible. You can, for example, accept a Function as a parameter:
+//
+// void setFilter(Function<bool(const Widget&)> filter);
+//
+// The caller of `setFilter()` may then pass any callable object as the parameter. The callable
+// object does not have to have the exact signature specified, just one that is "compatible" --
+// i.e. the return type is covariant and the parameters are contravariant.
+//
+// Unlike `std::function`, `kj::Function`s are movable but not copyable, just like `kj::Own`. This
+// is to avoid unexpected heap allocation or slow atomic reference counting.
+//
+// When a `Function` is constructed from an lvalue, it captures only a reference to the value.
+// When constructed from an rvalue, it invokes the value's move constructor. So, for example:
+//
+// struct AddN {
+// int n;
+// int operator(int i) { return i + n; }
+// }
+//
+// Function<int(int, int)> f1 = AddN{2};
+// // f1 owns an instance of AddN. It may safely be moved out
+// // of the local scope.
+//
+// AddN adder(2);
+// Function<int(int, int)> f2 = adder;
+// // f2 contains a reference to `adder`. Thus, it becomes invalid
+// // when `adder` goes out-of-scope.
+//
+// AddN adder2(2);
+// Function<int(int, int)> f3 = kj::mv(adder2);
+// // f3 owns an insatnce of AddN moved from `adder2`. f3 may safely
+// // be moved out of the local scope.
+//
+// Additionally, a Function may be bound to a class method using KJ_BIND_METHOD(object, methodName).
+// For example:
+//
+// class Printer {
+// public:
+// void print(int i);
+// void print(kj::StringPtr s);
+// };
+//
+// Printer p;
+//
+// Function<void(uint)> intPrinter = KJ_BIND_METHOD(p, print);
+// // Will call Printer::print(int).
+//
+// Function<void(const char*)> strPrinter = KJ_BIND_METHOD(p, print);
+// // Will call Printer::print(kj::StringPtr).
+//
+// Notice how KJ_BIND_METHOD is able to figure out which overload to use depending on the kind of
+// Function it is binding to.
+
+template <typename Return, typename... Params>
+class Function<Return(Params...)> {
+public:
+ template <typename F>
+ inline Function(F&& f): impl(heap<Impl<F>>(kj::fwd<F>(f))) {}
+ Function() = default;
+
+ inline Return operator()(Params... params) {
+ return (*impl)(kj::fwd<Params>(params)...);
+ }
+
+private:
+ class Iface {
+ public:
+ virtual Return operator()(Params... params) = 0;
+ };
+
+ template <typename F>
+ class Impl final: public Iface {
+ public:
+ explicit Impl(F&& f): f(kj::fwd<F>(f)) {}
+
+ Return operator()(Params... params) override {
+ return f(kj::fwd<Params>(params)...);
+ }
+
+ private:
+ F f;
+ };
+
+ Own<Iface> impl;
+};
+
+namespace _ {
+
+template <typename T>
+T rvalueOrRef(T&&);
+// Hack to help detect if an expression is an lvalue or an rvalue.
+//
+// int i;
+// decltype(i) i1(i); // i1 has type int.
+// decltype(rvalueOrRef(i)) i2(i); // i2 has type int&.
+// decltype(rvalueOrRef(kj::mv(i)) i3(kj::mv(i)); // i3 has type int.
+
+} // namespace _
+
+#define KJ_BIND_METHOD(obj, method) \
+ ({ \
+ typedef decltype(::kj::_::rvalueOrRef(obj)) T; \
+ class F { \
+ public: \
+ inline F(T&& t): t(::kj::fwd<T>(t)) {} \
+ template <typename... Params> \
+ auto operator()(Params&&... params) \
+ -> decltype(::kj::instance<T>().method(::kj::fwd<Params>(params)...)) { \
+ return t.method(::kj::fwd<Params>(params)...); \
+ } \
+ private: \
+ T t; \
+ }; \
+ (F(obj)); \
+ })
+// Macro that produces a functor object which forwards to the method `obj.name`. If `obj` is an
+// lvalue, the functor will hold a reference to it. If `obj` is an rvalue, the functor will
+// contain a copy (by move) of it.
+
+} // namespace kj
+
+#endif // KJ_FUNCTION_H_
diff --git a/c++/src/kj/main.c++ b/c++/src/kj/main.c++
new file mode 100644
index 0000000..8707b53
--- /dev/null
+++ b/c++/src/kj/main.c++
@@ -0,0 +1,685 @@
+// Copyright (c) 2013, Kenton Varda <[email protected]>
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice, this
+// list of conditions and the following disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+// this list of conditions and the following disclaimer in the documentation
+// and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#include "main.h"
+#include "debug.h"
+#include "arena.h"
+#include <map>
+#include <set>
+#include <stdlib.h>
+#include <unistd.h>
+#include <errno.h>
+#include <limits.h>
+
+namespace kj {
+
+// =======================================================================================
+
+TopLevelProcessContext::TopLevelProcessContext(StringPtr programName)
+ : programName(programName),
+ cleanShutdown(getenv("KJ_CLEAN_SHUTDOWN") != nullptr) {}
+
+StringPtr TopLevelProcessContext::getProgramName() {
+ return programName;
+}
+
+void TopLevelProcessContext::exit() {
+ int exitCode = hadErrors ? 1 : 0;
+ if (cleanShutdown) {
+#if KJ_NO_EXCEPTIONS
+ // This is the best we can do.
+ warning("warning: KJ_CLEAN_SHUTDOWN may not work correctly when compiled "
+ "with -fno-exceptions.");
+ ::exit(exitCode);
+#else
+ throw CleanShutdownException { exitCode };
+#endif
+ }
+ quick_exit(exitCode);
+}
+
+void TopLevelProcessContext::warning(StringPtr message) {
+ const char* pos = message.begin();
+
+ while (pos < message.end()) {
+ ssize_t n = write(STDERR_FILENO, pos, message.end() - pos);
+ if (n < 0) {
+ if (errno == EINTR) {
+ continue;
+ }
+ // Apparently we can't write to stderr. Dunno what to do.
+ return;
+ }
+ pos += n;
+ }
+ if (message.size() > 0 && message[message.size() - 1] != '\n') {
+ write(STDERR_FILENO, "\n", 1);
+ }
+}
+
+void TopLevelProcessContext::error(StringPtr message) {
+ hadErrors = true;
+ warning(message);
+}
+
+void TopLevelProcessContext::exitError(StringPtr message) {
+ error(message);
+ exit();
+}
+
+void TopLevelProcessContext::exitInfo(StringPtr message) {
+ const char* pos = message.begin();
+
+ while (pos < message.end()) {
+ ssize_t n;
+ KJ_SYSCALL(n = write(STDOUT_FILENO, pos, message.end() - pos));
+ pos += n;
+ }
+ if (message.size() > 0 && message[message.size() - 1] != '\n') {
+ write(STDOUT_FILENO, "\n", 1);
+ }
+
+ exit();
+}
+
+void TopLevelProcessContext::increaseLoggingVerbosity() {
+ // At the moment, there is only one log level that isn't enabled by default.
+ _::Debug::setLogLevel(_::Debug::Severity::INFO);
+}
+
+// =======================================================================================
+
+int runMainAndExit(ProcessContext& context, MainFunc&& func, int argc, char* argv[]) {
+#if !KJ_NO_EXCEPTIONS
+ try {
+#endif
+ KJ_ASSERT(argc > 0);
+
+ KJ_STACK_ARRAY(StringPtr, params, argc - 1, 8, 32);
+ for (int i = 1; i < argc; i++) {
+ params[i - 1] = argv[i];
+ }
+
+ KJ_IF_MAYBE(exception, runCatchingExceptions([&]() {
+ func(argv[0], params);
+ })) {
+ context.error(str(exception));
+ }
+ context.exit();
+#if !KJ_NO_EXCEPTIONS
+ } catch (const TopLevelProcessContext::CleanShutdownException& e) {
+ return e.exitCode;
+ }
+#endif
+}
+
+// =======================================================================================
+
+struct MainBuilder::Impl {
+ inline Impl(ProcessContext& context, StringPtr version,
+ StringPtr briefDescription, StringPtr extendedDescription)
+ : context(context), version(version),
+ briefDescription(briefDescription), extendedDescription(extendedDescription) {}
+
+ ProcessContext& context;
+ StringPtr version;
+ StringPtr briefDescription;
+ StringPtr extendedDescription;
+
+ Arena arena;
+
+ struct CharArrayCompare {
+ inline bool operator()(const ArrayPtr<const char>& a, const ArrayPtr<const char>& b) const {
+ int cmp = memcmp(a.begin(), b.begin(), min(a.size(), b.size()));
+ if (cmp == 0) {
+ return a.size() < b.size();
+ } else {
+ return cmp < 0;
+ }
+ }
+ };
+
+ struct Option {
+ ArrayPtr<OptionName> names;
+ bool hasArg;
+ union {
+ Function<Validity()>* func;
+ Function<Validity(StringPtr)>* funcWithArg;
+ };
+ StringPtr argTitle;
+ StringPtr helpText;
+ };
+
+ class OptionDisplayOrder;
+
+ std::map<char, Option*> shortOptions;
+ std::map<ArrayPtr<const char>, Option*, CharArrayCompare> longOptions;
+
+ struct SubCommand {
+ Function<MainFunc()> func;
+ StringPtr helpText;
+ };
+ std::map<StringPtr, SubCommand> subCommands;
+
+ struct Arg {
+ StringPtr title;
+ Function<Validity(StringPtr)> callback;
+ uint minCount;
+ uint maxCount;
+ };
+
+ Vector<Arg> args;
+
+ Maybe<Function<Validity()>> finalCallback;
+
+ Option& addOption(std::initializer_list<OptionName> names, bool hasArg, StringPtr helpText) {
+ KJ_REQUIRE(names.size() > 0, "option must have at least one name");
+
+ Option& option = arena.allocate<Option>();
+ option.names = arena.allocateArray<OptionName>(names.size());
+ uint i = 0;
+ for (auto& name: names) {
+ option.names[i++] = name;
+ if (name.isLong) {
+ KJ_REQUIRE(
+ longOptions.insert(std::make_pair(StringPtr(name.longName).asArray(), &option)).second,
+ "duplicate option", name.longName);
+ } else {
+ KJ_REQUIRE(
+ shortOptions.insert(std::make_pair(name.shortName, &option)).second,
+ "duplicate option", name.shortName);
+ }
+ }
+ option.hasArg = hasArg;
+ option.helpText = helpText;
+ return option;
+ }
+
+ Validity printVersion() {
+ context.exitInfo(version);
+ return true;
+ }
+
+ Validity increaseVerbosity() {
+ context.increaseLoggingVerbosity();
+ return true;
+ }
+};
+
+MainBuilder::MainBuilder(ProcessContext& context, StringPtr version,
+ StringPtr briefDescription, StringPtr extendedDescription)
+ : impl(heap<Impl>(context, version, briefDescription, extendedDescription)) {
+ addOption({"verbose"}, KJ_BIND_METHOD(*impl, increaseVerbosity),
+ "Log informational messages to stderr; useful for debugging.");
+ addOption({"version"}, KJ_BIND_METHOD(*impl, printVersion),
+ "Print version information and exit.");
+}
+
+MainBuilder::~MainBuilder() noexcept(false) {}
+
+MainBuilder& MainBuilder::addOption(std::initializer_list<OptionName> names,
+ Function<Validity()> callback,
+ StringPtr helpText) {
+ impl->addOption(names, false, helpText).func = &impl->arena.copy(kj::mv(callback));
+ return *this;
+}
+
+MainBuilder& MainBuilder::addOptionWithArg(std::initializer_list<OptionName> names,
+ Function<Validity(StringPtr)> callback,
+ StringPtr argumentTitle, StringPtr helpText) {
+ auto& opt = impl->addOption(names, true, helpText);
+ opt.funcWithArg = &impl->arena.copy(kj::mv(callback));
+ opt.argTitle = argumentTitle;
+ return *this;
+}
+
+MainBuilder& MainBuilder::addSubCommand(StringPtr name, Function<MainFunc()> getSubParser,
+ StringPtr helpText) {
+ KJ_REQUIRE(impl->args.size() == 0, "cannot have sub-commands when expecting arguments");
+ KJ_REQUIRE(impl->finalCallback == nullptr,
+ "cannot have a final callback when accepting sub-commands");
+ KJ_REQUIRE(
+ impl->subCommands.insert(std::make_pair(
+ name, Impl::SubCommand { kj::mv(getSubParser), helpText })).second,
+ "duplicate sub-command", name);
+ return *this;
+}
+
+MainBuilder& MainBuilder::expectArg(StringPtr title, Function<Validity(StringPtr)> callback) {
+ KJ_REQUIRE(impl->subCommands.empty(), "cannot have sub-commands when expecting arguments");
+ impl->args.add(Impl::Arg { title, kj::mv(callback), 1, 1 });
+ return *this;
+}
+MainBuilder& MainBuilder::expectOptionalArg(
+ StringPtr title, Function<Validity(StringPtr)> callback) {
+ KJ_REQUIRE(impl->subCommands.empty(), "cannot have sub-commands when expecting arguments");
+ impl->args.add(Impl::Arg { title, kj::mv(callback), 0, 1 });
+ return *this;
+}
+MainBuilder& MainBuilder::expectZeroOrMoreArgs(
+ StringPtr title, Function<Validity(StringPtr)> callback) {
+ KJ_REQUIRE(impl->subCommands.empty(), "cannot have sub-commands when expecting arguments");
+ impl->args.add(Impl::Arg { title, kj::mv(callback), 0, UINT_MAX });
+ return *this;
+}
+MainBuilder& MainBuilder::expectOneOrMoreArgs(
+ StringPtr title, Function<Validity(StringPtr)> callback) {
+ KJ_REQUIRE(impl->subCommands.empty(), "cannot have sub-commands when expecting arguments");
+ impl->args.add(Impl::Arg { title, kj::mv(callback), 1, UINT_MAX });
+ return *this;
+}
+
+MainBuilder& MainBuilder::callAfterParsing(Function<Validity()> callback) {
+ KJ_REQUIRE(impl->finalCallback == nullptr, "callAfterParsing() can only be called once");
+ KJ_REQUIRE(impl->subCommands.empty(), "cannot have a final callback when accepting sub-commands");
+ impl->finalCallback = kj::mv(callback);
+ return *this;
+}
+
+class MainBuilder::MainImpl {
+public:
+ MainImpl(Own<Impl>&& impl): impl(kj::mv(impl)) {}
+
+ void operator()(StringPtr programName, ArrayPtr<const StringPtr> params);
+
+private:
+ Own<Impl> impl;
+
+ void usageError(StringPtr programName, StringPtr message) KJ_NORETURN;
+ void printHelp(StringPtr programName) KJ_NORETURN;
+ void wrapText(Vector<char>& output, StringPtr indent, StringPtr text);
+};
+
+MainFunc MainBuilder::build() {
+ return MainImpl(kj::mv(impl));
+}
+
+void MainBuilder::MainImpl::operator()(StringPtr programName, ArrayPtr<const StringPtr> params) {
+ Vector<StringPtr> arguments;
+
+ for (size_t i = 0; i < params.size(); i++) {
+ StringPtr param = params[i];
+ if (param == "--") {
+ // "--" ends option parsing.
+ arguments.addAll(params.begin() + i + 1, params.end());
+ break;
+ } else if (param.startsWith("--")) {
+ // Long option.
+ ArrayPtr<const char> name;
+ Maybe<StringPtr> maybeArg;
+ KJ_IF_MAYBE(pos, param.findFirst('=')) {
+ name = param.slice(2, *pos);
+ maybeArg = param.slice(*pos + 1);
+ } else {
+ name = param.slice(2);
+ }
+ auto iter = impl->longOptions.find(name);
+ if (iter == impl->longOptions.end()) {
+ if (param == "--help") {
+ printHelp(programName);
+ } else {
+ usageError(programName, str("--", name, ": unrecognized option"));
+ }
+ } else {
+ const Impl::Option& option = *iter->second;
+ if (option.hasArg) {
+ // Argument expected.
+ KJ_IF_MAYBE(arg, maybeArg) {
+ // "--foo=blah": "blah" is the argument.
+ KJ_IF_MAYBE(error, (*option.funcWithArg)(*arg).releaseError()) {
+ usageError(programName, str(param, ": ", *error));
+ }
+ } else if (i + 1 < params.size() && !params[i + 1].startsWith("-")) {
+ // "--foo blah": "blah" is the argument.
+ ++i;
+ KJ_IF_MAYBE(error, (*option.funcWithArg)(params[i]).releaseError()) {
+ usageError(programName, str(param, "=", params[i], ": ", *error));
+ }
+ } else {
+ usageError(programName, str("--", name, ": missing argument"));
+ }
+ } else {
+ // No argument expected.
+ if (maybeArg == nullptr) {
+ KJ_IF_MAYBE(error, (*option.func)().releaseError()) {
+ usageError(programName, str(param, ": ", *error));
+ }
+ } else {
+ usageError(programName, str("--", name, ": option does not accept an argument"));
+ }
+ }
+ }
+ } else if (param.startsWith("-")) {
+ // Short option(s).
+ for (uint j = 1; j < param.size(); j++) {
+ char c = param[j];
+ auto iter = impl->shortOptions.find(c);
+ if (iter == impl->shortOptions.end()) {
+ usageError(programName, str("-", c, ": unrecognized option"));
+ } else {
+ const Impl::Option& option = *iter->second;
+ if (option.hasArg) {
+ // Argument expected.
+ if (j + 1 < params.size()) {
+ // Rest of flag is argument.
+ StringPtr arg = param.slice(j + 1);
+ KJ_IF_MAYBE(error, (*option.funcWithArg)(arg).releaseError()) {
+ usageError(programName, str("-", c, " ", arg, ": ", *error));
+ }
+ break;
+ } else if (i + 1 < params.size() && !params[i + 1].startsWith("-")) {
+ // Next parameter is argument.
+ ++i;
+ KJ_IF_MAYBE(error, (*option.funcWithArg)(params[i]).releaseError()) {
+ usageError(programName, str("-", c, " ", params[i], ": ", *error));
+ }
+ break;
+ } else {
+ usageError(programName, str("-", c, ": missing argument"));
+ }
+ } else {
+ // No argument expected.
+ KJ_IF_MAYBE(error, (*option.func)().releaseError()) {
+ usageError(programName, str("-", c, ": ", *error));
+ }
+ }
+ }
+ }
+ } else if (!impl->subCommands.empty()) {
+ // A sub-command name.
+ auto iter = impl->subCommands.find(param);
+ if (iter == impl->subCommands.end()) {
+ MainFunc subMain = iter->second.func();
+ subMain(str(programName, ' ', param), params.slice(i + 1, params.size()));
+ return;
+ } else if (param == "help") {
+ if (i + 1 < params.size()) {
+ iter = impl->subCommands.find(params[i + 1]);
+ if (iter == impl->subCommands.end()) {
+ usageError(programName, str(params[i + 1], ": unknown command"));
+ } else {
+ // Run the sub-command with "--help" as the argument.
+ MainFunc subMain = iter->second.func();
+ StringPtr dummyArg = "--help";
+ subMain(str(programName, ' ', params[i + 1]), arrayPtr(&dummyArg, 1));
+ return;
+ }
+ } else {
+ printHelp(programName);
+ }
+ } else {
+ // Arguments are not accepted, so this is an error.
+ usageError(programName, str(param, ": unknown command"));
+ }
+ } else {
+ // Just a regular argument.
+ arguments.add(param);
+ }
+ }
+
+ // ------------------------------------
+ // Handle arguments.
+ // ------------------------------------
+
+ // Count the number of required arguments, so that we know how to distribute the optional args.
+ uint requiredArgCount = 0;
+ for (auto& argSpec: impl->args) {
+ requiredArgCount += argSpec.minCount;
+ }
+
+ // Now go through each argument spec and consume arguments with it.
+ StringPtr* argPos = arguments.begin();
+ for (auto& argSpec: impl->args) {
+ uint i = 0;
+ for (; i < argSpec.minCount; i++) {
+ if (argPos == arguments.end()) {
+ usageError(programName, str("missing argument <", argSpec.title, '>'));
+ } else {
+ KJ_IF_MAYBE(error, argSpec.callback(*argPos).releaseError()) {
+ usageError(programName, str(*argPos, ": ", *error));
+ }
+ ++argPos;
+ --requiredArgCount;
+ }
+ }
+
+ // If we have more arguments than we need, and this argument spec will accept extras, give
+ // them to it.
+ for (; i < argSpec.maxCount && arguments.end() - argPos > requiredArgCount; ++i) {
+ KJ_IF_MAYBE(error, argSpec.callback(*argPos).releaseError()) {
+ usageError(programName, str(*argPos, ": ", *error));
+ }
+ ++argPos;
+ }
+ }
+
+ // Did we consume all the arguments?
+ while (argPos < arguments.end()) {
+ usageError(programName, str(*argPos++, ": too many arguments"));
+ }
+
+ // Run the final callback, if any.
+ KJ_IF_MAYBE(f, impl->finalCallback) {
+ KJ_IF_MAYBE(error, (*f)().releaseError()) {
+ usageError(programName, *error);
+ }
+ }
+}
+
+void MainBuilder::MainImpl::usageError(StringPtr programName, StringPtr message) {
+ impl->context.exitError(kj::str(
+ programName, ": ", message,
+ "\nTry '", programName, " --help' for more information."));
+}
+
+class MainBuilder::Impl::OptionDisplayOrder {
+public:
+ bool operator()(const Option* a, const Option* b) {
+ if (a == b) return false;
+
+ char aShort = '\0';
+ char bShort = '\0';
+
+ for (auto& name: a->names) {
+ if (name.isLong) {
+ if (aShort == '\0') {
+ aShort = name.longName[0];
+ }
+ } else {
+ aShort = name.shortName;
+ break;
+ }
+ }
+ for (auto& name: b->names) {
+ if (name.isLong) {
+ if (bShort == '\0') {
+ bShort = name.longName[0];
+ }
+ } else {
+ bShort = name.shortName;
+ break;
+ }
+ }
+
+ if (aShort < bShort) return true;
+ if (aShort > bShort) return false;
+
+ StringPtr aLong;
+ StringPtr bLong;
+
+ for (auto& name: a->names) {
+ if (name.isLong) {
+ aLong = name.longName;
+ break;
+ }
+ }
+ for (auto& name: b->names) {
+ if (name.isLong) {
+ bLong = name.longName;
+ break;
+ }
+ }
+
+ return aLong < bLong;
+ }
+};
+
+void MainBuilder::MainImpl::printHelp(StringPtr programName) {
+ Vector<char> text(1024);
+
+ std::set<const Impl::Option*, Impl::OptionDisplayOrder> sortedOptions;
+
+ for (auto& entry: impl->shortOptions) {
+ sortedOptions.insert(entry.second);
+ }
+ for (auto& entry: impl->longOptions) {
+ sortedOptions.insert(entry.second);
+ }
+
+ text.addAll(str("Usage: ", programName, sortedOptions.empty() ? "" : " [<option>...]"));
+
+ if (impl->subCommands.empty()) {
+ for (auto& arg: impl->args) {
+ text.add(' ');
+ if (arg.minCount == 0) {
+ text.addAll(str("[<", arg.title, arg.maxCount > 1 ? ">...]" : ">]"));
+ } else {
+ text.addAll(str('<', arg.title, arg.maxCount > 1 ? ">..." : ">"));
+ }
+ }
+ } else {
+ text.addAll(StringPtr(" <command> [<arg>...]"));
+ }
+ text.addAll(StringPtr("\n\n"));
+
+ wrapText(text, "", impl->briefDescription);
+
+ if (!impl->subCommands.empty()) {
+ text.addAll(StringPtr("\nCommands:\n"));
+ size_t maxLen = 0;
+ for (auto& command: impl->subCommands) {
+ maxLen = kj::max(maxLen, command.first.size());
+ }
+ for (auto& command: impl->subCommands) {
+ text.addAll(StringPtr(" "));
+ text.addAll(command.first);
+ for (size_t i = command.first.size(); i < maxLen; i++) {
+ text.add(' ');
+ }
+ text.addAll(StringPtr(" "));
+ text.addAll(command.second.helpText);
+ text.add('\n');
+ }
+ text.addAll(str(
+ "\nSee '", programName, " help <command>' for more information on a specific command.\n"));
+ }
+
+ if (!sortedOptions.empty()) {
+ text.addAll(StringPtr("\nOptions:\n"));
+
+ for (auto opt: sortedOptions) {
+ text.addAll(StringPtr(" "));
+ bool isFirst = true;
+ for (auto& name: opt->names) {
+ if (isFirst) {
+ isFirst = false;
+ } else {
+ text.addAll(StringPtr(", "));
+ }
+ if (name.isLong) {
+ text.addAll(str("--", name.longName));
+ if (opt->hasArg) {
+ text.addAll(str("=<", opt->argTitle, '>'));
+ }
+ } else {
+ text.addAll(str("-", name.shortName));
+ if (opt->hasArg) {
+ text.addAll(str('<', opt->argTitle, '>'));
+ }
+ }
+ }
+ text.add('\n');
+ wrapText(text, " ", opt->helpText);
+ }
+
+ text.addAll(StringPtr(" --help\n Display this help text and exit.\n"));
+ }
+
+ if (impl->extendedDescription.size() > 0) {
+ text.add('\n');
+ wrapText(text, "", impl->extendedDescription);
+ }
+
+ text.add('\0');
+ impl->context.exitInfo(String(text.releaseAsArray()));
+}
+
+void MainBuilder::MainImpl::wrapText(Vector<char>& output, StringPtr indent, StringPtr text) {
+ uint width = 80 - indent.size();
+
+ while (text.size() > 0) {
+ output.addAll(indent);
+
+ KJ_IF_MAYBE(lineEnd, text.findFirst('\n')) {
+ if (*lineEnd <= width) {
+ output.addAll(text.slice(0, *lineEnd + 1));
+ text = text.slice(*lineEnd + 1);
+ continue;
+ }
+ }
+
+ if (text.size() <= width) {
+ output.addAll(text);
+ output.add('\n');
+ break;
+ }
+
+ uint wrapPos = width;
+ for (;; wrapPos--) {
+ if (wrapPos == 0) {
+ // Hmm, no good place to break words. Just break in the middle.
+ wrapPos = width;
+ break;
+ } else if (text[wrapPos] == ' ' && text[wrapPos - 1] != ' ') {
+ // This position is a space and is preceded by a non-space. Wrap here.
+ break;
+ }
+ }
+
+ output.addAll(text.slice(0, wrapPos));
+ output.add('\n');
+
+ // Skip spaces after the text that was printed.
+ while (text[wrapPos] == ' ') {
+ ++wrapPos;
+ }
+ if (text[wrapPos] == '\n') {
+ // Huh, apparently there were a whole bunch of spaces at the end of the line followed by a
+ // newline. Skip the newline as well so we don't print a blank line.
+ ++wrapPos;
+ }
+ text = text.slice(wrapPos);
+ }
+}
+
+} // namespace kj
diff --git a/c++/src/kj/main.h b/c++/src/kj/main.h
new file mode 100644
index 0000000..2702b14
--- /dev/null
+++ b/c++/src/kj/main.h
@@ -0,0 +1,346 @@
+// Copyright (c) 2013, Kenton Varda <[email protected]>
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice, this
+// list of conditions and the following disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+// this list of conditions and the following disclaimer in the documentation
+// and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#ifndef KJ_MAIN_H_
+#define KJ_MAIN_H_
+
+#include "array.h"
+#include "string.h"
+#include "vector.h"
+#include "function.h"
+
+namespace kj {
+
+class ProcessContext {
+ // Context for command-line programs.
+
+public:
+ virtual StringPtr getProgramName() = 0;
+ // Get argv[0] as passed to main().
+
+ virtual void exit() KJ_NORETURN = 0;
+ // Indicates program completion. The program is considered successful unless `error()` was
+ // called. Typically this exits with quick_exit(), meaning that the stack is not unwound, buffers
+ // are not flushed, etc. -- it is the responsibility of the caller to flush any buffers that
+ // matter. However, an alternate context implementation e.g. for unit testing purposes could
+ // choose to throw an exception instead.
+
+ virtual void warning(StringPtr message) = 0;
+ // Print the given message to standard error. A newline is printed after the message if it
+ // doesn't already have one.
+
+ virtual void error(StringPtr message) = 0;
+ // Like `warning()`, but also sets a flag indicating that the process has failed, and that when
+ // it eventually exits it should indicate an error status.
+
+ virtual void exitError(StringPtr message) KJ_NORETURN = 0;
+ // Equivalent to `error(message)` followed by `exit()`.
+
+ virtual void exitInfo(StringPtr message) KJ_NORETURN = 0;
+ // Displays the given non-error message to the user and then calls `exit()`. This is used to
+ // implement things like --help.
+
+ virtual void increaseLoggingVerbosity() = 0;
+ // Increase the level of detail produced by the debug logging system. `MainBuilder` invokes
+ // this if the caller uses the -v flag.
+
+ // TODO(someday): Add interfaces representing standard OS resources like the filesystem, so that
+ // these things can be mocked out.
+};
+
+class TopLevelProcessContext final: public ProcessContext {
+ // A ProcessContext implementation appropriate for use at the actual entry point of a process
+ // (as opposed to when you are trying to call a program's main function from within some other
+ // program). This implementation writes errors to stderr, and its `exit()` method actually
+ // calls the C `quick_exit()` function.
+
+public:
+ explicit TopLevelProcessContext(StringPtr programName);
+
+ struct CleanShutdownException { int exitCode; };
+ // If the environment variable KJ_CLEAN_SHUTDOWN is set, then exit() will actually throw this
+ // exception rather than exiting. `kj::runMain()` catches this exception and returns normally.
+ // This is useful primarily for testing purposes, to assist tools like memory leak checkers that
+ // are easily confused by quick_exit().
+
+ StringPtr getProgramName() override;
+ void exit() KJ_NORETURN override;
+ void warning(StringPtr message) override;
+ void error(StringPtr message) override;
+ void exitError(StringPtr message) KJ_NORETURN override;
+ void exitInfo(StringPtr message) KJ_NORETURN override;
+ void increaseLoggingVerbosity() override;
+
+private:
+ StringPtr programName;
+ bool cleanShutdown;
+ bool hadErrors = false;
+};
+
+typedef Function<void(StringPtr programName, ArrayPtr<const StringPtr> params)> MainFunc;
+
+int runMainAndExit(ProcessContext& context, MainFunc&& func, int argc, char* argv[]);
+// Runs the given main function and then exits using the given context. If an exception is thrown,
+// this will catch it, report it via the context and exit with an error code.
+//
+// Normally this function does not return, because returning would probably lead to wasting time
+// on cleanup when the process is just going to exit anyway. However, to facilitate memory leak
+// checkers and other tools that require a clean shutdown to do their job, if the environment
+// variable KJ_CLEAN_SHUTDOWN is set, the function will in fact return an exit code, which should
+// then be returned from main().
+//
+// Most users will use the KJ_MAIN() macro rather than call this function directly.
+
+#define KJ_MAIN(MainClass) \
+ int main(int argc, char* argv[]) { \
+ ::kj::TopLevelProcessContext context(argv[0]); \
+ MainClass mainObject(context); \
+ return ::kj::runMainAndExit(context, mainObject.getMain(), argc, argv); \
+ }
+// Convenience macro for declaring a main function based on the given class. The class must have
+// a constructor that accepts a ProcessContext& and a method getMain() which returns
+// kj::MainFunc (probably building it using a MainBuilder).
+
+class MainBuilder {
+ // Builds a main() function with nice argument parsing. As options and arguments are parsed,
+ // corresponding callbacks are called, so that you never have to write a massive switch()
+ // statement to interpret arguments. Additionally, this approach encourages you to write
+ // main classes that have a reasonable API that can be used as an alternative to their
+ // command-line interface.
+ //
+ // All StringPtrs passed to MainBuilder must remain valid until option parsing completes. The
+ // assumption is that these strings will all be literals, making this an easy requirement. If
+ // not, consider allocating them in an Arena.
+ //
+ // Some flags are automatically recognized by the main functions built by this class:
+ // --help: Prints help text and exits. The help text is constructed based on the
+ // information you provide to the builder as you define each flag.
+ // --verbose: Increase logging verbosity.
+ // --version: Print version information and exit.
+ //
+ // Example usage:
+ //
+ // class FooMain {
+ // public:
+ // FooMain(kj::ProcessContext& context): context(context) {}
+ //
+ // bool setAll() { all = true; return true; }
+ // // Enable the --all flag.
+ //
+ // kj::MainBuilder::Validity setOutput(kj::StringPtr name) {
+ // // Set the output file.
+ //
+ // if (name.endsWith(".foo")) {
+ // outputFile = name;
+ // return true;
+ // } else {
+ // return "Output file must have extension .foo.";
+ // }
+ // }
+ //
+ // kj::MainBuilder::Validity processInput(kj::StringPtr name) {
+ // // Process an input file.
+ //
+ // if (!exists(name)) {
+ // return kj::str(name, ": file not found");
+ // }
+ // // ... process the input file ...
+ // return true;
+ // }
+ //
+ // kj::MainFunc getMain() {
+ // return MainBuilder(context, "Foo Builder v1.5", "Reads <source>s and builds a Foo.")
+ // .addOption({'a', "all"}, KJ_BIND_METHOD(*this, setAll),
+ // "Frob all the widgets. Otherwise, only some widgets are frobbed.")
+ // .addOptionWithArg({'o', "output"}, KJ_BIND_METHOD(*this, setOutput),
+ // "filename", "Output to <filename>. Must be a .foo file.")
+ // .expectOneOrMoreArgs("source", KJ_BIND_METHOD(*this, processInput))
+ // .build();
+ // }
+ //
+ // private:
+ // bool all = false;
+ // kj::StringPtr outputFile;
+ // kj::ProcessContext& context;
+ // };
+
+public:
+ MainBuilder(ProcessContext& context, StringPtr version,
+ StringPtr briefDescription, StringPtr extendedDescription = nullptr);
+ ~MainBuilder() noexcept(false);
+
+ class OptionName {
+ public:
+ OptionName() = default;
+ inline constexpr OptionName(char shortName): isLong(false), shortName(shortName) {}
+ inline constexpr OptionName(const char* longName): isLong(true), longName(longName) {}
+
+ private:
+ bool isLong;
+ union {
+ char shortName;
+ const char* longName;
+ };
+ friend class MainBuilder;
+ };
+
+ class Validity {
+ public:
+ inline Validity(bool valid) {
+ if (!valid) errorMessage = heapString("invalid argument");
+ }
+ inline Validity(const char* errorMessage)
+ : errorMessage(heapString(errorMessage)) {}
+ inline Validity(String&& errorMessage)
+ : errorMessage(kj::mv(errorMessage)) {}
+
+ inline const Maybe<String>& getError() const { return errorMessage; }
+ inline Maybe<String> releaseError() { return kj::mv(errorMessage); }
+
+ private:
+ Maybe<String> errorMessage;
+ friend class MainBuilder;
+ };
+
+ MainBuilder& addOption(std::initializer_list<OptionName> names, Function<Validity()> callback,
+ StringPtr helpText);
+ // Defines a new option (flag). `names` is a list of characters and strings that can be used to
+ // specify the option on the command line. Single-character names are used with "-" while string
+ // names are used with "--". `helpText` is a natural-language description of the flag.
+ //
+ // `callback` is called when the option is seen. Its return value indicates whether the option
+ // was accepted. If not, further option processing stops, and error is written, and the process
+ // exits.
+ //
+ // Example:
+ //
+ // builder.addOption({'a', "all"}, KJ_BIND_METHOD(*this, showAll), "Show all files.");
+ //
+ // This option could be specified in the following ways:
+ //
+ // -a
+ // --all
+ //
+ // Note that single-character option names can be combined into a single argument. For example,
+ // `-abcd` is equivalent to `-a -b -c -d`.
+ //
+ // The help text for this option would look like:
+ //
+ // -a, --all
+ // Show all files.
+ //
+ // Note that help text is automatically word-wrapped.
+
+ MainBuilder& addOptionWithArg(std::initializer_list<OptionName> names,
+ Function<Validity(StringPtr)> callback,
+ StringPtr argumentTitle, StringPtr helpText);
+ // Like `addOption()`, but adds an option which accepts an argument. `argumentTitle` is used in
+ // the help text. The argument text is passed to the callback.
+ //
+ // Example:
+ //
+ // builder.addOptionWithArg({'o', "output"}, KJ_BIND_METHOD(*this, setOutput),
+ // "filename", "Output to <filename>.");
+ //
+ // This option could be specified with an argument of "foo" in the following ways:
+ //
+ // -ofoo
+ // -o foo
+ // --output=foo
+ // --output foo
+ //
+ // Note that single-character option names can be combined, but only the last option can have an
+ // argument, since the characters after the option letter are interpreted as the argument. E.g.
+ // `-abofoo` would be equivalent to `-a -b -o foo`.
+ //
+ // The help text for this option would look like:
+ //
+ // -o FILENAME, --output=FILENAME
+ // Output to FILENAME.
+
+ MainBuilder& addSubCommand(StringPtr name, Function<MainFunc()> getSubParser,
+ StringPtr briefHelpText);
+ // If exactly the given name is seen as an argument, invoke getSubParser() and then pass all
+ // remaining arguments to the parser it returns. This is useful for implementing commands which
+ // have lots of sub-commands, like "git" (which has sub-commands "checkout", "branch", "pull",
+ // etc.).
+ //
+ // `getSubParser` is only called if the command is seen. This avoids building main functions
+ // for commands that aren't used.
+ //
+ // `briefHelpText` should be brief enough to show immediately after the command name on a single
+ // line. It will not be wrapped. Users can use the built-in "help" command to get extended
+ // help on a particular command.
+
+ MainBuilder& expectArg(StringPtr title, Function<Validity(StringPtr)> callback);
+ MainBuilder& expectOptionalArg(StringPtr title, Function<Validity(StringPtr)> callback);
+ MainBuilder& expectZeroOrMoreArgs(StringPtr title, Function<Validity(StringPtr)> callback);
+ MainBuilder& expectOneOrMoreArgs(StringPtr title, Function<Validity(StringPtr)> callback);
+ // Set callbacks to handle arguments. `expectArg()` and `expectOptionalArg()` specify positional
+ // arguments with special handling, while `expect{Zero,One}OrMoreArgs()` specifies a handler for
+ // an argument list (the handler is called once for each argument in the list). `title`
+ // specifies how the argument should be represented in the usage text.
+ //
+ // All options callbacks are called before argument callbacks, regardless of their ordering on
+ // the command line. This matches GNU getopt's behavior of permuting non-flag arguments to the
+ // end of the argument list. Also matching getopt, the special option "--" indicates that the
+ // rest of the command line is all arguments, not options, even if they start with '-'.
+ //
+ // The interpretation of positional arguments is fairly flexible. The non-optional arguments can
+ // be expected at the beginning, end, or in the middle. If more arguments are specified than
+ // the number of non-optional args, they are assigned to the optional argument handlers in the
+ // order of registration.
+ //
+ // For example, say you called:
+ // builder.expectArg("foo", ...);
+ // builder.expectOptionalArg("bar", ...);
+ // builder.expectArg("baz", ...);
+ // builder.expectZeroOrMoreArgs("qux", ...);
+ // builder.expectArg("corge", ...);
+ //
+ // This command requires at least three arguments: foo, baz, and corge. If four arguments are
+ // given, the second is assigned to bar. If five or more arguments are specified, then the
+ // arguments between the third and last are assigned to qux. Note that it never makes sense
+ // to call `expect*OrMoreArgs()` more than once since only the first call would ever be used.
+ //
+ // In practice, you probably shouldn't create such complicated commands as in the above example.
+ // But, this flexibility seems necessary to support commands where the first argument is special
+ // as well as commands (like `cp`) where the last argument is special.
+
+ MainBuilder& callAfterParsing(Function<Validity()> callback);
+ // Call the given function after all arguments have been parsed.
+
+ MainFunc build();
+ // Build the "main" function, which simply parses the arguments. Once this returns, the
+ // `MainBuilder` is no longer valid.
+
+private:
+ struct Impl;
+ Own<Impl> impl;
+
+ class MainImpl;
+};
+
+} // namespace kj
+
+#endif // KJ_MAIN_H_
diff --git a/c++/src/kj/string.h b/c++/src/kj/string.h
index 33b8f40..baf7502 100644
--- a/c++/src/kj/string.h
+++ b/c++/src/kj/string.h
@@ -84,6 +84,8 @@
inline bool startsWith(const StringPtr& other) const;
inline bool endsWith(const StringPtr& other) const;
+ inline Maybe<size_t> findFirst(char c) const;
+
private:
inline StringPtr(ArrayPtr<const char> content): content(content) {}
@@ -109,6 +111,8 @@
inline String(decltype(nullptr)): content(nullptr) {}
inline String(char* value, size_t size, const ArrayDisposer& disposer);
// Does not copy. `size` does not include NUL terminator, but `value` must be NUL-terminated.
+ inline explicit String(Array<char> buffer);
+ // Does not copy. Requires `buffer` ends with `\0`.
inline operator ArrayPtr<char>();
inline operator ArrayPtr<const char>() const;
@@ -373,6 +377,15 @@
memcmp(end() - other.size(), other.content.begin(), other.size()) == 0;
}
+inline Maybe<size_t> StringPtr::findFirst(char c) const {
+ const char* pos = reinterpret_cast<const char*>(memchr(content.begin(), c, size()));
+ if (pos == nullptr) {
+ return nullptr;
+ } else {
+ return pos - content.begin();
+ }
+}
+
inline String::operator ArrayPtr<char>() {
return content == nullptr ? ArrayPtr<char>(nullptr) : content.slice(0, content.size() - 1);
}
@@ -404,6 +417,10 @@
KJ_IREQUIRE(value[size] == '\0', "String must be NUL-terminated.");
}
+inline String::String(Array<char> buffer): content(kj::mv(buffer)) {
+ KJ_IREQUIRE(content.size() > 0 && content.back() == '\0', "String must be NUL-terminated.");
+}
+
inline String heapString(const char* value) {
return heapString(value, strlen(value));
}
diff --git a/c++/src/kj/vector.h b/c++/src/kj/vector.h
index 76549a9..3f7db56 100644
--- a/c++/src/kj/vector.h
+++ b/c++/src/kj/vector.h
@@ -82,6 +82,11 @@
builder.addAll(begin, end);
}
+ template <typename Container>
+ inline void addAll(Container&& container) {
+ addAll(container.begin(), container.end());
+ }
+
private:
ArrayBuilder<T> builder;
