fix namespace switching when using then in require-as-include scenarios

2 files changed, 88 insertions, 55 deletions

diff --git a/doc/core.md b/doc/core.md
index a247529..74bd2c3 100644
--- a/doc/core.md
+++ b/doc/core.md
@@ -4,7 +4,7 @@ of Fennel.
 
 This library contains a set of functions providing functions that
 behave similarly to Clojure's equivalents.  Library itself has nothing
-Fennel specific so it should work on Lua, e.g:
+Fennel specific, so it should work on Lua, e.g:
 
 ``` lua
 Lua 5.3.5  Copyright (C) 1994-2018 Lua.org, PUC-Rio
@@ -16,13 +16,13 @@ Lua 5.3.5  Copyright (C) 1994-2018 Lua.org, PUC-Rio
 This example is mapping an anonymous `function` over a table,
 producing new table and concatenating it with `" "`.
 
-However this library also provides Fennel-specific set of
-[macros](./macros.md), that provides additional facilities like
-`defn` or `defmulti` which extend the language allowing writing code
-that looks and works mostly like Clojure.
+However, this library also provides Fennel-specific set of
+[macros](./macros.md), that provides additional facilities like `defn`
+or `defmulti` which extend the language allowing writing code that
+looks and works mostly like Clojure.
 
 Each function in this library is created with `defn`, which is a
-special macros for creating multi-arity functions.  So when you see
+special macro for creating multi-arity functions.  So when you see
 function signature like `(foo [x])`, this means that this is function
 `foo`, that accepts exactly one argument `x`.  In contrary, functions
 created with `fn` will produce `(foo x)` signature (`x` is not inside
@@ -342,7 +342,7 @@ see `hash-map` for creating tables that have additional metadata
 attached for this test to work.
 
 ### Examples
-Non empty map:
+Non-empty map:
 
 ``` fennel
 (assert-is (map? {:a 1 :b 2}))
@@ -367,9 +367,9 @@ Function signature:
 (vector? [x])
 ```
 
-Check whether `tbl` is an sequential table.
+Check whether `tbl` is a sequential table.
 
-Non empty sequential tables are tested for two things:
+Non-empty sequential tables are tested for two things:
 - `next` returns the key-value pair,
 - key, that is returned by the `next` is equal to `1`.
 
@@ -379,7 +379,7 @@ see `vector` for creating tables that have additional
 metadata attached for this test to work.
 
 ### Examples
-Non empty vector:
+Non-empty vector:
 
 ``` fennel
 (assert-is (vector? [1 2 3 4]))
@@ -571,7 +571,7 @@ Function signature:
 (vector [& args])
 ```
 
-Constructs sequential table out of it's arguments.
+Constructs sequential table out of its arguments.
 
 Sets additional metadata for function `vector?` to work.
 
@@ -589,10 +589,10 @@ Function signature:
 (seq [coll])
 ```
 
-Construct a sequnce from the given collection `coll`.  If `coll` is an
-associative table, returns sequence of vectors with key and
-value.  If `col` is sequential table, returns its shallow copy.  If
-`col` is string, return sequential table of its codepoints.
+Construct a sequence from the given collection `coll`.  If `coll` is
+an associative table, returns sequence of vectors with key and value.
+If `col` is sequential table, returns its shallow copy.  If `col` is
+string, return sequential table of its codepoints.
 
 ### Examples
 Sequential tables are transformed to sequences:
