From 9e0e099cc0cc9f9eef6489a1fc0d4e6041036f27 Mon Sep 17 00:00:00 2001
From: Euan T <euantorano@users.noreply.github.com>
Date: Wed, 21 Mar 2018 10:30:58 +0000
Subject: [PATCH] Add an example to the `dynlib` module doc

Following a quesiton on Gitter about loading libraries dynamically based upon some runtime parameter, I noticed there's no documentation on the `dynlib` module for something that's quite common.
---
 lib/pure/dynlib.nim | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/lib/pure/dynlib.nim b/lib/pure/dynlib.nim
index fda41dadbd..ec6cbb232b 100644
--- a/lib/pure/dynlib.nim
+++ b/lib/pure/dynlib.nim
@@ -10,6 +10,49 @@
 ## This module implements the ability to access symbols from shared
 ## libraries. On POSIX this uses the ``dlsym`` mechanism, on
 ## Windows ``LoadLibrary``.
+##
+## Examples
+## --------
+##
+## Loading a simple C function
+## ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##
+## The following example demonstrates loading a function called 'greet' 
+## from a library that is determined at runtime based upon a language choice.
+## If the library fails to load or the function 'greet' is not found, 
+## it quits with a failure error code.
+##
+## .. code-block::nim
+##
+##   import dynlib
+##
+##   type
+##     greetFunction = proc(): cstring {.gcsafe, stdcall.}
+##
+##   let lang = stdin.readLine()
+##
+##   let lib = case lang
+##   of "french":
+##     loadLib("french.dll")
+##   else:
+##     loadLib("english.dll")
+##
+##   if lib == nil:
+##     echo "Error loading library"
+##     quit(QuitFailure)
+##
+##   let greet = cast[greetFunction](lib.symAddr("greet"))
+##
+##   if greet == nil:
+##     echo "Error loading 'greet' function from library"
+##     quit(QuitFailure)
+##
+##   let greeting = greet()
+##
+##   echo greeting
+##
+##   unloadLib(lib)
+##
 
 import strutils