Merge branch 'integrated-documentation' into staged-0.5

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Builtin documentation for builtin functions display from repl and command line (`musique doc <builtin>`)
+- Man documentation for commandline interface builtin (`musique man`)
+- Suggestions which command line parameters user may wanted to use
+
+### Changed
+
+- New parameter passing convention for command line invocation. `musique help` to learn how it changed
+
 ## [0.4.0]
 
 ### Added

config.mk

@@ -13,7 +13,7 @@ VERSION := $(MAJOR).$(MINOR).$(PATCH)-dev+$(COMMIT)
 
 CXXFLAGS:=$(CXXFLAGS) -std=c++20 -Wall -Wextra -Werror=switch -Werror=return-type -Werror=unused-result
 CPPFLAGS:=$(CPPFLAGS) -DMusique_Version='"$(VERSION)"' \
-	-Ilib/expected/ -I. -Ilib/bestline/ -Ilib/rtmidi/ -Ilib/link/include -Ilib/asio/include/
+	-Ilib/expected/ -I. -Ilib/bestline/ -Ilib/rtmidi/ -Ilib/link/include -Ilib/asio/include/ -Ilib/edit_distance.cc/
 LDFLAGS=-flto
 LDLIBS= -lpthread
 

lib/edit_distance.cc/.gitignore

@@ -0,0 +1,5 @@
+test
+test.cc
+Makefile
+.cache
+compile_commands.json

lib/edit_distance.cc/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023 Robert Bendun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lib/edit_distance.cc/edit_distance.hh

@@ -0,0 +1,76 @@
+// Copyright 2023 Robert Bendun <robert@bendun.cc>
+//
+// Permission is hereby granted, free of charge, to any person obtaining
+// a copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to
+// permit persons to whom the Software is furnished to do so, subject to
+// the following conditions:
+
+// The above copyright notice and this permission notice shall be
+// included in all copies or substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+#include <algorithm>
+#include <array>
+#include <concepts>
+#include <iterator>
+#include <numeric>
+#include <ranges>
+#include <type_traits>
+#include <vector>
+
+template<std::random_access_iterator S, std::random_access_iterator T>
+requires std::equality_comparable_with<
+	std::iter_value_t<S>,
+	std::iter_value_t<T>
+>
+constexpr int edit_distance(S s, unsigned m, T t, unsigned n)
+{
+	std::array<std::vector<int>, 2> memo;
+	auto *v0 = &memo[0];
+	auto *v1 = &memo[1];
+
+	for (auto& v : memo) {
+		v.resize(n+1);
+	}
+	std::iota(v0->begin(), v0->end(), 0);
+
+	for (auto i = 0u; i < m; ++i) {
+		(*v1)[0] = i+1;
+		for (auto j = 0u; j < n; ++j) {
+			auto const deletion_cost = (*v0)[j+1] + 1;
+			auto const insertion_cost = (*v1)[j] + 1;
+			auto const substitution_cost = (*v0)[j] + (s[i] != t[j]);
+
+			(*v1)[j+1] = std::min({ deletion_cost, insertion_cost, substitution_cost });
+		}
+		std::swap(v0, v1);
+	}
+
+	return (*v0)[n];
+}
+
+template<
+	std::ranges::random_access_range Range1,
+	std::ranges::random_access_range Range2
+>
+requires std::equality_comparable_with<
+	std::ranges::range_value_t<Range1>,
+	std::ranges::range_value_t<Range2>
+>
+constexpr int edit_distance(Range1 const& range1, Range2 const& range2)
+{
+	return edit_distance(
+		std::begin(range1), std::ranges::size(range1),
+		std::begin(range2), std::ranges::size(range2)
+	);
+}

musique/cmd.cc

