path: root/001help.cc

//: Everything this project/binary supports.
//: This should give you a sense for what to look forward to in later layers.

:(before "End Commandline Parsing")
if (argc <= 1 || is_equal(argv[1], "--help")) {
  //: this is the functionality later layers will provide
  // currently no automated tests for commandline arg parsing
  if (argc <= 1) {
    cerr << "Please provide a Mu program to run.\n"
         << "\n";
  }
  cerr << "Usage:\n"
       << "  mu [options] [test] [files]\n"
       << "or:\n"
       << "  mu [options] [test] [files] -- [ingredients for function/recipe 'main']\n"
       << "Square brackets surround optional arguments.\n"
       << "\n"
       << "Examples:\n"
       << "  To load files and run 'main':\n"
       << "    mu file1.mu file2.mu ...\n"
       << "  To run 'main' and dump a trace of all operations at the end:\n"
       << "    mu --trace file1.mu file2.mu ...\n"
       << "  To run all tests:\n"
       << "    mu test\n"
       << "  To load files and then run all tests:\n"
       << "    mu test file1.mu file2.mu ...\n"
       << "  To run a single Mu scenario:\n"
       << "    mu test file1.mu file2.mu ... scenario\n"
       << "  To run a single Mu scenario and dump a trace at the end:\n"
       << "    mu --trace test file1.mu file2.mu ... scenario\n"
       << "  To load files and run only the tests in explicitly loaded files (for apps):\n"
       << "    mu --test-only-app test file1.mu file2.mu ...\n"
       << "  To load all files with a numeric prefix in a directory:\n"
       << "    mu directory1 directory2 ...\n"
       << "  You can test directories just like files.\n"
       << "    mu test directory1 directory2 ...\n"
       << "  To pass ingredients to a mu program, provide them after '--':\n"
       << "    mu file_or_dir1 file_or_dir2 ... -- ingredient1 ingredient2 ...\n"
       << "  To see where a mu program is spending its time:\n"
       << "    mu --profile file_or_dir1 file_or_dir2 ...\n"
       << "  this slices and dices time spent in various profile.* output files\n"
       << "  To print out the trace to stderr:\n"
       << "    mu --dump file1.mu file2.mu ...\n"
       << "  this is handy when you want to see sandboxed traces alongside the main one\n"
       << "\n"
       << "  To browse a trace generated by a previous run:\n"
       << "    mu browse-trace file\n"
       ;
  return 0;
}

//: Support for option parsing.
//: Options always begin with '--' and are always the first arguments. An
//: option will never follow a non-option.
:(before "End Commandline Parsing")
char** arg = &argv[1];
while (argc > 1 && starts_with(*arg, "--")) {
  if (false)
    ;  // no-op branch just so any further additions can consistently always start with 'else'
  // End Commandline Options(*arg)
  else
    cerr << "skipping unknown option " << *arg << '\n';
  --argc;  ++argv;  ++arg;
}

//:: Helper function used by the above fragment of code (and later layers too,
//:: who knows?).
//: The :(code) directive appends function definitions to the end of the
//: project. Regardless of where functions are defined, we can call them
//: anywhere we like as long as we format the function header in a specific
//: way: put it all on a single line without indent, end the line with ') {'
//: and no trailing whitespace. As long as functions uniformly start this
//: way, our 'build*' scripts contain a little command to automatically
//: generate declarations for them.
:(code)
bool is_equal(char* s, const char* lit) {
  return strncmp(s, lit, strlen(lit)) == 0;
}

bool starts_with(const string& s, const string& pat) {
  string::const_iterator a=s.begin(), b=pat.begin();
  for (/*nada*/;  a!=s.end() && b!=pat.end();  ++a, ++b)
    if (*a != *b) return false;
  return b == pat.end();
}

//: I'll throw some style conventions here for want of a better place for them.
//: As a rule I hate style guides. Do what you want, that's my motto. But since
//: we're dealing with C/C++, the one big thing we want to avoid is undefined
//: behavior. If a compiler ever encounters undefined behavior it can make
//: your program do anything it wants.
//:
//: For reference, my checklist of undefined behaviors to watch out for:
//:   out-of-bounds access
//:   uninitialized variables
//:   use after free
//:   dereferencing invalid pointers: null, a new of size 0, others
//:
//:   casting a large number to a type t