@@ -602,7 +602,7 @@ Sequential tables are transformed to sequences:
 ```
 
 Associative tables are transformed to format like this `[[key1 value1]
-... [keyN valueN]]` and order is non deterministic:
+... [keyN valueN]]` and order is non-deterministic:
 
 ``` fennel
 (seq {:a 1 :b 2 :c 3}) ;; @seq([:b 2] [:a 1] [:c 3])
@@ -800,7 +800,7 @@ Reduces an associative table using function `f` and initial value `val`.
 applying `f` to `val`, the first key and the first value in `tbl`,
 then applying `f` to that result and the 2nd key and value, etc.  If
 `tbl` contains no entries, returns `val` and `f` is not called.  Note
-that reduce-kv is supported on sequential tables and strings, where
+that `reduce-kv` is supported on sequential tables and strings, where
 the keys will be the ordinals.
 
 Early termination is possible with the use of `reduced`
@@ -841,9 +841,9 @@ Function signature:
 
 Returns a vector consisting of the result of applying `f` to the
 set of first items of each `coll`, followed by applying `f` to the set
-of second items in each coll, until any one of the `colls` is exhausted.
-Any remaining items in other colls are ignored.  Function `f` should
-accept number-of-colls arguments.
+of second items in each coll, until any one of the `colls` is
+exhausted.  Any remaining items in other collections are ignored.
+Function `f` should accept number-of-colls arguments.
 
 ## `filter`
 Function signature:
@@ -890,7 +890,8 @@ Function signature:
 (range ([]) ([upper]) ([lower upper]) ([lower upper step]))
 ```
 
-Returns lazy sequence of of numbers from `lower` to `upper` with optional `step`.
+Returns lazy sequence of numbers from `lower` to `upper` with optional
+`step`.
 
 ## `reverse`
 Function signature:
@@ -899,7 +900,7 @@ Function signature:
 (reverse [coll])
 ```
 
-Returns a lazy sequnce with same items as in `coll` but in reverse order.
+Returns a lazy sequence with same items as in `coll` but in reverse order.
 
 ## `take`
 Function signature:
@@ -940,7 +941,7 @@ Given a collection `coll`, returns a lazy sequence of lists of `n`
 items each, at offsets `step` apart. If `step` is not supplied,
 defaults to `n`, i.e. the partitions do not overlap. If a `pad`
 collection is supplied, use its elements as necessary to complete last
-partition upto `n` items. In case there are not enough padding
+partition up to `n` items. In case there are not enough padding
 elements, return a partition with less than `n` items.
 
 ## `identity`
@@ -970,7 +971,7 @@ Function signature:
 
 Takes a function `f` and returns the function that takes the same
 amount of arguments as `f`, has the same effect, and returns the
-oppisite truth value.
+opposite truth value.
 
 ## `constantly`
 Function signature:
@@ -1069,7 +1070,8 @@ Function signature:
 (find [coll key])
 ```
 
-Returns the map entry for `key`, or `nil` if key not present in `coll`.
+Returns the map entry for `key`, or `nil` if key is not present in
+`coll`.
 
 ## `dissoc`
 Function signature:
@@ -1096,7 +1098,7 @@ Function signature:
 (remove-all-methods [multimethod])
 ```
 
-Removes all of the methods of `multimethod`
+Removes all methods of `multimethod`
 
 ## `methods`
 Function signature:
@@ -1213,7 +1215,8 @@ Function signature:
 (contains? [coll elt])
 ```
 
-Test if `elt` is in the `coll`.  May be a linear search depending on the type of the collection.
+Test if `elt` is in the `coll`.  It may be a linear search depending
+on the type of the collection.
 
 ## `count`
 Function signature:
@@ -1511,7 +1514,7 @@ Function signature:
 
 Returns a lazy sequence of the non-nil results of (f index item) in
 the `coll`.  Note, this means false return values will be included.
-`f` must be free of side-effects. Returns a transducer when no
+`f` must be free of side effects. Returns a transducer when no
 collection is provided.
 
 ## `lazy-seq`
@@ -1548,8 +1551,8 @@ truncated before the file is closed:
 ```fennel
 (let [lines (with-open [f (io.open "init.fnl" :r)]
               (line-seq f))]
-  ;; this errors because only first line was realized, but the file
-  ;; was closed before the rest of lines were cached
+  ;; this will error because only first line was realized, but the
+  ;; file was closed before the rest of lines were cached
   (assert-not (pcall next lines)))
 ```
 
@@ -1634,7 +1637,7 @@ Function signature:
 
 Returns a lazy sequence consisting of the result of applying `f` to 1
 and the first item of `coll`, followed by applying `f` to 2 and the
-second item in `coll`, etc, until `coll` is exhausted.  Returns a
+second item in `coll`, etc., until `coll` is exhausted.  Returns a
 transducer when no collection is provided.
 
 ## `mapcat`