@@ -0,0 +1,474 @@
+#include <algorithm>
+#include <array>
+#include <chrono>
+#include <edit_distance.hh>
+#include <iomanip>
+#include <iostream>
+#include <limits>
+#include <musique/cmd.hh>
+#include <musique/common.hh>
+#include <musique/errors.hh>
+#include <musique/interpreter/builtin_function_documentation.hh>
+#include <musique/pretty.hh>
+#include <set>
+#include <unordered_set>
+#include <utility>
+#include <variant>
+
+// TODO: Command line parameters full documentation in other then man pages format. Maybe HTML generation?
+
+#ifdef _WIN32
+extern "C" {
+#include <io.h>
+}
+#else
+#include <unistd.h>
+#endif
+
+using Empty_Argument    = void(*)();
+using Requires_Argument = void(*)(std::string_view);
+using Defines_Code      = cmd::Run(*)(std::string_view);
+using Parameter         = std::variant<Empty_Argument, Requires_Argument, Defines_Code>;
+
+using namespace cmd;
+
+// from musique/main.cc:
+extern bool enable_repl;
+extern bool ast_only_mode;
+
+static Defines_Code provide_function = [](std::string_view fname) -> cmd::Run {
+	return { .type = Run::Deffered_File, .argument = fname };
+};
+
+static Defines_Code provide_inline_code = [](std::string_view code) -> cmd::Run {
+	return { .type = Run::Argument, .argument = code };
+};
+
+static Defines_Code provide_file = [](std::string_view fname) -> cmd::Run {
+	return { .type = Run::File, .argument = fname };
+};
+
+static Requires_Argument show_docs = [](std::string_view builtin) {
+	if (auto maybe_docs = find_documentation_for_builtin(builtin); maybe_docs) {
+		std::cout << *maybe_docs << std::endl;
+		return;
+	}
+	std::cerr << pretty::begin_error << "musique: error:" << pretty::end;
+	std::cerr << " cannot find documentation for given builtin" << std::endl;
+
+	std::cerr << "Similar ones are:" << std::endl;
+	for (auto similar : similar_names_to_builtin(builtin)) {
+		std::cerr << "  " << similar << '\n';
+	}
+	std::exit(1);
+};
+
+static Empty_Argument set_interactive_mode = [] { enable_repl = true; };
+static Empty_Argument set_ast_only_mode = [] { ast_only_mode = true; };
+
+static Empty_Argument print_version = [] { std::cout << Musique_Version << std::endl; };
+static Empty_Argument print_help = usage;
+
+[[noreturn]]
+static void print_manpage();
+
+struct Entry
+{
+	std::string_view name;
+	Parameter handler;
+	bool internal = false;
+
+	void* handler_ptr() const
+	{
+		return std::visit([](auto p) { return reinterpret_cast<void*>(p); }, handler);
+	}
+
+	size_t arguments() const
+	{
+		return std::visit([]<typename R, typename ...A>(R(*)(A...)) { return sizeof...(A); }, handler);
+	}
+};
+
+// First entry for given action type should always be it's cannonical name
+static auto all_parameters = std::array {
+	Entry { "run",  provide_file },
+	Entry { "r",    provide_file },
+	Entry { "exec", provide_file },
+	Entry { "load", provide_file },
+
+	Entry { "fun",      provide_function },
+	Entry { "def",      provide_function },
+	Entry { "f",        provide_function },
+	Entry { "func",     provide_function },
+	Entry { "function", provide_function },
+
+	Entry { "repl",        set_interactive_mode },
+	Entry { "i",           set_interactive_mode },
+	Entry { "interactive", set_interactive_mode },
+
+	Entry { "doc",  show_docs },
+	Entry { "d",    show_docs },
+	Entry { "docs", show_docs },
+
+	Entry { "man", print_manpage },
+
+	Entry { "inline", provide_inline_code },
+	Entry { "c",      provide_inline_code },
+	Entry { "code",   provide_inline_code },
+
+	Entry { "help", print_help },
+	Entry { "?",    print_help },
+	Entry { "/?",   print_help },
+	Entry { "h",    print_help },
+
+	Entry { "version", print_version },
+	Entry { "v",       print_version },
+
+	Entry {
+		.name     = "ast",
+		.handler  = set_ast_only_mode,
+		.internal = true,
+	},
+};
+
+struct Documentation_For_Handler_Entry
+{
+	void *handler;
+	std::string_view short_documentation{};
+	std::string_view long_documentation{};
+};
+
+static auto documentation_for_handler = std::array {
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(provide_function),
+		.short_documentation = "load file as function",
+		.long_documentation =
+			"Loads given file, placing it inside a function. The main use for this mechanism is\n"
+			"to delay execution of a file e.g. to play it using synchronization infrastructure.\n"
+			"Name of function is derived from file name, replacing special characters with underscores.\n"
+			"New name is reported when entering interactive mode."
+	},
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(provide_file),
+		.short_documentation = "execute given file",
+		.long_documentation =
+			"Run provided Musique source file."
+	},
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(set_interactive_mode),
+		.short_documentation = "enable interactive mode",
+		.long_documentation =
+			"Enables interactive mode. It's enabled by default when provided without arguments or\n"
+			"when all arguments are files loaded as functions."
+	},
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(print_help),
+		.short_documentation = "print help",
+		.long_documentation =
+			"Prints short version of help, to provide version easy for quick lookup by the user."
+	},
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(print_version),
+		.short_documentation = "print version information",
+		.long_documentation =
+			"Prints version of Musique, following Semantic Versioning.\n"
+			"It's either '<major>.<minor>.<patch>' for official releases or\n"
+			"'<major>.<minor>.<patch>-dev+gc<commit hash>' for self-build releases."
+	},
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(show_docs),
+		.short_documentation = "print documentation for given builtin",
+		.long_documentation =
+			"Prints documentation for given builtin function (function predefined by language).\n"
+			"Documentation is in Markdown format and can be passed to render."
+	},
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(provide_inline_code),
+		.short_documentation = "run code from an argument",
+		.long_documentation =
+			"Runs code passed as next argument. Same rules apply as for code inside a file."
+	},
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(set_ast_only_mode),
+		.short_documentation = "don't run code, print AST of it",
+		.long_documentation =
+			"Parameter made for internal usage. Instead of executing provided code,\n"
+			"prints program syntax tree."
+	},
+	Documentation_For_Handler_Entry {
+		.handler = reinterpret_cast<void*>(print_manpage),
+		.short_documentation = "print man page source code to standard output",
+		.long_documentation =
+			"Prints Man page document to standard output of Musique full command line interface.\n"
+			"One can view it with 'musique man > /tmp/musique.1; man /tmp/musique.1'"
+	},
+};
+
+// Supported types of argument input:
+// With arity = 0
+//   -i -j -k ≡ --i --j --k ≡ i j k
+// With arity = 1
+//   -i 1 -j 2 ≡ --i 1 --j 2 ≡ i 1 j 2 ≡ --i=1 --j=2
+// Arity ≥ 2 is not supported
+std::optional<std::string_view> cmd::accept_commandline_argument(std::vector<cmd::Run> &runnables, std::span<char const*> &args)
+{
+	if (args.empty()) {
+		return std::nullopt;
+	}
+
+	// This struct when function returns automatically ajust number of arguments used
+	struct Fix_Args_Array
+	{
+		std::string_view name() const { return m_name; }
+
+		std::optional<std::string_view> value() const
+		{
+			if (m_has_value) { m_success = m_value_consumed = true; return m_value; }
+			return std::nullopt;
+		}
+
+		void mark_success() { m_success = true; }
+
+		~Fix_Args_Array() { args = args.subspan(int(m_success) + (!m_packed * int(m_value_consumed))); }
+
+		std::span<char const*> &args;
+		std::string_view m_name = {};
+		std::string_view m_value = {};
+		bool m_has_value = false;
+		bool m_packed = false;
+		mutable bool m_success = false;
+		mutable bool m_value_consumed = false;
+	} state { .args = args };
+
+	std::string_view s = args.front();
+	if (s.starts_with("--")) s.remove_prefix(2);
+	if (s.starts_with('-'))  s.remove_prefix(1);
+
+	state.m_name = s;
+
+	if (auto p = s.find('='); p != std::string_view::npos) {
+		state.m_name = s.substr(0, p);
+		state.m_value = s.substr(p+1);
+		state.m_has_value = true;
+		state.m_packed = true;
+	} else if (args.size() >= 2) {
+		state.m_has_value = true;
+		state.m_value = args[1];
+	}
+
+	for (auto const& p : all_parameters) {
+		if (p.name != state.name()) {
+			continue;
+		}
+		std::visit(Overloaded {
+			[&state](Empty_Argument const& h) {
+				state.mark_success();
+				h();
+			},
+			[&state, p](Requires_Argument const& h) {
+				auto arg = state.value();
+				if (!arg) {
+					std::cerr << pretty::begin_error << "musique: error:" << pretty::end;
+					std::cerr << " option " << std::quoted(p.name) << " requires an argument" << std::endl;
+					std::exit(1);
+				}
+				h(*arg);
+			},
+			[&state, &runnables, p](Defines_Code const& h) {
+				auto arg = state.value();
+				if (!arg) {
+					std::cerr << pretty::begin_error << "musique: error:" << pretty::end;
+					std::cerr << " option " << std::quoted(p.name) << " requires an argument" << std::endl;
+					std::exit(1);
+				}
+				runnables.push_back(h(*arg));
+			}
+		}, p.handler);
+		return std::nullopt;
+	}
+
+	return state.name();
+}
+
+Documentation_For_Handler_Entry find_documentation_for_handler(void *handler)
+{
+	auto it = std::find_if(documentation_for_handler.begin(), documentation_for_handler.end(),
+		[=](Documentation_For_Handler_Entry const& e) { return e.handler == handler; });
+
+	ensure(it != documentation_for_handler.end(), "Parameter handler doesn't have matching documentation");
+	return *it;
+}
+
+Documentation_For_Handler_Entry find_documentation_for_parameter(std::string_view param)
+{
+	auto entry = std::find_if(all_parameters.begin(), all_parameters.end(),
+			[=](auto const& e) { return e.name == param; });
+
+	ensure(entry != all_parameters.end(), "Cannot find parameter that maches given name");
+	return find_documentation_for_handler(entry->handler_ptr());
+}
+
+void cmd::print_close_matches(std::string_view arg)
+{
+	auto minimum_distance = std::numeric_limits<int>::max();
+
+	std::array<typename decltype(all_parameters)::value_type, 3> closest;
+
+	std::partial_sort_copy(
+		all_parameters.begin(), all_parameters.end(),
+		closest.begin(), closest.end(),
+		[&minimum_distance, arg](auto const& lhs, auto const& rhs) {
+			auto const lhs_score = edit_distance(arg, lhs.name);
+			auto const rhs_score = edit_distance(arg, rhs.name);
+			minimum_distance = std::min({ minimum_distance, lhs_score, rhs_score });
+			return lhs_score < rhs_score;
+		}
+	);
+
+	std::vector<std::string> shown;
+	if (minimum_distance <= 3) {
+		for (auto const& p : closest) {
+			if (std::find(shown.begin(), shown.end(), std::string(p.name)) == shown.end()) {
+				shown.push_back(std::string(p.name));
+			}
+		}
+	}
+
+	if (shown.empty()) {
+		void *previous = nullptr;
+		std::cout << "Available subcommands are:\n";
+		for (auto const& p : all_parameters) {
+			auto handler_p = p.handler_ptr();
+			if (std::exchange(previous, handler_p) == handler_p || p.internal) {
+				continue;
+			}
+			std::cout << "  " << p.name << " - " << find_documentation_for_handler(handler_p).short_documentation << '\n';
+		}
+	} else {
+		std::cout << "The most similar commands are:\n";
+		for (auto const& name : shown) {
+			std::cout << "  " << name << " - " << find_documentation_for_parameter(name).short_documentation << '\n';
+		}
+	}
+
+	std::cout << "\nInvoke 'musique help' to read more about available commands\n";
+}
+
+static inline void iterate_over_documentation(
+	std::ostream& out,
+	std::string_view Documentation_For_Handler_Entry::* handler,
+	std::string_view prefix,
+	std::ostream&(*first)(std::ostream&, std::string_view name))
+{
+	decltype(std::optional(all_parameters.begin())) previous = std::nullopt;
+
+	for (auto it = all_parameters.begin();; ++it) {
+		if (it != all_parameters.end() && it->internal)
+			continue;
+
+		if (it == all_parameters.end() || (previous && it->handler_ptr() != (*previous)->handler_ptr())) {
+			auto &e = **previous;
+			switch (e.arguments()) {
+			break; case 0: out << '\n';
+			break; case 1: out << " ARG\n";
+			break; default: unreachable();
+			}
+
+			out << prefix << find_documentation_for_handler(e.handler_ptr()).*handler << "\n\n";
+		}
+
+		if (it == all_parameters.end()) {
+			break;
+		}
+
+		if (previous && (**previous).handler_ptr() == it->handler_ptr()) {
+			out << ", " << it->name;
+		} else {
+			first(out, it->name);
+		}
+		previous = it;
+	}
+}
+
+void cmd::usage()
+{
+	std::cerr << "usage: " << pretty::begin_bold << "musique" << pretty::end << " [subcommand]...\n";
+	std::cerr << "  where available subcommands are:\n";
+
+	iterate_over_documentation(std::cerr, &Documentation_For_Handler_Entry::short_documentation, "      ",
+		[](std::ostream& out, std::string_view name) -> std::ostream&
+		{
+			return out << "    " << pretty::begin_bold << name << pretty::end;
+		});
+
+	std::exit(2);
+}
+
+void print_manpage()
+{
+	auto const ymd = std::chrono::year_month_day(
+		std::chrono::floor<std::chrono::days>(
+			std::chrono::system_clock::now()
+		)
+	);
+
+	std::cout << ".TH MUSIQUE 1 "
+		<< int(ymd.year()) << '-'
+		<< std::setfill('0') << std::setw(2) << unsigned(ymd.month()) << '-'
+		<< std::setfill('0') << std::setw(2) << unsigned(ymd.day())
+		<< " Linux Linux\n";
+
+	std::cout << R"troff(.SH NAME
+musique \- interactive, musical programming language
+.SH SYNOPSIS
+.B musique
+[
+SUBCOMMANDS
+]
+.SH DESCRIPTION
+Musique is an interpreted, interactive, musical domain specific programming language
+that allows for algorythmic music composition, live-coding and orchestra performing.
+.SH SUBCOMMANDS
+All subcommands can be expressed in three styles: -i arg -j -k
+.I or
+--i=arg --j --k
+.I or
+i arg j k
+)troff";
+
+	iterate_over_documentation(std::cout, &Documentation_For_Handler_Entry::long_documentation, {},
+		[](std::ostream& out, std::string_view name) -> std::ostream&
+		{
+			return out << ".TP\n" << name;
+		});
+
+	std::cout << R"troff(.SH ENVIROMENT
+.TP
+NO_COLOR
+This enviroment variable overrides standard Musique color behaviour.
+When it's defined, it disables colors and ensures they are not enabled.
+.SH FILES
+.TP
+History file
+History file for interactive mode is kept in XDG_DATA_HOME (or similar on other operating systems).
+.SH EXAMPLES
+.TP
+musique \-c "play (c5 + up 12)"
+Plays all semitones in 5th octave
+.TP
+musique run examples/ode-to-joy.mq
+Play Ode to Joy written as Musique source code in examples/ode-to-joy.mq
+)troff";
+
+	std::exit(0);
+}
+
+bool cmd::is_tty()
+{
+#ifdef _WIN32
+	return _isatty(STDOUT_FILENO);
+#else
+	return isatty(fileno(stdout));
+#endif
+}
+

