Merge pull request #818 from hiteshjasani/pr_devel_doc_import_constraints

Add docs for constraining and qualifying imports.

1 files changed, 35 insertions, 0 deletions

diff --git a/doc/tut1.txt b/doc/tut1.txt
index 91bff41d7..2e7f9d27f 100644
--- a/doc/tut1.txt
+++ b/doc/tut1.txt
@@ -1592,6 +1592,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
 --------------
 
@@ -1602,6 +1613,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
 -----------------