From 9a81d7460fdb16f4e77712e5381d9db8781f5ae6 Mon Sep 17 00:00:00 2001 From: "Kartik K. Agaram" Date: Sat, 22 Oct 2016 16:56:07 -0700 Subject: 3561 --- 002test.cc | 2 +- 003trace.cc | 5 +- 010vm.cc | 10 +- 011load.cc | 4 +- 012transform.cc | 4 +- 014literal_string.cc | 2 +- 020run.cc | 8 +- 028call_reply.cc | 8 +- 029tools.cc | 12 +- 030container.cc | 2 +- 033exclusive_container.cc | 2 +- 038new_text.cc | 2 +- 040brace.cc | 2 +- 042name.cc | 2 +- 043space.cc | 6 +- 050scenario.cc | 15 +-- 056shape_shifting_recipe.cc | 4 +- 057immutable.cc | 2 +- 073wait.cc | 2 +- 080display.cc | 6 +- 082scenario_screen.cc | 4 +- 091socket.cc | 8 +- 092socket.mu | 230 ++++++++++++++++++---------------- 101run_sandboxed.cc | 4 +- 999spaces.cc | 4 +- chessboard.mu | 6 +- edit/001-editor.mu | 2 +- edit/005-sandbox.mu | 2 +- edit/011-errors.mu | 2 +- edit/Readme.md | 4 +- html/002test.cc.html | 2 +- html/003trace.cc.html | 5 +- html/010vm.cc.html | 10 +- html/011load.cc.html | 4 +- html/012transform.cc.html | 4 +- html/014literal_string.cc.html | 2 +- html/020run.cc.html | 8 +- html/028call_reply.cc.html | 8 +- html/029tools.cc.html | 12 +- html/030container.cc.html | 2 +- html/033exclusive_container.cc.html | 2 +- html/038new_text.cc.html | 2 +- html/040brace.cc.html | 2 +- html/042name.cc.html | 2 +- html/043space.cc.html | 6 +- html/050scenario.cc.html | 15 +-- html/056shape_shifting_recipe.cc.html | 4 +- html/057immutable.cc.html | 2 +- html/073wait.cc.html | 2 +- html/080display.cc.html | 6 +- html/082scenario_screen.cc.html | 4 +- html/091socket.cc.html | 8 +- html/092socket.mu.html | 230 ++++++++++++++++++---------------- html/101run_sandboxed.cc.html | 4 +- html/999spaces.cc.html | 4 +- html/chessboard.mu.html | 6 +- html/edit/001-editor.mu.html | 2 +- html/edit/005-sandbox.mu.html | 2 +- html/edit/011-errors.mu.html | 2 +- html/lambda-to-mu.mu.html | 4 +- lambda-to-mu.mu | 4 +- mu | 2 +- mu.vim | 8 +- new_lesson | 4 +- sandbox/001-editor.mu | 2 +- sandbox/011-errors.mu | 2 +- sandbox/Readme.md | 12 +- sandbox/tmux.conf | 2 +- vimrc.vim | 4 +- 69 files changed, 414 insertions(+), 358 deletions(-) diff --git a/002test.cc b/002test.cc index 2f64437f..13398bb5 100644 --- a/002test.cc +++ b/002test.cc @@ -1,6 +1,6 @@ //: A simple test harness. To create new tests define functions starting with //: 'test_'. To run all tests so defined, run: -//: $ mu test +//: $ ./mu test //: //: Every layer should include tests, and can reach into previous layers. //: However, it seems like a good idea never to reach into tests from previous diff --git a/003trace.cc b/003trace.cc index 5f807476..e874d04f 100644 --- a/003trace.cc +++ b/003trace.cc @@ -99,7 +99,7 @@ Dump_trace = false; // compilation units. So no extern linkage. const int Max_depth = 9999; const int Error_depth = 0; // definitely always print errors -const int App_depth = 2; // temporarily where all mu code will trace to +const int App_depth = 2; // temporarily where all Mu code will trace to struct trace_stream { vector past_lines; @@ -393,7 +393,8 @@ using std::ofstream; //: Primitive statements will occupy 101-9989 extern const int Initial_callstack_depth = 101; extern const int Max_callstack_depth = 9989; -//: Finally, details of primitive mu statements will occupy depth 9990-9999 (more on that later as well) +//: Finally, details of primitive Mu statements will occupy depth 9990-9999 +//: (more on that later as well) //: //: This framework should help us hide some details at each level, mixing //: static ideas like layers with the dynamic notion of call-stack depth. diff --git a/010vm.cc b/010vm.cc index fd22cbf7..685fded6 100644 --- a/010vm.cc +++ b/010vm.cc @@ -118,9 +118,9 @@ Memory.clear(); // value 97 as the letter 'a', while a different location of type 'number' // would not. // -// Unlike most computers today, mu stores types in a single big table, shared -// by all the mu programs on the computer. This is useful in providing a -// seamless experience to help understand arbitrary mu programs. +// Unlike most computers today, Mu stores types in a single big table, shared +// by all the Mu programs on the computer. This is useful in providing a +// seamless experience to help understand arbitrary Mu programs. typedef int type_ordinal; :(before "End Globals") map Type_ordinal; @@ -194,7 +194,7 @@ enum primitive_recipes { :(code) //: It's all very well to construct recipes out of other recipes, but we need //: to know how to do *something* out of the box. For the following -//: recipes there are only codes, no entries in the book, because mu just knows +//: recipes there are only codes, no entries in the book, because Mu just knows //: what to do for them. void setup_recipes() { Recipe.clear(); Recipe_ordinal.clear(); @@ -532,7 +532,7 @@ string_tree* property(const reagent& r, const string& name) { } :(before "End Globals") -extern const string Ignore(","); // commas are ignored in mu except within [] strings +extern const string Ignore(","); // commas are ignored in Mu except within [] strings :(code) void skip_whitespace_but_not_newline(istream& in) { while (true) { diff --git a/011load.cc b/011load.cc index 5dd64335..20e4c2c8 100644 --- a/011load.cc +++ b/011load.cc @@ -1,6 +1,6 @@ -//: Phase 1 of running mu code: load it from a textual representation. +//: Phase 1 of running Mu code: load it from a textual representation. //: -//: The process of running mu code: +//: The process of running Mu code: //: load -> transform -> run :(scenarios load) // use 'load' instead of 'run' in all scenarios in this layer diff --git a/012transform.cc b/012transform.cc index 8395bcd6..2a2cfb9b 100644 --- a/012transform.cc +++ b/012transform.cc @@ -1,12 +1,12 @@ //: Phase 2: Filter loaded recipes through an extensible list of 'transforms'. //: -//: The process of running mu code: +//: The process of running Mu code: //: load -> transform -> run //: //: The hope is that this framework of transform tools will provide a //: deconstructed alternative to conventional compilers. //: -//: We're going to have many transforms in mu, and getting their order right +//: We're going to have many transforms in Mu, and getting their order right //: (not the same as ordering of layers) is a well-known problem. Some tips: //: a) Design each layer to rely on as few previous layers as possible. //: diff --git a/014literal_string.cc b/014literal_string.cc index 316bd4aa..eb5422ff 100644 --- a/014literal_string.cc +++ b/014literal_string.cc @@ -3,7 +3,7 @@ //: //: Instead of quotes, we'll use [] to delimit strings. That'll reduce the //: need for escaping since we can support nested brackets. And we can also -//: imagine that 'recipe' might one day itself be defined in mu, doing its own +//: imagine that 'recipe' might one day itself be defined in Mu, doing its own //: parsing. :(scenarios load) diff --git a/020run.cc b/020run.cc index e8bb44fd..248389c6 100644 --- a/020run.cc +++ b/020run.cc @@ -1,10 +1,10 @@ //: Phase 3: Start running a loaded and transformed recipe. //: -//: The process of running mu code: +//: The process of running Mu code: //: load -> transform -> run //: //: So far we've seen recipes as lists of instructions, and instructions point -//: at other recipes. To kick things off mu needs to know how to run certain +//: at other recipes. To kick things off Mu needs to know how to run certain //: 'primitive' recipes. That will then give the ability to run recipes //: containing these primitives. //: @@ -145,7 +145,7 @@ const vector& routine::steps() const { //: Step 1: load all .mu files with numeric prefixes (in order) :(before "End Load Recipes") -// Load .mu Core +// Load Mu Prelude //? Save_trace = true; //? START_TRACING_UNTIL_END_OF_SCOPE; load_file_or_directory("core.mu"); @@ -390,7 +390,7 @@ def main [ ] -mem: storing 34 in location 0 -//: mu is robust to various combinations of commas and spaces. You just have +//: Mu is robust to various combinations of commas and spaces. You just have //: to put spaces around the '<-'. :(scenario comma_without_space) diff --git a/028call_reply.cc b/028call_reply.cc index 067fd010..98287c69 100644 --- a/028call_reply.cc +++ b/028call_reply.cc @@ -112,10 +112,12 @@ def f [ ] +error: f: return ingredient '14:point' can't be saved in '3:num' -//: In mu we'd like to assume that any instruction doesn't modify its +//: In Mu we'd like to assume that any instruction doesn't modify its //: ingredients unless they're also products. The /same-as-ingredient inside -//: the recipe's 'reply' will help catch accidental misuse of such -//: 'ingredient-products' (sometimes called in-out parameters in other languages). +//: the recipe's 'reply' indicates that an ingredient is intended to be +//: modified in place, and will help catch accidental misuse of such +//: 'ingredient-products' (sometimes called in-out parameters in other +//: languages). :(scenario return_same_as_ingredient) % Hide_errors = true; diff --git a/029tools.cc b/029tools.cc index 12a1fdea..ce0794c4 100644 --- a/029tools.cc +++ b/029tools.cc @@ -1,10 +1,10 @@ -//: Allow mu programs to log facts just like we've been doing in C++ so far. +//: Allow Mu programs to log facts just like we've been doing in C++ so far. :(scenario trace) def main [ - trace 1, [foo], [this is a trace in mu] + trace 1, [foo], [this is a trace in Mu] ] -+foo: this is a trace in mu ++foo: this is a trace in Mu :(before "End Primitive Recipe Declarations") TRACE, @@ -192,9 +192,9 @@ case _SAVE_TRACE: { :(scenario assert) % Hide_errors = true; // '%' lines insert arbitrary C code into tests before calling 'run' with the lines below. Must be immediately after :(scenario) line. def main [ - assert 0, [this is an assert in mu] + assert 0, [this is an assert in Mu] ] -+error: this is an assert in mu ++error: this is an assert in Mu :(before "End Primitive Recipe Declarations") ASSERT, @@ -337,7 +337,7 @@ case _LOG: { break; } -//: set a variable from within mu code +//: set a variable from within Mu code //: useful for selectively tracing or printing after some point :(before "End Globals") bool Foo = false; diff --git a/030container.cc b/030container.cc index e11475a6..4519e347 100644 --- a/030container.cc +++ b/030container.cc @@ -652,7 +652,7 @@ def main [ ] +error: main: product of 'put' must be first ingredient '1:point', but got '3:point' -//:: Allow containers to be defined in mu code. +//:: Allow containers to be defined in Mu code. :(scenarios load) :(scenario container) diff --git a/033exclusive_container.cc b/033exclusive_container.cc index a88e684d..800f1a86 100644 --- a/033exclusive_container.cc +++ b/033exclusive_container.cc @@ -216,7 +216,7 @@ def main [ ] $error: 0 -//:: Allow exclusive containers to be defined in mu code. +//:: Allow exclusive containers to be defined in Mu code. :(scenario exclusive_container) exclusive-container foo [ diff --git a/038new_text.cc b/038new_text.cc index 3283e994..0b4e4663 100644 --- a/038new_text.cc +++ b/038new_text.cc @@ -58,7 +58,7 @@ int new_mu_text(const string& contents) { curr += tb_utf8_char_length(raw_contents[curr]); ++curr_address; } - // mu strings are not null-terminated in memory + // Mu strings are not null-terminated in memory. return result; } diff --git a/040brace.cc b/040brace.cc index eed6abab..75877dca 100644 --- a/040brace.cc +++ b/040brace.cc @@ -1,6 +1,6 @@ //: Structured programming //: -//: Our jump recipes are quite inconvenient to use, so mu provides a +//: Our jump recipes are quite inconvenient to use, so Mu provides a //: lightweight tool called 'transform_braces' to work in a slightly more //: convenient format with nested braces: //: diff --git a/042name.cc b/042name.cc index 35849997..a23f3a6a 100644 --- a/042name.cc +++ b/042name.cc @@ -1,5 +1,5 @@ //: A big convenience high-level languages provide is the ability to name memory -//: locations. In mu, a transform called 'transform_names' provides this +//: locations. In Mu, a transform called 'transform_names' provides this //: convenience. :(scenario transform_names) diff --git a/043space.cc b/043space.cc index 35f01391..5d8d8d72 100644 --- a/043space.cc +++ b/043space.cc @@ -388,11 +388,11 @@ bool Hide_missing_default_space_errors = true; Transform.push_back(check_default_space); // idempotent :(code) void check_default_space(const recipe_ordinal r) { - if (Hide_missing_default_space_errors) return; // skip previous core tests; this is only for mu code + if (Hide_missing_default_space_errors) return; // skip previous core tests; this is only for Mu code const recipe& caller = get(Recipe, r); // skip scenarios (later layer) // user code should never create recipes with underscores in their names - if (caller.name.find("scenario_") == 0) return; // skip mu scenarios which will use raw memory locations + if (caller.name.find("scenario_") == 0) return; // skip Mu scenarios which will use raw memory locations if (caller.name.find("run_") == 0) return; // skip calls to 'run', which should be in scenarios and will also use raw memory locations // assume recipes with only numeric addresses know what they're doing (usually tests) if (!contains_non_special_name(r)) return; @@ -403,7 +403,7 @@ void check_default_space(const recipe_ordinal r) { raise << caller.name << " does not seem to start with default-space or local-scope\n" << end(); } } -:(after "Load .mu Core") +:(after "Load Mu Prelude") Hide_missing_default_space_errors = false; :(after "Test Runs") Hide_missing_default_space_errors = true; diff --git a/050scenario.cc b/050scenario.cc index 0212e499..556c3208 100644 --- a/050scenario.cc +++ b/050scenario.cc @@ -112,7 +112,7 @@ scenario foo [ ] +run: {1: ("address" "array" "character")} <- new {"# not a comment": "literal-string"} -//:: Run scenarios when we run 'mu test'. +//:: Run scenarios when we run './mu test'. //: Treat the text of the scenario as a regular series of instructions. :(before "End Globals") @@ -257,7 +257,8 @@ def scenario-foo [ if (recipe_name.find("scenario-") == 0) return true; //:: The special instructions we want to support inside scenarios. -//: In a compiler for the mu VM these will require more work. +//: These are easy to support in an interpreter, but will require more work +//: when we eventually build a compiler. //: 'run' is a purely lexical convenience to separate the code actually being //: tested from any setup or teardown @@ -355,7 +356,7 @@ void check_memory(const string& s) { } if (!is_integer(rhs) && !is_noninteger(rhs)) { if (Current_scenario && !Scenario_testing_scenario) - // genuine test in a mu file + // genuine test in a .mu file raise << "\nF - " << Current_scenario->name << ": location '" << address << "' can't contain non-number " << rhs << "\n" << end(); else // just testing scenario support @@ -369,7 +370,7 @@ void check_memory(const string& s) { trace(9999, "run") << "checking location " << address << end(); if (get_or_insert(Memory, address) != value) { if (Current_scenario && !Scenario_testing_scenario) { - // genuine test in a mu file + // genuine test in a .mu file raise << "\nF - " << Current_scenario->name << ": expected location '" << address << "' to contain " << no_scientific(value) << " but saw " << no_scientific(get_or_insert(Memory, address)) << '\n' << end(); } else { @@ -428,7 +429,7 @@ void check_string(int address, const string& literal) { trace(9999, "run") << "checking location " << address+i << end(); if (get_or_insert(Memory, address+i) != literal.at(i)) { if (Current_scenario && !Scenario_testing_scenario) { - // genuine test in a mu file + // genuine test in a .mu file raise << "\nF - " << Current_scenario->name << ": expected location " << (address+i) << " to contain " << literal.at(i) << " but saw " << no_scientific(get_or_insert(Memory, address+i)) << " ('" << static_cast(get_or_insert(Memory, address+i)) << "')\n" << end(); } else { @@ -712,7 +713,7 @@ case CHECK_TRACE_COUNT_FOR_LABEL: { int count = trace_count(label); if (count != expected_count) { if (Current_scenario && !Scenario_testing_scenario) { - // genuine test in a mu file + // genuine test in a .mu file raise << "\nF - " << Current_scenario->name << ": " << maybe(current_recipe_name()) << "expected " << expected_count << " lines in trace with label '" << label << "' in trace: " << end(); DUMP(label); } @@ -737,7 +738,7 @@ def main [ +error: main: expected 2 lines in trace with label 'a' in trace //: Minor detail: ignore 'system' calls in scenarios, since anything we do -//: with them is by definition impossible to test through mu. +//: with them is by definition impossible to test through Mu. :(after "case _SYSTEM:") if (Current_scenario) break; diff --git a/056shape_shifting_recipe.cc b/056shape_shifting_recipe.cc index ac4c426c..4431f9c8 100644 --- a/056shape_shifting_recipe.cc +++ b/056shape_shifting_recipe.cc @@ -78,8 +78,8 @@ if (!candidates.empty()) { } skip_shape_shifting_variants:; -//: make sure we have no unspecialized shape-shifting recipes being called -//: before running mu programs +//: before running Mu programs, make sure no unspecialized shape-shifting +//: recipes can be called :(before "End Instruction Operation Checks") if (contains_key(Recipe, inst.operation) && inst.operation >= MAX_PRIMITIVE_RECIPES diff --git a/057immutable.cc b/057immutable.cc index 2dde38a8..4b7e4a68 100644 --- a/057immutable.cc +++ b/057immutable.cc @@ -524,7 +524,7 @@ set ingredient_indices(const instruction& inst, const set& ingredi //: can't pass both pointers back out, because if a caller tries to make both //: identical then you can't tell which value will be written on the way out. //: -//: Experimental solution: just tell mu that one points inside the other. +//: Experimental solution: just tell Mu that one points inside the other. //: This way we can return just one pointer as high up as necessary to capture //: all modifications performed by a recipe. //: diff --git a/073wait.cc b/073wait.cc index 1290b561..36ae1774 100644 --- a/073wait.cc +++ b/073wait.cc @@ -1,5 +1,5 @@ //: Routines can be put in a 'waiting' state, from which it will be ready to -//: run again when a specific memory location changes its value. This is mu's +//: run again when a specific memory location changes its value. This is Mu's //: basic technique for orchestrating the order in which different routines //: operate. diff --git a/080display.cc b/080display.cc index 52ac4283..6518c91c 100644 --- a/080display.cc +++ b/080display.cc @@ -43,9 +43,9 @@ case OPEN_CONSOLE: { int height = tb_height(); if (width > 222 || height > 222) tb_shutdown(); if (width > 222) - raise << "sorry, mu doesn't support windows wider than 222 characters in console mode. Please resize your window.\n" << end(); + raise << "sorry, Mu doesn't support windows wider than 222 characters in console mode. Please resize your window.\n" << end(); if (height > 222) - raise << "sorry, mu doesn't support windows taller than 222 characters in console mode. Please resize your window.\n" << end(); + raise << "sorry, Mu doesn't support windows taller than 222 characters in console mode. Please resize your window.\n" << end(); break; } @@ -527,7 +527,7 @@ case INTERACTIONS_LEFT: { break; } -//: a hack to make edit.mu more responsive +//: hack to make text-mode apps more responsive under Unix :(before "End Primitive Recipe Declarations") CLEAR_DISPLAY_FROM, diff --git a/082scenario_screen.cc b/082scenario_screen.cc index 73660fb5..e5fe76b3 100644 --- a/082scenario_screen.cc +++ b/082scenario_screen.cc @@ -282,7 +282,7 @@ void check_screen(const string& expected_contents, const int color) { if (color == -1 || color == get_or_insert(Memory, addr+cell_color_offset)) continue; // contents match but color is off if (Current_scenario && !Scenario_testing_scenario) { - // genuine test in a mu file + // genuine test in a .mu file raise << "\nF - " << Current_scenario->name << ": expected screen location (" << row << ", " << column << ", address " << addr << ", value " << no_scientific(get_or_insert(Memory, addr)) << ") to be in color " << color << " instead of " << no_scientific(get_or_insert(Memory, addr+cell_color_offset)) << "\n" << end(); dump_screen(); } @@ -310,7 +310,7 @@ void check_screen(const string& expected_contents, const int color) { ostringstream color_phrase; if (color != -1) color_phrase << " in color " << color; if (Current_scenario && !Scenario_testing_scenario) { - // genuine test in a mu file + // genuine test in a .mu file raise << "\nF - " << Current_scenario->name << ": expected screen location (" << row << ", " << column << ") to contain " << curr << expected_pretty << color_phrase.str() << " instead of " << no_scientific(get_or_insert(Memory, addr)) << actual_pretty << '\n' << end(); dump_screen(); } diff --git a/091socket.cc b/091socket.cc index 74626853..bd3f4ed6 100644 --- a/091socket.cc +++ b/091socket.cc @@ -218,6 +218,7 @@ case _READ_FROM_SOCKET: { } :(before "End Primitive Recipe Implementations") case _READ_FROM_SOCKET: { + cerr << "$read-from-socket\n"; long long int x = static_cast(ingredients.at(0).at(0)); socket_t* socket = reinterpret_cast(x); // 1. we'd like to simply read() from the socket @@ -227,19 +228,22 @@ case _READ_FROM_SOCKET: { // 3. but poll() will block on EOF, so only use poll() on the very first // $read-from-socket on a socket if (!socket->polled) { - socket->polled = true; pollfd p; bzero(&p, sizeof(p)); p.fd = socket->fd; p.events = POLLIN | POLLHUP; - if (poll(&p, /*num pollfds*/1, /*no timeout*/-1) <= 0) { + if (poll(&p, /*num pollfds*/1, /*timeout*/100/*ms*/) <= 0) { raise << maybe(current_recipe_name()) << "error in $read-from-socket\n" << end(); products.resize(2); products.at(0).push_back(0); products.at(1).push_back(false); break; } + cerr << "poll output: " << p.revents << '\n'; + cerr << "setting socket->polled\n"; + socket->polled = true; } + cerr << "$read-from-socket " << x << " continuing\n"; int bytes = static_cast(ingredients.at(1).at(0)); char* contents = new char[bytes]; bzero(contents, bytes); diff --git a/092socket.mu b/092socket.mu index 6a5c427a..1fd2586b 100644 --- a/092socket.mu +++ b/092socket.mu @@ -1,69 +1,87 @@ -# Wrappers around socket primitives that take a 'local-network' object and are -# thus easier to test. +# Wrappers around socket primitives that are easier to test. # -# The current semantics of fake port-connections don't match UNIX socket ones, -# but we'll improve them as we learn more. - -container local-network [ - data:&:@:port-connection -] - -# Port connections represent connections to ports on localhost. -# Before passing a local-network object to network functions -# `start-reading-socket` and `start-writing-socket`, add port-connections to -# the local-network. -# -# For reading, `receive-from-socket` will check for a -# port-connection on the port parameter that's been passed in. If there's -# no port-connection for that port, it will return nothing and log an error. -# If there is a port-connection for that port, it will transmit the contents -# to the provided sink. +# To test client operations, use `assume-resources` with a filename that +# begins with a hostname. (Filenames starting with '/' are assumed to be +# local.) # -# For writing, `start-writing-socket` returns a sink connecting the -# caller to the socket on the passed-in port. -container port-connection [ - port:num - contents:text -] +# To test server operations, just run a real client against localhost. -def new-port-connection port:num, contents:text -> p:&:port-connection [ +scenario example-server-test [ local-scope - load-ingredients - p:&:port-connection <- new port-connection:type - *p <- merge port, contents + # test server without a fake on a random (real) port + # that way repeatedly running the test will give ports time to timeout and + # close before reusing them + make-random-nondeterministic + port:num <- random-in-range 0/real-random-numbers, 8000, 8100 + run [ + socket:num <- $open-server-socket port + $print [server socket: ], socket, 10/newline + assert socket, [ +F - example-server-test: $open-server-socket failed] + $print [starting up server routine], 10/newline + handler-routine:number <- start-running serve-one-request socket, example-handler + ] + $print [starting to read from port ], port, 10/newline + source:&:source:char <- start-reading-from-network 0/real-resources, [localhost], [/], port + response:text <- drain source + 10:@:char/raw <- copy *response + memory-should-contain [ + 10:array:character <- [abc] + ] ] - -def new-fake-network -> n:&:local-network [ +# helper just for this scenario +def example-handler query:text -> response:text [ local-scope load-ingredients - n:&:local-network <- new local-network:type - local-network-ports:&:@:port-connection <- new port-connection:type, 0 - *n <- put *n, data:offset, local-network-ports + reply [abc] ] -scenario write-to-fake-socket [ +#? scenario example-client-test [ +#? local-scope +#? assume-resources [ +#? [example.com/] -> [abc] +#? ] +#? run [ +#? source:&:source:char <- start-reading-from-network resources, [example.com], [/] +#? ] +#? contents:text <- drain source +#? 10:@:char/raw <- copy *contents +#? memory-should-contain [ +#? 10:address:character <- [abc] +#? ] +#? ] + +type request-handler = (recipe text -> text) + +def serve-one-request socket:num, request-handler:request-handler [ local-scope - single-port-network:&:local-network <- new-fake-network - sink:&:sink:char, writer:num/routine <- start-writing-socket single-port-network, 8080 - sink <- write sink, 120/x - close sink - wait-for-routine writer - tested-port-connections:&:@:port-connection <- get *single-port-network, data:offset - tested-port-connection:port-connection <- index *tested-port-connections, 0 - contents:text <- get tested-port-connection, contents:offset - 10:@:char/raw <- copy *contents - memory-should-contain [ - 10:array:character <- [x] - ] + load-ingredients + session:num <- $accept socket + $print [server session socket: ], session, 10/newline + assert session, [ +F - example-server-test: $accept failed] + contents:&:source:char, sink:&:sink:char <- new-channel 30 + sink <- start-running receive-from-socket session, sink + query:text <- drain contents + response:text <- call request-handler, query + write-to-socket session, response + $close-socket session ] def start-reading-from-network resources:&:resources, host:text, path:text -> contents:&:source:char [ local-scope load-ingredients + $print [running start-reading-from-network], 10/newline + { + port:num, port-found?:boolean <- next-ingredient + break-if port-found? + port <- copy 80/http-port + } { break-if resources # real network - socket:num <- $open-client-socket host, 80/http-port + socket:num <- $open-client-socket host, port + $print [client socket: ], socket, 10/newline assert socket, [contents] req:text <- interpolate [GET _ HTTP/1.1], path request-socket socket, req @@ -102,70 +120,72 @@ def request-socket socket:num, s:text -> socket:num [ $write-to-socket socket, 10/lf ] -def start-writing-socket network:&:local-network, port:num -> sink:&:sink:char, routine-id:num [ - local-scope - load-ingredients - source:&:source:char, sink:&:sink:char <- new-channel 30 - { - break-if network - socket:num <- $open-server-socket port - session:num <- $accept socket - # TODO Create channel implementation of write-to-socket. - return sink, 0/routine-id - } - # fake network - routine-id <- start-running transmit-to-fake-socket network, port, source -] +#? def start-writing-socket network:&:local-network, port:num -> sink:&:sink:char, routine-id:num [ +#? local-scope +#? load-ingredients +#? source:&:source:char, sink:&:sink:char <- new-channel 30 +#? { +#? break-if network +#? socket:num <- $open-server-socket port +#? session:num <- $accept socket +#? # TODO Create channel implementation of write-to-socket. +#? return sink, 0/routine-id +#? } +#? # fake network +#? routine-id <- start-running transmit-to-fake-socket network, port, source +#? ] -def transmit-to-fake-socket network:&:local-network, port:num, source:&:source:char -> network:&:local-network, source:&:source:char [ - local-scope - load-ingredients - # compute new port connection contents - buf:&:buffer <- new-buffer 30 - { - c:char, done?:bool, source <- read source - break-unless c - buf <- append buf, c - break-if done? - loop - } - contents:text <- buffer-to-array buf - new-port-connection:&:port-connection <- new-port-connection port, contents - # Got the contents of the channel, time to write to fake port. - i:num <- copy 0 - port-connections:&:@:port-connection <- get *network, data:offset - len:num <- length *port-connections - { - done?:bool <- greater-or-equal i, len - break-if done? - current:port-connection <- index *port-connections, i - current-port:num <- get current, port:offset - ports-match?:bool <- equal current-port, port - i <- add i, 1 - loop-unless ports-match? - # Found an existing connection on this port, overwrite. - put-index *port-connections, i, *new-port-connection - reply - } - # Couldn't find an existing connection on this port, initialize a new one. - new-len:num <- add len, 1 - new-port-connections:&:@:port-connection <- new port-connection:type, new-len - put *network, data:offset, new-port-connections - i:num <- copy 0 - { - done?:bool <- greater-or-equal i, len - break-if done? - tmp:port-connection <- index *port-connections, i - put-index *new-port-connections, i, tmp - } - put-index *new-port-connections, len, *new-port-connection -] +#? def transmit-to-fake-socket network:&:local-network, port:num, source:&:source:char -> network:&:local-network, source:&:source:char [ +#? local-scope +#? load-ingredients +#? # compute new port connection contents +#? buf:&:buffer <- new-buffer 30 +#? { +#? c:char, done?:bool, source <- read source +#? break-unless c +#? buf <- append buf, c +#? break-if done? +#? loop +#? } +#? contents:text <- buffer-to-array buf +#? new-port-connection:&:port-connection <- new-port-connection port, contents +#? # Got the contents of the channel, time to write to fake port. +#? i:num <- copy 0 +#? port-connections:&:@:port-connection <- get *network, data:offset +#? len:num <- length *port-connections +#? { +#? done?:bool <- greater-or-equal i, len +#? break-if done? +#? current:port-connection <- index *port-connections, i +#? current-port:num <- get current, port:offset +#? ports-match?:bool <- equal current-port, port +#? i <- add i, 1 +#? loop-unless ports-match? +#? # Found an existing connection on this port, overwrite. +#? put-index *port-connections, i, *new-port-connection +#? reply +#? } +#? # Couldn't find an existing connection on this port, initialize a new one. +#? new-len:num <- add len, 1 +#? new-port-connections:&:@:port-connection <- new port-connection:type, new-len +#? put *network, data:offset, new-port-connections +#? i:num <- copy 0 +#? { +#? done?:bool <- greater-or-equal i, len +#? break-if done? +#? tmp:port-connection <- index *port-connections, i +#? put-index *new-port-connections, i, tmp +#? } +#? put-index *new-port-connections, len, *new-port-connection +#? ] def receive-from-socket socket:num, sink:&:sink:char -> sink:&:sink:char [ local-scope load-ingredients { + $print [read-from-socket ], socket, 10/newline req:text, eof?:bool <- $read-from-socket socket, 4096/bytes + loop-unless req bytes-read:num <- length *req i:num <- copy 0 { diff --git a/101run_sandboxed.cc b/101run_sandboxed.cc index 18d3eae0..66a19426 100644 --- a/101run_sandboxed.cc +++ b/101run_sandboxed.cc @@ -1,5 +1,5 @@ -//: Helper for various programming environments: run arbitrary mu code and -//: return some result in string form. +//: Helper for various programming environments: run arbitrary Mu code and +//: return some result in text form. :(scenario run_interactive_code) def main [ diff --git a/999spaces.cc b/999spaces.cc index f379d3c5..e28faa78 100644 --- a/999spaces.cc +++ b/999spaces.cc @@ -8,7 +8,7 @@ //: //: Location 0 - unused (since it can help uncover bugs) //: Locations 1-899 - reserved for tests -//: Locations 900-999 - reserved for predefined globals in mu scenarios, like keyboard, screen, etc. +//: Locations 900-999 - reserved for predefined globals in Mu scenarios, like keyboard, screen, etc. :(before "End Setup") assert(Max_variables_in_scenarios == 900); //: Locations 1000 ('Reserved_for_tests') onward - available to the allocator in chunks of size Initial_memory_per_routine. @@ -26,7 +26,7 @@ assert(Next_recipe_ordinal == 1000); //:: Depths for tracing //: //: 0 - unused -//: 1-100 - app-level trace statements in mu +//: 1-100 - app-level trace statements in Mu //: 101-9989 - call-stack statements (mostly label run) assert(Initial_callstack_depth == 101); assert(Max_callstack_depth == 9989); diff --git a/chessboard.mu b/chessboard.mu index f78027ab..feb49058 100644 --- a/chessboard.mu +++ b/chessboard.mu @@ -7,8 +7,8 @@ def main [ # The chessboard function takes keyboard and screen objects as 'ingredients'. # - # In mu it is good form (though not required) to explicitly show the - # hardware you rely on. + # In Mu it is good form (though not required) to explicitly state what + # hardware a function needs. # # Here the console and screen are both 0, which usually indicates real # hardware rather than a fake for testing as you'll see below. @@ -17,7 +17,7 @@ def main [ close-console # clean up screen, keyboard and mouse ] -## But enough about mu. Here's what it looks like to run the chessboard program. +## But enough about Mu. Here's what it looks like to run the chessboard program. scenario print-board-and-read-move [ local-scope diff --git a/edit/001-editor.mu b/edit/001-editor.mu index 82f4c4fa..133a8472 100644 --- a/edit/001-editor.mu +++ b/edit/001-editor.mu @@ -364,7 +364,7 @@ scenario editor-initializes-empty-text [ ] ] -# just a little color for mu code +# just a little color for Mu code scenario render-colors-comments [ local-scope diff --git a/edit/005-sandbox.mu b/edit/005-sandbox.mu index bc0488f7..b5380202 100644 --- a/edit/005-sandbox.mu +++ b/edit/005-sandbox.mu @@ -184,7 +184,7 @@ def run-sandboxes env:&:environment, screen:&:screen -> errors-found?:bool, env: ] -# copy code from recipe editor, persist, load into mu +# copy code from recipe editor, persist to disk, load # replaced in a later layer (whereupon errors-found? will actually be set) def update-recipes env:&:environment, screen:&:screen -> errors-found?:bool, env:&:environment, screen:&:screen [ local-scope diff --git a/edit/011-errors.mu b/edit/011-errors.mu index c0d4a63b..23c2c172 100644 --- a/edit/011-errors.mu +++ b/edit/011-errors.mu @@ -4,7 +4,7 @@ container environment [ recipe-errors:text ] -# copy code from recipe editor, persist, load into mu, save any errors +# copy code from recipe editor, persist to disk, load, save any errors def! update-recipes env:&:environment, screen:&:screen -> errors-found?:bool, env:&:environment, screen:&:screen [ local-scope load-ingredients diff --git a/edit/Readme.md b/edit/Readme.md index 30b27d9b..280c3500 100644 --- a/edit/Readme.md +++ b/edit/Readme.md @@ -1,6 +1,6 @@ -Environment for learning programming using mu: http://akkartik.name/post/mu +Environment for learning programming using Mu: http://akkartik.name/post/mu -Run it from the mu directory: +Run it from the `mu` directory: ```shell $ ./mu edit diff --git a/html/002test.cc.html b/html/002test.cc.html index 8ef2c73d..8e339e99 100644 --- a/html/002test.cc.html +++ b/html/002test.cc.html @@ -34,7 +34,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color 
 //: A simple test harness. To create new tests define functions starting with
 //: 'test_'. To run all tests so defined, run:
-//:   $ mu test
+//:   $ ./mu test
 //:
 //: Every layer should include tests, and can reach into previous layers.
 //: However, it seems like a good idea never to reach into tests from previous
diff --git a/html/003trace.cc.html b/html/003trace.cc.html
index 991df32e..a5523956 100644
--- a/html/003trace.cc.html
+++ b/html/003trace.cc.html
@@ -132,7 +132,7 @@ Dump_trace = false;
 // compilation units. So no extern linkage.
 const int Max_depth = 9999;
 const int Error_depth = 0;  // definitely always print errors
-const int App_depth = 2;  // temporarily where all mu code will trace to
+const int App_depth = 2;  // temporarily where all Mu code will trace to
 
 struct trace_stream {
   vector<trace_line> past_lines;
@@ -426,7 +426,8 @@ string trim(const str
 //: Primitive statements will occupy 101-9989
 extern const int Initial_callstack_depth = 101;
 extern const int Max_callstack_depth = 9989;
-//: Finally, details of primitive mu statements will occupy depth 9990-9999 (more on that later as well)
+//: Finally, details of primitive Mu statements will occupy depth 9990-9999
+//: (more on that later as well)
 //:
 //: This framework should help us hide some details at each level, mixing
 //: static ideas like layers with the dynamic notion of call-stack depth.
diff --git a/html/010vm.cc.html b/html/010vm.cc.html
index 13e76b37..22196064 100644
--- a/html/010vm.cc.html
+++ b/html/010vm.cc.html
@@ -154,9 +154,9 @@ Memory.clear();
 // value 97 as the letter 'a', while a different location of type 'number'
 // would not.
 //
-// Unlike most computers today, mu stores types in a single big table, shared
-// by all the mu programs on the computer. This is useful in providing a
-// seamless experience to help understand arbitrary mu programs.
+// Unlike most computers today, Mu stores types in a single big table, shared
+// by all the Mu programs on the computer. This is useful in providing a
+// seamless experience to help understand arbitrary Mu programs.
 typedef int type_ordinal;
 :(before "End Globals")
 map<string, type_ordinal> Type_ordinal;
@@ -230,7 +230,7 @@ atexit(teardown_types);:(code)
 //: It's all very well to construct recipes out of other recipes, but we need
 //: to know how to do *something* out of the box. For the following
-//: recipes there are only codes, no entries in the book, because mu just knows
+//: recipes there are only codes, no entries in the book, because Mu just knows
 //: what to do for them.
 void setup_recipes() {
   Recipe.clear();  Recipe_ordinal.clear();
@@ -568,7 +568,7 @@ string_tree* property(const<
 }
 
 :(before "End Globals")
-extern const string Ignore(",");  // commas are ignored in mu except within [] strings
+extern const string Ignore(",");  // commas are ignored in Mu except within [] strings
 :(code)
 void skip_whitespace_but_not_newline(istream& in) {
   while (true) {
diff --git a/html/011load.cc.html b/html/011load.cc.html
index 4bcbd016..0a1991b9 100644
--- a/html/011load.cc.html
+++ b/html/011load.cc.html
@@ -34,9 +34,9 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 
 
-//: Phase 1 of running mu code: load it from a textual representation.
+//: Phase 1 of running Mu code: load it from a textual representation.
 //:
-//: The process of running mu code:
+//: The process of running Mu code:
 //:   load -> transform -> run
 
 :(scenarios load)  // use 'load' instead of 'run' in all scenarios in this layer
diff --git a/html/012transform.cc.html b/html/012transform.cc.html
index c7e405eb..860b1de4 100644
--- a/html/012transform.cc.html
+++ b/html/012transform.cc.html
@@ -31,13 +31,13 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 //: Phase 2: Filter loaded recipes through an extensible list of 'transforms'.
 //:
-//:   The process of running mu code:
+//:   The process of running Mu code:
 //:     load -> transform -> run
 //:
 //: The hope is that this framework of transform tools will provide a
 //: deconstructed alternative to conventional compilers.
 //:
-//: We're going to have many transforms in mu, and getting their order right
+//: We're going to have many transforms in Mu, and getting their order right
 //: (not the same as ordering of layers) is a well-known problem. Some tips:
 //:   a) Design each layer to rely on as few previous layers as possible.
 //:
diff --git a/html/014literal_string.cc.html b/html/014literal_string.cc.html
index db095813..89329b1c 100644
--- a/html/014literal_string.cc.html
+++ b/html/014literal_string.cc.html
@@ -38,7 +38,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 //:
 //: Instead of quotes, we'll use [] to delimit strings. That'll reduce the
 //: need for escaping since we can support nested brackets. And we can also
-//: imagine that 'recipe' might one day itself be defined in mu, doing its own
+//: imagine that 'recipe' might one day itself be defined in Mu, doing its own
 //: parsing.
 
 :(scenarios load)
diff --git a/html/020run.cc.html b/html/020run.cc.html
index bc31010d..cb39df0e 100644
--- a/html/020run.cc.html
+++ b/html/020run.cc.html
@@ -39,11 +39,11 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 //: Phase 3: Start running a loaded and transformed recipe.
 //:
-//:   The process of running mu code:
+//:   The process of running Mu code:
 //:     load -> transform -> run
 //:
 //: So far we've seen recipes as lists of instructions, and instructions point
-//: at other recipes. To kick things off mu needs to know how to run certain
+//: at other recipes. To kick things off Mu needs to know how to run certain
 //: 'primitive' recipes. That will then give the ability to run recipes
 //: containing these primitives.
 //:
@@ -184,7 +184,7 @@ map<string, int>
 
 //: Step 1: load all .mu files with numeric prefixes (in order)
 :(before "End Load Recipes")
-// Load .mu Core
+// Load Mu Prelude
 //? Save_trace = true;
 //? START_TRACING_UNTIL_END_OF_SCOPE;
 load_file_or_directory("core.mu");
@@ -429,7 +429,7 @@ vector<double> read_memory-mem: storing 34 in location 0
 
-//: mu is robust to various combinations of commas and spaces. You just have
+//: Mu is robust to various combinations of commas and spaces. You just have
 //: to put spaces around the '<-'.
 
 :(scenario comma_without_space)
diff --git a/html/028call_reply.cc.html b/html/028call_reply.cc.html
index 9ef06f2c..4c32013f 100644
--- a/html/028call_reply.cc.html
+++ b/html/028call_reply.cc.html
@@ -147,10 +147,12 @@ Transform.push_back(+error: f: return ingredient '14:point' can't be saved in '3:num'
 
-//: In mu we'd like to assume that any instruction doesn't modify its
+//: In Mu we'd like to assume that any instruction doesn't modify its
 //: ingredients unless they're also products. The /same-as-ingredient inside
-//: the recipe's 'reply' will help catch accidental misuse of such
-//: 'ingredient-products' (sometimes called in-out parameters in other languages).
+//: the recipe's 'reply' indicates that an ingredient is intended to be
+//: modified in place, and will help catch accidental misuse of such
+//: 'ingredient-products' (sometimes called in-out parameters in other
+//: languages).
 
 :(scenario return_same_as_ingredient)
 % Hide_errors = true;
diff --git a/html/029tools.cc.html b/html/029tools.cc.html
index c4adebe7..a6322f9c 100644
--- a/html/029tools.cc.html
+++ b/html/029tools.cc.html
@@ -35,13 +35,13 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 
 
-//: Allow mu programs to log facts just like we've been doing in C++ so far.
+//: Allow Mu programs to log facts just like we've been doing in C++ so far.
 
 :(scenario trace)
 def main [
-  trace 1, [foo], [this is a trace in mu]
+  trace 1, [foo], [this is a trace in Mu]
 ]
-+foo: this is a trace in mu
++foo: this is a trace in Mu
 
 :(before "End Primitive Recipe Declarations")
 TRACE,
@@ -229,9 +229,9 @@ put(Recipe_ordinal,:(scenario assert)
 % Hide_errors = true;  // '%' lines insert arbitrary C code into tests before calling 'run' with the lines below. Must be immediately after :(scenario) line.
 def main [
-  assert 0, [this is an assert in mu]
+  assert 0, [this is an assert in Mu]
 ]
-+error: this is an assert in mu
++error: this is an assert in Mu
 
 :(before "End Primitive Recipe Declarations")
 ASSERT,
@@ -374,7 +374,7 @@ put(Recipe_ordinal,break;
 }
 
-//: set a variable from within mu code
+//: set a variable from within Mu code
 //: useful for selectively tracing or printing after some point
 :(before "End Globals")
 bool Foo = false;
diff --git a/html/030container.cc.html b/html/030container.cc.html
index 05838130..2c7bfe6d 100644
--- a/html/030container.cc.html
+++ b/html/030container.cc.html
@@ -690,7 +690,7 @@ put(Recipe_ordinal,+error: main: product of 'put' must be first ingredient '1:point', but got '3:point'
 
-//:: Allow containers to be defined in mu code.
+//:: Allow containers to be defined in Mu code.
 
 :(scenarios load)
 :(scenario container)
diff --git a/html/033exclusive_container.cc.html b/html/033exclusive_container.cc.html
index 619010d7..589e3075 100644
--- a/html/033exclusive_container.cc.html
+++ b/html/033exclusive_container.cc.html
@@ -253,7 +253,7 @@ put(Recipe_ordinal,0
 
-//:: Allow exclusive containers to be defined in mu code.
+//:: Allow exclusive containers to be defined in Mu code.
 
 :(scenario exclusive_container)
 exclusive-container foo [
diff --git a/html/038new_text.cc.html b/html/038new_text.cc.html
index 3a6cb0a4..0cd1e165 100644
--- a/html/038new_text.cc.html
+++ b/html/038new_text.cc.html
@@ -93,7 +93,7 @@ put(Type_abbreviations,(raw_contents[curr]);
     ++curr_address;
   }
-  // mu strings are not null-terminated in memory
+  // Mu strings are not null-terminated in memory.
   return result;
 }
 
diff --git a/html/040brace.cc.html b/html/040brace.cc.html
index aa4f3908..777e91cf 100644
--- a/html/040brace.cc.html
+++ b/html/040brace.cc.html
@@ -35,7 +35,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 //: Structured programming
 //:
-//: Our jump recipes are quite inconvenient to use, so mu provides a
+//: Our jump recipes are quite inconvenient to use, so Mu provides a
 //: lightweight tool called 'transform_braces' to work in a slightly more
 //: convenient format with nested braces:
 //:
diff --git a/html/042name.cc.html b/html/042name.cc.html
index f74f772d..d7027161 100644
--- a/html/042name.cc.html
+++ b/html/042name.cc.html
@@ -36,7 +36,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 
 //: A big convenience high-level languages provide is the ability to name memory
-//: locations. In mu, a transform called 'transform_names' provides this
+//: locations. In Mu, a transform called 'transform_names' provides this
 //: convenience.
 
 :(scenario transform_names)
diff --git a/html/043space.cc.html b/html/043space.cc.html
index fe5751c9..d66b6eeb 100644
--- a/html/043space.cc.html
+++ b/html/043space.cc.html
@@ -426,11 +426,11 @@ Update_refcounts_in_write_memory = true.push_back(check_default_space);  // idempotent
 :(code)
 void check_default_space(const recipe_ordinal r) {
-  if (Hide_missing_default_space_errors) return;  // skip previous core tests; this is only for mu code
+  if (Hide_missing_default_space_errors) return;  // skip previous core tests; this is only for Mu code
   const recipe& caller = get(Recipe, r);
   // skip scenarios (later layer)
   // user code should never create recipes with underscores in their names
-  if (caller.name.find("scenario_") == 0) return;  // skip mu scenarios which will use raw memory locations
+  if (caller.name.find("scenario_") == 0) return;  // skip Mu scenarios which will use raw memory locations
   if (caller.name.find("run_") == 0) return;  // skip calls to 'run', which should be in scenarios and will also use raw memory locations
   // assume recipes with only numeric addresses know what they're doing (usually tests)
   if (!contains_non_special_name(r)) return;
@@ -441,7 +441,7 @@ Transform.push_back(.name << " does not seem to start with default-space or local-scope\n" << end();
   }
 }
-:(after "Load .mu Core")
+:(after "Load Mu Prelude")
 Hide_missing_default_space_errors = false;
 :(after "Test Runs")
 Hide_missing_default_space_errors = true;
diff --git a/html/050scenario.cc.html b/html/050scenario.cc.html
index ffdee110..3ca291e8 100644
--- a/html/050scenario.cc.html
+++ b/html/050scenario.cc.html
@@ -151,7 +151,7 @@ vector<scenario> Scenarios;
 ]
 +run: {1: ("address" "array" "character")} <- new {"# not a comment": "literal-string"}
 
-//:: Run scenarios when we run 'mu test'.
+//:: Run scenarios when we run './mu test'.
 //: Treat the text of the scenario as a regular series of instructions.
 
 :(before "End Globals")
@@ -296,7 +296,8 @@ Name[r]["__maybe_make_raw_test__"] = Res
   if (recipe_name.find("scenario-") == 0) return true;
 
 //:: The special instructions we want to support inside scenarios.
-//: In a compiler for the mu VM these will require more work.
+//: These are easy to support in an interpreter, but will require more work
+//: when we eventually build a compiler.
 
 //: 'run' is a purely lexical convenience to separate the code actually being
 //: tested from any setup or teardown
@@ -394,7 +395,7 @@ put(Recipe_ordinal,}
     if (!is_integer(rhs) && !is_noninteger(rhs)) {
       if (Current_scenario && !Scenario_testing_scenario)
-        // genuine test in a mu file
+        // genuine test in a .mu file
         raise << "\nF - " << Current_scenario->name << ": location '" << address << "' can't contain non-number " << rhs << "\n" << end();
       else
         // just testing scenario support
@@ -408,7 +409,7 @@ put(Recipe_ordinal,(9999, "run") << "checking location " << address << end();
     if (get_or_insert(Memory, address) != value) {
       if (Current_scenario && !Scenario_testing_scenario) {
-        // genuine test in a mu file
+        // genuine test in a .mu file
         raise << "\nF - " << Current_scenario->name << ": expected location '" << address << "' to contain " << no_scientific(value) << " but saw " << no_scientific(get_or_insert(Memory, address)) << '\n' << end();
       }
       else {
@@ -467,7 +468,7 @@ put(Recipe_ordinal,(9999, "run") << "checking location " << address+i << end();
     if (get_or_insert(Memory, address+i) != literal.at(i)) {
       if (Current_scenario && !Scenario_testing_scenario) {
-        // genuine test in a mu file
+        // genuine test in a .mu file
         raise << "\nF - " << Current_scenario->name << ": expected location " << (address+i) << " to contain " << literal.at(i) << " but saw " << no_scientific(get_or_insert(Memory, address+i)) << " ('" << static_cast<char>(get_or_insert(Memory, address+i)) << "')\n" << end();
       }
       else {
@@ -751,7 +752,7 @@ put(Recipe_ordinal,int count = trace_count(label);
   if (count != expected_count) {
     if (Current_scenario && !Scenario_testing_scenario) {
-      // genuine test in a mu file
+      // genuine test in a .mu file
       raise << "\nF - " << Current_scenario->name << ": " << maybe(current_recipe_name()) << "expected " << expected_count << " lines in trace with label '" << label << "' in trace: " << end();
       DUMP(label);
     }
@@ -776,7 +777,7 @@ put(Recipe_ordinal,+error: main: expected 2 lines in trace with label 'a' in trace
 
 //: Minor detail: ignore 'system' calls in scenarios, since anything we do
-//: with them is by definition impossible to test through mu.
+//: with them is by definition impossible to test through Mu.
 :(after "case _SYSTEM:")
   if (Current_scenario) break;
 
diff --git a/html/056shape_shifting_recipe.cc.html b/html/056shape_shifting_recipe.cc.html
index fe4cc565..fa7aa789 100644
--- a/html/056shape_shifting_recipe.cc.html
+++ b/html/056shape_shifting_recipe.cc.html
@@ -117,8 +117,8 @@ candidates = strictly_matching_shape_shifting_variants(<
 }
 skip_shape_shifting_variants:;
 
-//: make sure we have no unspecialized shape-shifting recipes being called
-//: before running mu programs
+//: before running Mu programs, make sure no unspecialized shape-shifting
+//: recipes can be called
 
 :(before "End Instruction Operation Checks")
 if (contains_key(Recipe, inst.operation) && inst.operation >= MAX_PRIMITIVE_RECIPES
diff --git a/html/057immutable.cc.html b/html/057immutable.cc.html
index ac57964f..f1fbb793 100644
--- a/html/057immutable.cc.html
+++ b/html/057immutable.cc.html
@@ -561,7 +561,7 @@ set<int> ingredient_indices//: can't pass both pointers back out, because if a caller tries to make both
 //: identical then you can't tell which value will be written on the way out.
 //:
-//: Experimental solution: just tell mu that one points inside the other.
+//: Experimental solution: just tell Mu that one points inside the other.
 //: This way we can return just one pointer as high up as necessary to capture
 //: all modifications performed by a recipe.
 //:
diff --git a/html/073wait.cc.html b/html/073wait.cc.html
index 15ebd50e..dc24c121 100644
--- a/html/073wait.cc.html
+++ b/html/073wait.cc.html
@@ -36,7 +36,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 
 //: Routines can be put in a 'waiting' state, from which it will be ready to
-//: run again when a specific memory location changes its value. This is mu's
+//: run again when a specific memory location changes its value. This is Mu's
 //: basic technique for orchestrating the order in which different routines
 //: operate.
 
diff --git a/html/080display.cc.html b/html/080display.cc.html
index db77ddc2..56533131 100644
--- a/html/080display.cc.html
+++ b/html/080display.cc.html
@@ -77,9 +77,9 @@ put(Recipe_ordinal,int height = tb_height();
   if (width > 222 || height > 222) tb_shutdown();
   if (width > 222)
-    raise << "sorry, mu doesn't support windows wider than 222 characters in console mode. Please resize your window.\n" << end();
+    raise << "sorry, Mu doesn't support windows wider than 222 characters in console mode. Please resize your window.\n" << end();
   if (height > 222)
-    raise << "sorry, mu doesn't support windows taller than 222 characters in console mode. Please resize your window.\n" << end();
+    raise << "sorry, Mu doesn't support windows taller than 222 characters in console mode. Please resize your window.\n" << end();
   break;
 }
 
@@ -561,7 +561,7 @@ put(Recipe_ordinal,break;
 }
 
-//: a hack to make edit.mu more responsive
+//: hack to make text-mode apps more responsive under Unix
 
 :(before "End Primitive Recipe Declarations")
 CLEAR_DISPLAY_FROM,
diff --git a/html/082scenario_screen.cc.html b/html/082scenario_screen.cc.html
index 48be09ec..222c01a0 100644
--- a/html/082scenario_screen.cc.html
+++ b/html/082scenario_screen.cc.html
@@ -319,7 +319,7 @@ put(Recipe_ordinal,if (color == -1 || color == get_or_insert(Memory, addr+cell_color_offset)) continue;
         // contents match but color is off
         if (Current_scenario && !Scenario_testing_scenario) {
-          // genuine test in a mu file
+          // genuine test in a .mu file
           raise << "\nF - " << Current_scenario->name << ": expected screen location (" << row << ", " << column << ", address " << addr << ", value " << no_scientific(get_or_insert(Memory, addr)) << ") to be in color " << color << " instead of " << no_scientific(get_or_insert(Memory, addr+cell_color_offset)) << "\n" << end();
           dump_screen();
         }
@@ -347,7 +347,7 @@ put(Recipe_ordinal,;
       if (color != -1) color_phrase << " in color " << color;
       if (Current_scenario && !Scenario_testing_scenario) {
-        // genuine test in a mu file
+        // genuine test in a .mu file
         raise << "\nF - " << Current_scenario->name << ": expected screen location (" << row << ", " << column << ") to contain " << curr << expected_pretty << color_phrase.str() << " instead of " << no_scientific(get_or_insert(Memory, addr)) << actual_pretty << '\n' << end();
         dump_screen();
       }
diff --git a/html/091socket.cc.html b/html/091socket.cc.html
index a81f4c79..a3bd7316 100644
--- a/html/091socket.cc.html
+++ b/html/091socket.cc.html
@@ -251,6 +251,7 @@ put(Recipe_ordinal,}
 :(before "End Primitive Recipe Implementations")
 case _READ_FROM_SOCKET: {
+  cerr << "$read-from-socket\n";
   long long int x = static_cast<long long int>(ingredients.at(0).at(0));
   socket_t* socket = reinterpret_cast<socket_t*>(x);
   // 1. we'd like to simply read() from the socket
@@ -260,19 +261,22 @@ put(Recipe_ordinal,// 3. but poll() will block on EOF, so only use poll() on the very first
   // $read-from-socket on a socket
   if (!socket->polled) {
-    socket->polled = true;
     pollfd p;
     bzero(&p, sizeof(p));
     p.fd = socket->fd;
     p.events = POLLIN | POLLHUP;
-    if (poll(&p, /*num pollfds*/1, /*no timeout*/-1) <= 0) {
+    if (poll(&p, /*num pollfds*/1, /*timeout*/100/*ms*/) <= 0) {
       raise << maybe(current_recipe_name()) << "error in $read-from-socket\n" << end();
       products.resize(2);
       products.at(0).push_back(0);
       products.at(1).push_back(false);
       break;
     }
+    cerr << "poll output: " << p.revents << '\n';
+    cerr << "setting socket->polled\n";
+    socket->polled = true;
   }
+  cerr << "$read-from-socket " << x << " continuing\n";
   int bytes = static_cast<int>(ingredients.at(1).at(0));
   char* contents = new char[bytes];
   bzero(contents, bytes);
diff --git a/html/092socket.mu.html b/html/092socket.mu.html
index 186c7c3b..72ffa17c 100644
--- a/html/092socket.mu.html
+++ b/html/092socket.mu.html
@@ -33,72 +33,90 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 
 
-# Wrappers around socket primitives that take a 'local-network' object and are
-# thus easier to test.
+# Wrappers around socket primitives that are easier to test.
 #
-# The current semantics of fake port-connections don't match UNIX socket ones,
-# but we'll improve them as we learn more.
-
-container local-network [
-  data:&:@:port-connection
-]
-
-# Port connections represent connections to ports on localhost.
-# Before passing a local-network object to network functions
-# `start-reading-socket` and `start-writing-socket`, add port-connections to
-# the local-network.
-#
-# For reading, `receive-from-socket` will check for a
-# port-connection on the port parameter that's been passed in. If there's
-# no port-connection for that port, it will return nothing and log an error.
-# If there is a port-connection for that port, it will transmit the contents
-# to the provided sink.
+# To test client operations, use `assume-resources` with a filename that
+# begins with a hostname. (Filenames starting with '/' are assumed to be
+# local.)
 #
-# For writing, `start-writing-socket` returns a sink connecting the
-# caller to the socket on the passed-in port.
-container port-connection [
-  port:num
-  contents:text
-]
+# To test server operations, just run a real client against localhost.
 
-def new-port-connection port:num, contents:text -> p:&:port-connection [
+scenario example-server-test [
   local-scope
-  load-ingredients
-  p:&:port-connection <- new port-connection:type
-  *p <- merge port, contents
+  # test server without a fake on a random (real) port
+  # that way repeatedly running the test will give ports time to timeout and
+  # close before reusing them
+  make-random-nondeterministic
+  port:num <- random-in-range 0/real-random-numbers, 8000, 8100
+  run [
+    socket:num <- $open-server-socket port
+    $print [server socket: ], socket, 10/newline
+    assert socket, [ 
+F - example-server-test: $open-server-socket failed]
+    $print [starting up server routine], 10/newline
+    handler-routine:number <- start-running serve-one-request socket, example-handler
+  ]
+  $print [starting to read from port ], port, 10/newline
+  source:&:source:char <- start-reading-from-network 0/real-resources, [localhost], [/], port
+  response:text <- drain source
+  10:@:char/raw <- copy *response
+  memory-should-contain [
+    10:array:character <- [abc]
+  ]
 ]
-
-def new-fake-network -> n:&:local-network [
+# helper just for this scenario
+def example-handler query:text -> response:text [
   local-scope
   load-ingredients
-  n:&:local-network <- new local-network:type
-  local-network-ports:&:@:port-connection <- new port-connection:type, 0
-  *n <- put *n, data:offset, local-network-ports
+  reply [abc]
 ]
 
-scenario write-to-fake-socket [
+#? scenario example-client-test [
+#?   local-scope
+#?   assume-resources [
+#?     [example.com/] -> [abc]
+#?   ]
+#?   run [
+#?     source:&:source:char <- start-reading-from-network resources, [example.com], [/]
+#?   ]
+#?   contents:text <- drain source
+#?   10:@:char/raw <- copy *contents
+#?   memory-should-contain [
+#?     10:address:character <- [abc]
+#?   ]
+#? ]
+
+type request-handler = (recipe text -> text)
+
+def serve-one-request socket:num, request-handler:request-handler [
   local-scope
-  single-port-network:&:local-network <- new-fake-network
-  sink:&:sink:char, writer:num/routine <- start-writing-socket single-port-network, 8080
-  sink <- write sink, 120/x
-  close sink
-  wait-for-routine writer
-  tested-port-connections:&:@:port-connection <- get *single-port-network, data:offset
-  tested-port-connection:port-connection <- index *tested-port-connections, 0
-  contents:text <- get tested-port-connection, contents:offset
-  10:@:char/raw <- copy *contents
-  memory-should-contain [
-    10:array:character <- [x]
-  ]
+  load-ingredients
+  session:num <- $accept socket
+  $print [server session socket: ], session, 10/newline
+  assert session, [ 
+F - example-server-test: $accept failed]
+  contents:&:source:char, sink:&:sink:char <- new-channel 30
+  sink <- start-running receive-from-socket session, sink
+  query:text <- drain contents
+  response:text <- call request-handler, query
+  write-to-socket session, response
+  $close-socket session
 ]
 
 def start-reading-from-network resources:&:resources, host:text, path:text -> contents:&:source:char [
   local-scope
   load-ingredients
+  $print [running start-reading-from-network], 10/newline
+  {
+    port:num, port-found?:boolean <- next-ingredient
+    break-if port-found?
+    port <- copy 80/http-port
+  }
   {
     break-if resources
     # real network
-    socket:num <- $open-client-socket host, 80/http-port
+    socket:num <- $open-client-socket host, port
+    $print [client socket: ], socket, 10/newline
     assert socket, [contents]
     req:text <- interpolate [GET _ HTTP/1.1], path
     request-socket socket, req
@@ -137,70 +155,72 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
   $write-to-socket socket, 10/lf
 ]
 
-def start-writing-socket network:&:local-network, port:num -> sink:&:sink:char, routine-id:num [
-  local-scope
-  load-ingredients
-  source:&:source:char, sink:&:sink:char <- new-channel 30
-  {
-    break-if network
-    socket:num <- $open-server-socket port
-    session:num <- $accept socket
-    # TODO Create channel implementation of write-to-socket.
-    return sink, 0/routine-id
-  }
-  # fake network
-  routine-id <- start-running transmit-to-fake-socket network, port, source
-]
+#? def start-writing-socket network:&:local-network, port:num -> sink:&:sink:char, routine-id:num [
+#?   local-scope
+#?   load-ingredients
+#?   source:&:source:char, sink:&:sink:char <- new-channel 30
+#?   {
+#?     break-if network
+#?     socket:num <- $open-server-socket port
+#?     session:num <- $accept socket
+#?     # TODO Create channel implementation of write-to-socket.
+#?     return sink, 0/routine-id
+#?   }
+#?   # fake network
+#?   routine-id <- start-running transmit-to-fake-socket network, port, source
+#? ]
 
-def transmit-to-fake-socket network:&:local-network, port:num, source:&:source:char -> network:&:local-network, source:&:source:char [
-  local-scope
-  load-ingredients
-  # compute new port connection contents
-  buf:&:buffer <- new-buffer 30
-  {
-    c:char, done?:bool, source <- read source
-    break-unless c
-    buf <- append buf, c
-    break-if done?
-    loop
-  }
-  contents:text <- buffer-to-array buf
-  new-port-connection:&:port-connection <- new-port-connection port, contents
-  # Got the contents of the channel, time to write to fake port.
-  i:num <- copy 0
-  port-connections:&:@:port-connection <- get *network, data:offset
-  len:num <- length *port-connections
-  {
-    done?:bool <- greater-or-equal i, len
-    break-if done?
-    current:port-connection <- index *port-connections, i
-    current-port:num <- get current, port:offset
-    ports-match?:bool <- equal current-port, port
-    i <- add i, 1
-    loop-unless ports-match?
-    # Found an existing connection on this port, overwrite.
-    put-index *port-connections, i, *new-port-connection
-    reply
-  }
-  # Couldn't find an existing connection on this port, initialize a new one.
-  new-len:num <- add len, 1
-  new-port-connections:&:@:port-connection <- new port-connection:type, new-len
-  put *network, data:offset, new-port-connections
-  i:num <- copy 0
-  {
-    done?:bool <- greater-or-equal i, len
-    break-if done?
-    tmp:port-connection <- index *port-connections, i
-    put-index *new-port-connections, i, tmp
-  }
-  put-index *new-port-connections, len, *new-port-connection
-]
+#? def transmit-to-fake-socket network:&:local-network, port:num, source:&:source:char -> network:&:local-network, source:&:source:char [
+#?   local-scope
+#?   load-ingredients
+#?   # compute new port connection contents
+#?   buf:&:buffer <- new-buffer 30
+#?   {
+#?     c:char, done?:bool, source <- read source
+#?     break-unless c
+#?     buf <- append buf, c
+#?     break-if done?
+#?     loop
+#?   }
+#?   contents:text <- buffer-to-array buf
+#?   new-port-connection:&:port-connection <- new-port-connection port, contents
+#?   # Got the contents of the channel, time to write to fake port.
+#?   i:num <- copy 0
+#?   port-connections:&:@:port-connection <- get *network, data:offset
+#?   len:num <- length *port-connections
+#?   {
+#?     done?:bool <- greater-or-equal i, len
+#?     break-if done?
+#?     current:port-connection <- index *port-connections, i
+#?     current-port:num <- get current, port:offset
+#?     ports-match?:bool <- equal current-port, port
+#?     i <- add i, 1
+#?     loop-unless ports-match?
+#?     # Found an existing connection on this port, overwrite.
+#?     put-index *port-connections, i, *new-port-connection
+#?     reply
+#?   }
+#?   # Couldn't find an existing connection on this port, initialize a new one.
+#?   new-len:num <- add len, 1
+#?   new-port-connections:&:@:port-connection <- new port-connection:type, new-len
+#?   put *network, data:offset, new-port-connections
+#?   i:num <- copy 0
+#?   {
+#?     done?:bool <- greater-or-equal i, len
+#?     break-if done?
+#?     tmp:port-connection <- index *port-connections, i
+#?     put-index *new-port-connections, i, tmp
+#?   }
+#?   put-index *new-port-connections, len, *new-port-connection
+#? ]
 
 def receive-from-socket socket:num, sink:&:sink:char -> sink:&:sink:char [
   local-scope
   load-ingredients
   {
+    $print [read-from-socket ], socket, 10/newline
     req:text, eof?:bool <- $read-from-socket socket, 4096/bytes
+    loop-unless req
     bytes-read:num <- length *req
     i:num <- copy 0
     {
diff --git a/html/101run_sandboxed.cc.html b/html/101run_sandboxed.cc.html
index c79fb1d4..7b5da51b 100644
--- a/html/101run_sandboxed.cc.html
+++ b/html/101run_sandboxed.cc.html
@@ -34,8 +34,8 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 
 
-//: Helper for various programming environments: run arbitrary mu code and
-//: return some result in string form.
+//: Helper for various programming environments: run arbitrary Mu code and
+//: return some result in text form.
 
 :(scenario run_interactive_code)
 def main [
diff --git a/html/999spaces.cc.html b/html/999spaces.cc.html
index f72dcc82..cc8053e4 100644
--- a/html/999spaces.cc.html
+++ b/html/999spaces.cc.html
@@ -38,7 +38,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 //:
 //: Location 0 - unused (since it can help uncover bugs)
 //: Locations 1-899 - reserved for tests
-//: Locations 900-999 - reserved for predefined globals in mu scenarios, like keyboard, screen, etc.
+//: Locations 900-999 - reserved for predefined globals in Mu scenarios, like keyboard, screen, etc.
 :(before "End Setup")
 assert(Max_variables_in_scenarios == 900);
 //: Locations 1000 ('Reserved_for_tests') onward - available to the allocator in chunks of size Initial_memory_per_routine.
@@ -56,7 +56,7 @@ assert(Next_recipe_ordinal == //:: Depths for tracing
 //:
 //: 0 - unused
-//: 1-100 - app-level trace statements in mu
+//: 1-100 - app-level trace statements in Mu
 //: 101-9989 - call-stack statements (mostly label run)
 assert(Initial_callstack_depth == 101);
 assert(Max_callstack_depth == 9989);
diff --git a/html/chessboard.mu.html b/html/chessboard.mu.html
index 7f89f457..5b24345b 100644
--- a/html/chessboard.mu.html
+++ b/html/chessboard.mu.html
@@ -43,8 +43,8 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
   # The chessboard function takes keyboard and screen objects as 'ingredients'.
   #
-  # In mu it is good form (though not required) to explicitly show the
-  # hardware you rely on.
+  # In Mu it is good form (though not required) to explicitly state what
+  # hardware a function needs.
   #
   # Here the console and screen are both 0, which usually indicates real
   # hardware rather than a fake for testing as you'll see below.
@@ -53,7 +53,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
   close-console  # clean up screen, keyboard and mouse
 ]
 
-## But enough about mu. Here's what it looks like to run the chessboard program.
+## But enough about Mu. Here's what it looks like to run the chessboard program.
 
 scenario print-board-and-read-move [
   local-scope
diff --git a/html/edit/001-editor.mu.html b/html/edit/001-editor.mu.html
index 2f07e8eb..b6ba98e8 100644
--- a/html/edit/001-editor.mu.html
+++ b/html/edit/001-editor.mu.html
@@ -399,7 +399,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
   ]
 ]
 
-# just a little color for mu code
+# just a little color for Mu code
 
 scenario render-colors-comments [
   local-scope
diff --git a/html/edit/005-sandbox.mu.html b/html/edit/005-sandbox.mu.html
index 80650ce9..825a64ee 100644
--- a/html/edit/005-sandbox.mu.html
+++ b/html/edit/005-sandbox.mu.html
@@ -219,7 +219,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
   <run-sandboxes-end>
 ]
 
-# copy code from recipe editor, persist, load into mu
+# copy code from recipe editor, persist to disk, load
 # replaced in a later layer (whereupon errors-found? will actually be set)
 def update-recipes env:&:environment, screen:&:screen -> errors-found?:bool, env:&:environment, screen:&:screen [
   local-scope
diff --git a/html/edit/011-errors.mu.html b/html/edit/011-errors.mu.html
index e31fc3e9..f3a9b566 100644
--- a/html/edit/011-errors.mu.html
+++ b/html/edit/011-errors.mu.html
@@ -39,7 +39,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
   recipe-errors:text
 ]
 
-# copy code from recipe editor, persist, load into mu, save any errors
+# copy code from recipe editor, persist to disk, load, save any errors
 def! update-recipes env:&:environment, screen:&:screen -> errors-found?:bool, env:&:environment, screen:&:screen [
   local-scope
   load-ingredients
diff --git a/html/lambda-to-mu.mu.html b/html/lambda-to-mu.mu.html
index 131d0122..7ffbe91a 100644
--- a/html/lambda-to-mu.mu.html
+++ b/html/lambda-to-mu.mu.html
@@ -35,7 +35,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
 
 
 ## experimental compiler to translate programs written in a generic
-## expression-oriented language called 'lambda' into mu
+## expression-oriented language called 'lambda' into Mu
 
 scenario convert-lambda [
   run [
@@ -600,7 +600,7 @@ body { font-size: 12pt; font-family: monospace; color: #eeeeee; background-color
   ]
 ]
 
-## convert tree of cells to mu text
+## convert tree of cells to Mu text
 
 def to-mu in:&:cell -> out:text [
   local-scope
diff --git a/lambda-to-mu.mu b/lambda-to-mu.mu
index 4cd9da7d..c1c3171f 100644
--- a/lambda-to-mu.mu
+++ b/lambda-to-mu.mu
@@ -1,5 +1,5 @@
 ## experimental compiler to translate programs written in a generic
-## expression-oriented language called 'lambda' into mu
+## expression-oriented language called 'lambda' into Mu
 
 scenario convert-lambda [
   run [
@@ -564,7 +564,7 @@ scenario parse-dotted-list-of-more-than-two-atoms [
   ]
 ]
 
-## convert tree of cells to mu text
+## convert tree of cells to Mu text
 
 def to-mu in:&:cell -> out:text [
   local-scope
diff --git a/mu b/mu
index 76548f2f..da738da7 100755
--- a/mu
+++ b/mu
@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Compile mu if necessary before running it.
+# Compile Mu if necessary before running it.
 
 ./build || exit 1
 
diff --git a/mu.vim b/mu.vim
index 9d0ce033..6929c8b2 100644
--- a/mu.vim
+++ b/mu.vim
@@ -20,7 +20,7 @@ set cpo&vim
 "? let b:syntax = "mu"
 
 setlocal iskeyword=@,48-57,?,!,_,$,-
-setlocal formatoptions-=t  " mu programs have long lines
+setlocal formatoptions-=t  " Mu programs have long lines
 setlocal formatoptions+=c  " but comments should still wrap
 
 syntax match muComment /#.*$/ | highlight link muComment Comment
@@ -31,16 +31,16 @@ set comments+=n:#
 syntax match CommentedCode "#? .*"
 let b:cmt_head = "#? "
 
-" mu strings are inside [ ... ] and can span multiple lines
+" Mu strings are inside [ ... ] and can span multiple lines
 " don't match '[' at end of line, that's usually code
 syntax region muString start=+\[[^\]]+ end=+\]+
 syntax match muString "\[\]"
 highlight link muString String
-" mu syntax for representing the screen in scenarios
+" Mu syntax for representing the screen in scenarios
 syntax region muScreen start=+ \.+ end=+\.$\|$+
 highlight link muScreen muString
 
-" mu literals
+" Mu literals
 syntax match muLiteral %[^ ]\+:literal/[^ ,]*\|[^ ]\+:literal\>%
 syntax match muLiteral %\<[0-9-]\?[0-9]\+\>%
 syntax match muLiteral %\<[0-9-]\?[0-9]\+/[^ ,]*%
diff --git a/new_lesson b/new_lesson
index 9c18ecdb..3642b823 100755
--- a/new_lesson
+++ b/new_lesson
@@ -1,6 +1,6 @@
 #!/bin/sh
-# Run this before a fresh project for 'mu edit' or 'mu sandbox' to make sure
-# you don't lose any work.
+# Run this before running './mu edit' or './mu sandbox' to make sure you don't
+# lose any work.
 #
 # You'll be editing code in lesson/recipes.mu, and any sandboxes you create
 # will be in lesson/0, lesson/1, etc., from top to bottom.
diff --git a/sandbox/001-editor.mu b/sandbox/001-editor.mu
index 034d4cc9..54a35391 100644
--- a/sandbox/001-editor.mu
+++ b/sandbox/001-editor.mu
@@ -364,7 +364,7 @@ scenario editor-initializes-empty-text [
   ]
 ]
 
-# just a little color for mu code
+# just a little color for Mu code
 
 scenario render-colors-comments [
   local-scope
diff --git a/sandbox/011-errors.mu b/sandbox/011-errors.mu
index 6755af2d..cffbb437 100644
--- a/sandbox/011-errors.mu
+++ b/sandbox/011-errors.mu
@@ -4,7 +4,7 @@ container environment [
   recipe-errors:text
 ]
 
-# copy code from recipe editor, persist, load into mu, save any errors
+# copy code from recipe editor, save to disk, load, save any errors
 # test-recipes is a hook for testing
 def! update-recipes env:&:environment, screen:&:screen, test-recipes:text -> errors-found?:bool, env:&:environment, screen:&:screen [
   local-scope
diff --git a/sandbox/Readme.md b/sandbox/Readme.md
index eba8a762..b8ac4409 100644
--- a/sandbox/Readme.md
+++ b/sandbox/Readme.md
@@ -1,8 +1,8 @@
-Variant of [the mu programming environment](../edit) that runs just the sandbox.
+Variant of [the Mu programming environment](../edit) that runs just the sandbox.
 
 Suitable for people who want to run their favorite terminal-based editor with
-mu. Just run editor and sandbox inside split panes atop tmux. For example,
-here's mu running alongside vim:
+Mu. Just run editor and sandbox inside split panes atop tmux. For example,
+here's Mu running alongside vim:
 
 tmux+vim example
 
@@ -12,9 +12,9 @@ To set this up:
 
   b) copy the file `mu_run` somewhere in your `$PATH`.
 
-Now when you start tmux, split it into two vertical panes, run `mu sandbox` on
-the right pane and your editor on the left. You should be able to hit F4 in
+Now when you start tmux, split it into two vertical panes, run `./mu sandbox`
+on the right pane and your editor on the left. You should be able to hit F4 in
 either side to run the sandbox.
 
 Known issues: you have to explicitly save inside your editor before hitting
-F4, unlike with `mu edit`.
+F4, unlike with `./mu edit`.
diff --git a/sandbox/tmux.conf b/sandbox/tmux.conf
index 7c716c59..e5fa8b19 100644
--- a/sandbox/tmux.conf
+++ b/sandbox/tmux.conf
@@ -1,2 +1,2 @@
-# hotkey for running mu over tmux (assumes exactly two panes, 'mu sandbox' running on the right/second window)
+# hotkey for running Mu over tmux (assumes exactly two panes, './mu sandbox' running on the right/second window)
 bind-key -n F4 run mu_run
diff --git a/vimrc.vim b/vimrc.vim
index 32c96159..5008b415 100644
--- a/vimrc.vim
+++ b/vimrc.vim
@@ -17,13 +17,13 @@ function! HighlightTangledFile()
   highlight traceAbsent ctermfg=darkred
   syntax match tangleScenarioSetup /^\s*% .*/ | highlight link tangleScenarioSetup SpecialChar
 
-  " Our C++ files can have mu code in scenarios, so highlight mu comments like
+  " Our C++ files can have Mu code in scenarios, so highlight Mu comments like
   " regular comments.
   syntax match muComment /# .*$/ | highlight link muComment Comment
   syntax match muSalientComment /##.*$/ | highlight link muSalientComment SalientComment
   syntax match muCommentedCode /#? .*$/ | highlight link muCommentedCode CommentedCode
   set comments+=n:#
-  " Some other bare-bones mu highlighting.
+  " Some other bare-bones Mu highlighting.
   syntax match muLiteral %[^ ]\+:literal/[^ ,]*\|[^ ]\+:literal\>%
   syntax match muLiteral %[^ ]\+:label/[^ ,]*\|[^ ]\+:label\>%
   syntax match muLiteral %[^ ]\+:type/[^ ,]*\|[^ ]\+:type\>%
-- 
cgit 1.4.1-2-gfad0