musique/cmd.hh

@@ -0,0 +1,39 @@
+#ifndef MUSIQUE_CMD_HH
+#define MUSIQUE_CMD_HH
+
+#include <optional>
+#include <span>
+#include <string_view>
+#include <variant>
+#include <vector>
+
+namespace cmd
+{
+	/// Describes all arguments that will be run
+	struct Run
+	{
+		enum Type
+		{
+			File,
+			Argument,
+			Deffered_File
+		} type;
+
+		std::string_view argument;
+	};
+
+	/// Accept and execute next command line argument with its parameters if it has any
+	std::optional<std::string_view> accept_commandline_argument(std::vector<cmd::Run> &runnables, std::span<char const*> &args);
+
+	/// Print all arguments that are similar to one provided
+	void print_close_matches(std::string_view arg);
+
+	/// Recognize if stdout is connected to terminal
+	bool is_tty();
+
+	[[noreturn]]
+	void usage();
+}
+
+#endif // MUSIQUE_CMD_HH
+

musique/interpreter/builtin_function_documentation.hh

@@ -0,0 +1,14 @@
+#ifndef MUSIQUE_BUILTIN_FUNCTION_DOCUMENTATION_HH
+#define MUSIQUE_BUILTIN_FUNCTION_DOCUMENTATION_HH
+
+#include <optional>
+#include <string_view>
+#include <vector>
+
+std::optional<std::string_view> find_documentation_for_builtin(std::string_view builtin_name);
+
+
+/// Returns top 4 similar names to required
+std::vector<std::string_view> similar_names_to_builtin(std::string_view builtin_name);
+
+#endif

