From 74af6351b2b1888cc1437e158cf29851f8e6465e Mon Sep 17 00:00:00 2001
From: Hitesh Jasani <hitesh@grokken.com>
Date: Thu, 16 Jan 2014 14:42:12 -0500
Subject: Add docs for constraining and qualifying imports.

---
 doc/tut1.txt | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

(limited to 'doc')

diff --git a/doc/tut1.txt b/doc/tut1.txt
index 2070c69d6..52d46d9bd 100644
--- a/doc/tut1.txt
+++ b/doc/tut1.txt
@@ -1582,6 +1582,17 @@ rules apply:
   write(stdout, x(3))   # ambiguous: which `x` is to call?
 
 
+Excluding symbols
+-----------------
+
+The normal ``import`` statement will bring in all exported symbols.
+These can be limited by naming symbols which should be excluded with
+the ``except`` qualifier.
+
+.. code-block:: nimrod
+  import mymodule except y
+
+
 From statement
 --------------
 
@@ -1592,6 +1603,30 @@ exported symbols. An alternative that only imports listed symbols is the
 .. code-block:: nimrod
   from mymodule import x, y, z
 
+The ``from`` statement can also force namespace qualification on
+symbols, thereby making symbols available, but needing to be qualified
+to be used.
+
+.. code-block:: nimrod
+  from mymodule import x, y, z
+
+  x()           # use x without any qualification
+
+.. code-block:: nimrod
+  from mymodule import nil
+
+  mymodule.x()  # must qualify x with the module name as prefix
+
+  x()           # using x here without qualification is a compile error
+
+Since module names are generally long to be descriptive, you can also
+define a shorter alias to use when qualifying symbols.
+
+.. code-block:: nimrod
+  from mymodule as m import nil
+
+  m.x()         # m is aliasing mymodule
+
 
 Include statement
 -----------------
-- 
cgit 1.4.1-2-gfad0