@@ -1954,7 +1957,7 @@ Function signature:
 ```
 
 `reduce` with a transformation of `f` (`xform`). If `init` is not
-supplied, `f` will be called to produce it. f should be a reducing
+supplied, `f` will be called to produce it. `f` should be a reducing
 step function that accepts both 1 and 2 arguments, if it accepts only
 2 you can add the arity-1 with `completing`. Returns the result of
 applying (the transformed) `xform` to `init` and the first item in
diff --git a/doc/macros.md b/doc/macros.md
index d757495..8021db9 100644
--- a/doc/macros.md
+++ b/doc/macros.md
@@ -46,7 +46,7 @@ namespace set with the `ns` macro, unless `:private` was passed before
 the binding name. Accepts the `name` to be bound and the `initializer`
 expression. `meta` can be either an associative table where keys are
 strings, or a string representing a key from the table. If a sole
-string is given, it's value is set to `true` in the meta table.
+string is given, its value is set to `true` in the meta table.
 
 ## `defmethod`
 Function signature:
@@ -55,7 +55,7 @@ Function signature:
 (defmethod multi-fn dispatch-value fnspec)
 ```
 
-Attach new method to multi-function dispatch value. accepts the
+Attach new method to multi-function dispatch value. Accepts the
 `multi-fn` as its first argument, the `dispatch-value` as second, and
 `fnspec` - a function tail starting from argument list, followed by
 function body as in [`fn*`](#fn).
@@ -91,14 +91,14 @@ Multi-arity function tails are also supported:
 
 (defmulti foo (fn* ([x] [x]) ([x y] [x y])))
 
-(defmethod foo [10] [_] (print "I've knew I'll get 10"))
-(defmethod foo [10 20] [_ _] (print "I've knew I'll get both 10 and 20"))
+(defmethod foo [10] [_] (print "I knew I'll get 10"))
+(defmethod foo [10 20] [_ _] (print "I knew I'll get both 10 and 20"))
 (defmethod foo :default ([x] (print (.. "Umm, got" x)))
                         ([x y] (print (.. "Umm, got both " x " and " y))))
 ```
 
-Calling `(foo 10)` will print `"I've knew I'll get 10"`, and calling
-`(foo 10 20)` will print `"I've knew I'll get both 10 and 20"`.
+Calling `(foo 10)` will print `"I knew I'll get 10"`, and calling
+`(foo 10 20)` will print `"I knew I'll get both 10 and 20"`.
 However, calling `foo` with any other numbers will default either to
 `"Umm, got x"` message, when called with single value, and `"Umm, got
 both x and y"` when calling with two values.
@@ -168,10 +168,10 @@ Function signature:
 (defn ([name doc-string? [params*] pre-post? body]) ([name doc-string? ([params*] pre-post? body) +]))
 ```
 
-Same as (def name (fn* name docstring? [params*] pre-post? exprs*))
-or (def name (fn* name docstring? ([params*] pre-post? exprs*)+)) with
-any doc-string or attrs added to the function metadata.  Accepts
-`name` wich will be used to refer to a function in the current
+Same as `(def name (fn* name docstring? [params*] pre-post? exprs*))`
+or `(def name (fn* name docstring? ([params*] pre-post? exprs*)+))`
+with any doc-string or attrs added to the function metadata.  Accepts
+`name` which will be used to refer to a function in the current
 namespace, and optional `doc-string?`, a vector of function's
 `params*`, `pre-post?` conditions, and the `body` of the function.
 The body is wrapped in an implicit do.  See `fn*` for more info.
@@ -183,13 +183,13 @@ Function signature:
 (defn- ([name doc-string? [params*] pre-post? body]) ([name doc-string? ([params*] pre-post? body) +]))
 ```
 
-Same as (def :private name (fn* name docstring? [params*] pre-post?
-exprs*)) or (def :private name (fn* name docstring? ([params*]
-pre-post?  exprs*)+)) with any doc-string or attrs added to the
-function metadata. Accepts `name` wich will be used to refer to a
-function, and optional `doc-string?`, a vector of function's `params*`,
-`pre-post?` conditions, and the `body` of the function.  The body is
-wrapped in an implicit do. See `fn*` for more info.
+Same as `(def :private name (fn* name docstring? [params*] pre-post?
+exprs*))` or `(def :private name (fn* name docstring? ([params*]
+pre-post?  exprs*)+))` with any doc-string or attrs added to the
+function metadata. Accepts `name` which will be used to refer to a
+function, and optional `doc-string?`, a vector of function's
+`params*`, `pre-post?` conditions, and the `body` of the function.
+The body is wrapped in an implicit do. See `fn*` for more info.
 
 ## `fn*`
 Function signature:
@@ -222,7 +222,7 @@ list:
 
 The same syntax applies to multi-arity version.
 
-(pre and post checks are not yet implemented)
+(pre- and post-checks are not yet implemented)
 
 ## `if-let`
 Function signature:
@@ -232,7 +232,7 @@ Function signature:
 ```
 
 When `test` is logical `true`, evaluates the `if-branch` with `name`
-bound to the value of `test`. Otherwise evaluates the `else-branch`
+bound to the value of `test`. Otherwise, evaluates the `else-branch`
 
 ## `if-some`
 Function signature:
@@ -242,7 +242,7 @@ Function signature:
 ```
 
 When `test` is not `nil`, evaluates the `if-branch` with `name`
-bound to the value of `test`. Otherwise evaluates the `else-branch`
+bound to the value of `test`. Otherwise, evaluates the `else-branch`
 
 ## `in-ns`
 Function signature:
@@ -251,11 +251,12 @@ Function signature:
 (in-ns name)
 ```
 
-Sets the compile time variable `current-ns` to the given `name`.
+Sets the compile-time variable `cljlib-namespaces` to the given `name`.
 Affects such macros as `def`, `defn`, which will bind names to the
 specified namespace.
 
 ### Examples
+Creating several namespaces in the file, and defining functions in each:
 
 ```fennel
 (ns a)
@@ -273,6 +274,33 @@ specified namespace.
 (assert-eq (b.g) "g from b")
 ```
 
+Note, switching namespaces in the REPL doesn't affect non-namespaced
+local bindings.  In other words, when defining a local with `def`, a
+bot a local binding and a namespaced binding are created, and
+switching current namespace won't change the local binding:
+
+```
+>> (ns foo)
+nil
+>> (def x 42)
+nil
+>> (ns bar)
+nil
+>> (def x 1337)
+nil
+>> (in-ns foo)
+#<namespace: foo>
+>> x ; user might have expected to see 42 here
+1337
+>> foo.x
+42
+>> bar.x
+1337
+```
+
+Sadly, Fennel itself has no support for namespace switching in REPL,
+so this feature can be only partially emulated by the cljlib library.
+
 ## `lazy-cat`
 Function signature:
 
@@ -291,7 +319,7 @@ Function signature:
 (lazy-seq & body)
 ```
 
-Takes a `body` of expressions that returns an sequence, table or nil,
+Takes a `body` of expressions that returns a sequence, table or nil,
 and yields a lazy sequence that will invoke the body only the first
 time `seq` is called, and will cache the result and return it on all
 subsequent `seq` calls. See also - `realized?`
@@ -374,6 +402,8 @@ Note that when no `:as` alias is given, the library will be named
 after the innermost part of the require path, i.e. `some.lib` is
 transformed to `lib`.
 
+See `in-ns` on how to switch namespaces.
+
 ## `time`
 Function signature:
 
@@ -401,7 +431,7 @@ specified, an implicit catch-all clause is created.  `body*`, and
 inner expressions of `catch-clause*`, and `finally-clause?` are
 wrapped in implicit `do`.
 
-Finally clause is optional, and written as (finally body*).  If
+The `finally` clause is optional, and written as (finally body*).  If
 present, it must be the last clause in the [`try`](#try) form, and the only
 `finally` clause.  Note that `finally` clause is for side effects
 only, and runs either after succesful run of [`try`](#try) body, or after any