musique/main.cc

@@ -1,13 +1,13 @@
 #include <charconv>
+#include <cstdio>
+#include <cstring>
+#include <edit_distance.hh>
 #include <filesystem>
 #include <fstream>
 #include <iostream>
-#include <span>
-#include <thread>
-#include <cstring>
-#include <cstdio>
-
+#include <musique/cmd.hh>
 #include <musique/format.hh>
+#include <musique/interpreter/builtin_function_documentation.hh>
 #include <musique/interpreter/env.hh>
 #include <musique/interpreter/interpreter.hh>
 #include <musique/lexer/lines.hh>
@@ -17,13 +17,11 @@
 #include <musique/try.hh>
 #include <musique/unicode.hh>
 #include <musique/value/block.hh>
+#include <span>
+#include <thread>
+#include <unordered_set>
 
-#ifdef _WIN32
-extern "C" {
-#include <io.h>
-}
-#else
-#include <unistd.h>
+#ifndef _WIN32
 extern "C" {
 #include <bestline.h>
 }
@@ -31,66 +29,12 @@ extern "C" {
 
 namespace fs = std::filesystem;
 
-static bool quiet_mode = false;
-static bool ast_only_mode = false;
-static bool enable_repl = false;
+bool ast_only_mode = false;
+bool enable_repl = false;
 static unsigned repl_line_number = 1;
 
 #define Ignore(Call) do { auto const ignore_ ## __LINE__ = (Call); (void) ignore_ ## __LINE__; } while(0)
 
-/// Pop string from front of an array
-template<typename T = std::string_view>
-static T pop(std::span<char const*> &span)
-{
-	auto element = span.front();
-	span = span.subspan(1);
-
-	if constexpr (std::is_same_v<T, std::string_view>) {
-		return element;
-	} else if constexpr (std::is_arithmetic_v<T>) {
-		T result;
-		auto end = element + std::strlen(element);
-		auto [ptr, ec] = std::from_chars(element, end, result);
-		if (ec != decltype(ec){}) {
-			std::cout << "Expected natural number as argument" << std::endl;
-			std::exit(1);
-		}
-		return result;
-	} else {
-		static_assert(always_false<T>, "Unsupported type for pop operation");
-	}
-}
-
-/// Print usage and exit
-[[noreturn]] void usage()
-{
-	std::cerr <<
-		"usage: musique <options> [filename]\n"
-		"  where filename is path to file with Musique code that will be executed\n"
-		"  where options are:\n"
-		"    -c,--run CODE\n"
-		"      executes given code\n"
-		"    -I,--interactive,--repl\n"
-		"      enables interactive mode even when another code was passed\n"
-		"\n"
-		"    -f,--as-function FILENAME\n"
-		"      deffer file execution and turn it into a file\n"
-		"\n"
-		"    --ast\n"
-		"      prints ast for given code\n"
-		"\n"
-		"    -v,--version\n"
-		"      prints Musique interpreter version\n"
-		"\n"
-		"Thanks to:\n"
-		"  Sy Brand, https://sybrand.ink/, creator of tl::expected https://github.com/TartanLlama/expected\n"
-		"  Justine Tunney, https://justinetunney.com, creator of bestline readline library https://github.com/jart/bestline\n"
-		"  Gary P. Scavone, http://www.music.mcgill.ca/~gary/, creator of rtmidi https://github.com/thestk/rtmidi\n"
-		"  Creators of ableton/link, https://github.com/Ableton/link\n"
-		;
-	std::exit(1);
-}
-
 void print_repl_help()
 {
 	std::cout <<
@@ -245,15 +189,6 @@ void completion(char const* buf, bestlineCompletions *lc)
 }
 #endif
 
-bool is_tty()
-{
-#ifdef _WIN32
-	return _isatty(STDOUT_FILENO);
-#else
-	return isatty(fileno(stdout));
-#endif
-}
-
 /// Handles commands inside REPL session (those starting with ':')
 ///
 /// Returns if one of command matched
@@ -352,84 +287,30 @@ static Result<bool> handle_repl_session_commands(std::string_view input, Runner
 	return false;
 }
 
+
 /// Fancy main that supports Result forwarding on error (Try macro)
 static std::optional<Error> Main(std::span<char const*> args)
 {
-	if (is_tty() && getenv("NO_COLOR") == nullptr) {
+	enable_repl = args.empty();
+
+	if (cmd::is_tty() && getenv("NO_COLOR") == nullptr) {
 		pretty::terminal_mode();
 	}
 
-	/// Describes all arguments that will be run
-	struct Run
-	{
-		enum Type
-		{
-			File,
-			Argument,
-			Deffered_File
-		} type;
-		std::string_view argument;
-	};
+	std::vector<cmd::Run> runnables;
 
-	std::vector<Run> runnables;
 
-	while (not args.empty()) {
-		std::string_view arg = pop(args);
-
-		if (arg == "-" || !arg.starts_with('-')) {
-			runnables.push_back({ .type = Run::File, .argument = std::move(arg) });
-			continue;
-		}
-
-		if (arg == "-c" || arg == "--run") {
-			if (args.empty()) {
-				std::cerr << "musique: error: option " << arg << " requires an argument" << std::endl;
-				std::exit(1);
-			}
-			runnables.push_back({ .type = Run::Argument, .argument = pop(args) });
-			continue;
-		}
-
-		if (arg == "-f" || arg == "--as-function") {
-			if (args.empty()) {
-				std::cerr << "musique: error: option " << arg << " requires an argument" << std::endl;
-				std::exit(1);
-			}
-			runnables.push_back({ .type = Run::Deffered_File, .argument = pop(args) });
-			continue;
-		}
-
-		if (arg == "--quiet" || arg == "-q") {
-			quiet_mode = true;
-			continue;
-		}
-		if (arg == "--ast") {
-			ast_only_mode = true;
-			continue;
-		}
-
-		if (arg == "--repl" || arg == "-I" || arg == "--interactive")  {
-			enable_repl = true;
-			continue;
-		}
-
-		if (arg == "--version" || arg == "-v") {
-			std::cout << Musique_Version << std::endl;
-			return {};
-		}
-
-		if (arg == "-h" || arg == "--help") {
-			usage();
-		}
-
-		std::cerr << "musique: error: unrecognized command line option: " << arg << std::endl;
+	while (args.size()) if (auto failed = cmd::accept_commandline_argument(runnables, args)) {
+		std::cerr << pretty::begin_error << "musique: error:" << pretty::end;
+		std::cerr << " Failed to recognize parameter " << std::quoted(*failed) << std::endl;
+		cmd::print_close_matches(args.front());
 		std::exit(1);
 	}
 
 	Runner runner;
 
 	for (auto const& [type, argument] : runnables) {
-		if (type == Run::Argument) {
+		if (type == cmd::Run::Argument) {
 			Lines::the.add_line("<arguments>", argument, repl_line_number);
 			Try(runner.run(argument, "<arguments>"));
 			repl_line_number++;
@@ -440,7 +321,8 @@ static std::optional<Error> Main(std::span<char const*> args)
 			eternal_sources.emplace_back(std::istreambuf_iterator<char>(std::cin), std::istreambuf_iterator<char>());
 		} else {
 			if (not fs::exists(path)) {
-				std::cerr << "musique: error: couldn't open file: " << path << std::endl;
+				std::cerr << pretty::begin_error << "musique: error:" << pretty::end;
+				std::cerr << " couldn't open file: " << path << std::endl;
 				std::exit(1);
 			}
 			std::ifstream source_file{fs::path(path)};
@@ -448,21 +330,18 @@ static std::optional<Error> Main(std::span<char const*> args)
 		}
 
 		Lines::the.add_file(std::string(path), eternal_sources.back());
-		if (type == Run::File) {
+		if (type == cmd::Run::File) {
 			Try(runner.run(eternal_sources.back(), path));
 		} else {
 			Try(runner.deffered_file(eternal_sources.back(), argument));
 		}
 	}
 
-	enable_repl = enable_repl || std::all_of(runnables.begin(), runnables.end(),
-		[](Run const& run) {
-			return run.type == Run::Deffered_File;
-		});
+	enable_repl = enable_repl || (!runnables.empty() && std::all_of(runnables.begin(), runnables.end(),
+		[](cmd::Run const& run) { return run.type == cmd::Run::Deffered_File; }));
 
-	if (runnables.empty() || enable_repl) {
+	if (enable_repl) {
 		repl_line_number = 1;
-		enable_repl = true;
 #ifndef _WIN32
 		bestlineSetCompletionCallback(completion);
 #else
@@ -504,7 +383,8 @@ static std::optional<Error> Main(std::span<char const*> args)
 			if (command.starts_with(':')) {
 				command.remove_prefix(1);
 				if (!Try(handle_repl_session_commands(command, runner))) {
-					std::cerr << "musique: error: unrecognized REPL command '" << command << '\'' << std::endl;
+					std::cerr << pretty::begin_error << "musique: error:" << pretty::end;
+					std::cerr << " unrecognized REPL command '" << command << '\'' << std::endl;
 				}
 				continue;
 			}

musique/pretty.cc

@@ -8,10 +8,11 @@ extern "C" {
 
 namespace starters
 {
-	static std::string_view Error;
-	static std::string_view Path;
+	static std::string_view Bold;
 	static std::string_view Comment;
 	static std::string_view End;
+	static std::string_view Error;
+	static std::string_view Path;
 }
 
 std::ostream& pretty::begin_error(std::ostream& os)
@@ -29,6 +30,11 @@ std::ostream& pretty::begin_comment(std::ostream& os)
 	return os << starters::Comment;
 }
 
+std::ostream& pretty::begin_bold(std::ostream& os)
+{
+	return os << starters::Bold;
+}
+
 std::ostream& pretty::end(std::ostream& os)
 {
 	return os << starters::End;
@@ -56,16 +62,18 @@ void pretty::terminal_mode()
 #endif
 
 
-	starters::Error    = "\x1b[31;1m";
-	starters::Path     = "\x1b[34;1m";
+	starters::Bold     = "\x1b[1m";
 	starters::Comment  = "\x1b[30;1m";
 	starters::End      = "\x1b[0m";
+	starters::Error    = "\x1b[31;1m";
+	starters::Path     = "\x1b[34;1m";
 }
 
 void pretty::no_color_mode()
 {
-	starters::Error   = {};
-	starters::Path    = {};
+	starters::Bold    = {};
 	starters::Comment = {};
 	starters::End     = {};
+	starters::Error   = {};
+	starters::Path    = {};
 }

musique/pretty.hh

@@ -15,6 +15,9 @@ namespace pretty
 	/// Mark start of printing a comment
 	std::ostream& begin_comment(std::ostream&);
 
+	/// Mark start of printing with bold face
+	std::ostream& begin_bold(std::ostream&);
+
 	/// Mark end of any above
 	std::ostream& end(std::ostream&);
 

scripts/build.mk

@@ -1,4 +1,4 @@
-Release_Obj=$(addprefix bin/$(os)/,$(Obj))
+Release_Obj=$(addprefix bin/$(os)/,$(Obj)) bin/$(os)/builtin_function_documentation.o
 
 bin/$(os)/bestline.o: lib/bestline/bestline.c lib/bestline/bestline.h
 	@echo "CC $@"
@@ -12,7 +12,14 @@ bin/$(os)/$(Target): $(Release_Obj) bin/$(os)/main.o bin/$(os)/rtmidi.o $(Bestli
 	@echo "CXX $@"
 	@$(CXX) $(CXXFLAGS) $(RELEASE_FLAGS) $(CPPFLAGS) -o $@ $(Release_Obj) bin/$(os)/rtmidi.o $(Bestline) $(LDFLAGS) $(LDLIBS)
 
-Debug_Obj=$(addprefix bin/$(os)/debug/,$(Obj))
+bin/$(os)/builtin_function_documentation.o: bin/$(os)/builtin_function_documentation.cc
+	@echo "CXX $@"
+	@$(CXX) $(CXXFLAGS) $(RELEASE_FLAGS) $(CPPFLAGS) -o $@ $< -c
+
+bin/$(os)/builtin_function_documentation.cc: musique/interpreter/builtin_functions.cc scripts/document-builtin.py
+	scripts/document-builtin.py -f cpp -o $@ musique/interpreter/builtin_functions.cc
+
+Debug_Obj=$(addprefix bin/$(os)/debug/,$(Obj)) bin/$(os)/debug/builtin_function_documentation.o
 
 bin/$(os)/debug/$(Target): $(Debug_Obj) bin/$(os)/debug/main.o bin/$(os)/rtmidi.o $(Bestline)
 	@echo "CXX $@"
@@ -22,3 +29,6 @@ bin/$(os)/debug/%.o: musique/%.cc
 	@echo "CXX $@"
 	@$(CXX) $(CXXFLAGS) $(DEBUG_FLAGS) $(CPPFLAGS) -o $@ $< -c
 
+bin/$(os)/debug/builtin_function_documentation.o: bin/$(os)/builtin_function_documentation.cc
+	@echo "CXX $@"
+	@$(CXX) $(CXXFLAGS) $(DEBUG_FLAGS) $(CPPFLAGS) -o $@ $< -c

scripts/document-builtin.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
 import argparse
 import dataclasses
-import string
-import re
 import itertools
-import typing
+import json
+import re
+import string
 import subprocess
+import typing
 
 MARKDOWN_CONVERTER = "lowdown -m 'shiftheadinglevelby=3'"
 CPP_FUNC_IDENT_ALLOWLIST = string.ascii_letters + string.digits + "_"
@@ -60,6 +61,38 @@ HTML_SUFFIX = """
 </html>
 """
 
+FIND_DOCUMENTATION_FOR_BUILTIN = """
+std::optional<std::string_view> find_documentation_for_builtin(std::string_view builtin_name)
+{
+	for (auto [name, doc] : names_to_documentation) {
+		if (builtin_name == name)
+			return doc;
+	}
+	return std::nullopt;
+}
+
+std::vector<std::string_view> similar_names_to_builtin(std::string_view builtin_name)
+{
+    auto minimum_distance = std::numeric_limits<int>::max();
+
+    std::array<std::pair<std::string_view, std::string_view>, 4> closest;
+	std::partial_sort_copy(
+        names_to_documentation.begin(), names_to_documentation.end(),
+		closest.begin(), closest.end(),
+		[&minimum_distance, builtin_name](auto const& lhs, auto const& rhs) {
+			auto const lhs_score = edit_distance(builtin_name, lhs.first);
+			auto const rhs_score = edit_distance(builtin_name, rhs.first);
+			minimum_distance = std::min({ minimum_distance, lhs_score, rhs_score });
+			return lhs_score < rhs_score;
+		}
+	);
+
+    std::vector<std::string_view> result;
+    result.resize(4);
+    std::transform(closest.begin(), closest.end(), result.begin(), [](auto const& p) { return p.first; });
+    return result;
+}
+"""
 
 def warning(*args, prefix: str | None = None):
     if prefix is None:
@@ -151,7 +184,9 @@ def builtins_from_file(source_path: str) -> typing.Generator[Builtin, None, None
         yield builtin
 
 
-def filter_builtins(builtins: list[Builtin]) -> typing.Generator[Builtin, None, None]:
+def filter_builtins(
+    builtins: typing.Iterable[Builtin],
+) -> typing.Generator[Builtin, None, None]:
     for builtin in builtins:
         if not builtin.documentation:
             warning(f"builtin '{builtin.implementation}' doesn't have documentation")
@@ -167,7 +202,7 @@ def filter_builtins(builtins: list[Builtin]) -> typing.Generator[Builtin, None,
 def each_musique_name_occurs_once(
     builtins: typing.Iterable[Builtin],
 ) -> typing.Generator[Builtin, None, None]:
-    names = {}
+    names: dict[str, str] = {}
     for builtin in builtins:
         for name in builtin.names:
             if name in names:
@@ -178,7 +213,7 @@ def each_musique_name_occurs_once(
         yield builtin
 
 
-def generate_html_document(builtins: list[Builtin], output_path: str):
+def generate_html_document(builtins: typing.Iterable[Builtin], output_path: str):
     with open(output_path, "w") as out:
         out.write(HTML_PREFIX)
 
@@ -218,7 +253,47 @@ def generate_html_document(builtins: list[Builtin], output_path: str):
         out.write(HTML_SUFFIX)
 
 
-def main(source_path: str, output_path: str):
+def generate_cpp_documentation(builtins: typing.Iterable[Builtin], output_path: str):
+    # TODO Support markdown rendering and colors using `pretty` sublibrary
+
+    def documentation_str_var(builtin: Builtin):
+        return f"{builtin.implementation}_doc"
+
+    with open(output_path, "w") as out:
+        includes = [
+            "algorithm",
+            "array",
+            "edit_distance.hh",
+            "musique/interpreter/builtin_function_documentation.hh",
+            "vector",
+        ]
+        for include in includes:
+            print(f"#include <{include}>", file=out)
+
+        # 1. Generate strings with documentation
+        for builtin in builtins:
+            # FIXME json.dumps will probably produce valid C++ strings for most cases,
+            # but can we ensure that will output valid strings for all cases?
+            print(
+                "static constexpr std::string_view %s = %s;"
+                % (documentation_str_var(builtin), json.dumps(builtin.documentation)),
+                file=out,
+            )
+        print("", file=out)
+
+        # 2. Generate array mapping from name to documentation variable
+        names_to_documentation = list(sorted((name, documentation_str_var(builtin)) for builtin in builtins for name in builtin.names))
+        print("static constexpr std::array<std::pair<std::string_view, std::string_view>, %d> names_to_documentation = {" % (len(names_to_documentation), ), file=out)
+        for name, doc in names_to_documentation:
+              print("  std::pair { std::string_view(%s), %s }," % (json.dumps(name), doc), file=out)
+        print("};", file=out);
+
+        # 3. Generate function that given builtin name results in documentation string
+        print(FIND_DOCUMENTATION_FOR_BUILTIN, file=out)
+
+
+
+def main(source_path: str, output_path: str, format: typing.Literal["html", "cpp"]):
     "Generates documentaiton from file source_path and saves in output_path"
 
     builtins = builtins_from_file(source_path)
@@ -226,7 +301,10 @@ def main(source_path: str, output_path: str):
     builtins = each_musique_name_occurs_once(builtins)
     builtins = sorted(list(builtins), key=lambda builtin: builtin.names[0])
 
-    generate_html_document(builtins, output_path)
+    if format == "md":
+        generate_html_document(builtins, output_path)
+    else:
+        generate_cpp_documentation(builtins, output_path)
 
 
 if __name__ == "__main__":
@@ -247,10 +325,21 @@ if __name__ == "__main__":
         required=True,
         help="path for standalone HTML file containing generated documentation",
     )
+    parser.add_argument(
+        "-f",
+        "--format",
+        type=str,
+        default="md",
+        help="output format. One of {html, cpp} are allowed, where HTML yields standalone docs, and C++ mode yields integrated docs",
+    )
 
     PROGRAM_NAME = parser.prog
     args = parser.parse_args()
     assert len(args.source) == 1
     assert len(args.output) == 1
+    assert args.format in (
+        "html",
+        "cpp",
+    ), "Only C++ and HTML output formats are supported"
 
-    main(source_path=args.source[0], output_path=args.output[0])
+    main(source_path=args.source[0], output_path=args.output[0], format=args.format)