Adding some more documentation, making pledge() take varargs rather than an openarray

Signed-off-by: Euan Torano <[email protected]>

Author: euantorano

.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{nim,nimble}]
+indent_style = space
+indent_size = 2

.travis.yml

@@ -41,7 +41,7 @@ before_script:
 script:
     - nim c --cc:$CC --verbosity:0 -r pledge.nim
     # Optional: build docs.
-    - nim doc --docSeeSrcUrl:https://github.com/euantorano/pledge.nim/blob/master --project pledge.nim
+    - nim doc2 --docSeeSrcUrl:https://github.com/euantorano/pledge.nim/blob/master --project pledge.nim
 cache:
   directories:
     - nim-master

README.md

@@ -1,6 +1,6 @@
 # pledge.nim
 
-OpenBSD's pledge(2) for Nim.
+A wrapper around OpenBSD's pledge(2) systemcall for Nim.
 
 ## Installation
 
@@ -15,7 +15,7 @@ nimble install pledge
 ```nim
 import pledge
 
-if not pledge([Promises.Stdio]):
+if not pledge(Promises.Stdio):
   # Pledge failed, cannot use stdio
   quit(QuitFailure)
 

pledge.nim

@@ -1,4 +1,26 @@
-# pledge(2) for Nim
+## A wrapper for the `pledge(2) <http://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man2/pledge.2?query=pledge>`_ systemcall, used to restrict system operations.
+##
+## On systems other than OpenBSD where `pledge` is not yet implemented, the wrapper has no effect.
+##
+## Example of making a single promise
+## ----------------------------------
+##
+## In order to pledge to only use the `stdio` promise as described in the `pledge(2) man page <http://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man2/pledge.2?query=pledge>`_, you simply pass the `Promise.Stdio` to `pledge()`:
+##
+## .. code-block::nim
+##   import pledge
+##
+##   let pledged = pledge(Promises.Stdio)
+##
+## Example of making several promises
+## ----------------------------------
+##
+## In order to pledge to use the `stdio` and `rpath` promises as described in the `pledge(2) man page <http://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man2/pledge.2?query=pledge>`_, you simply pass the required promises to `pledge()`:
+##
+## .. code-block::nim
+##   import pledge
+##
+##   let pledged = pledge(Promises.Stdio, Promises.Rpath)
 
 from os import osLastError, raiseOSError
 from sequtils import map, deduplicate
@@ -32,25 +54,30 @@ type Promise* {.pure.} = enum
   Pf = "pf",
   Audio = "audio"
 
-when defined(openbsd):
+when defined(nimdoc):
+  proc pledge*(promises: varargs[Promise]): bool {.raises: [OSError].} = discard
+    ## Pledge to use only the defined functions. Always returns true on non-OpenBSD systems.
+    ##
+    ## If the pledge call was successful, this will return true.
+    ##
+    ## If the pledge call is not successful, an `OSError` will be thrown.
+elif defined(openbsd):
   proc pledge_c(promises: cstring, paths: cstringArray): cint {.importc: "pledge".}
 
   proc promisesToString(promises: openArray[Promise]): string =
     ## Convert a list of promises to a string for use with the `pledge(2)` function.
     let stringPromises = map(promises, proc(p: Promise): string = $p)
     return join(deduplicate(stringPromises), " ")
 
-  proc pledge*(promises: openArray[Promise]): bool {.raises: [OSError].} =
-    ## Pledge to use only the defined functions, separated by a space. Always returns true on non-OpenBSD systems.
+  proc pledge*(promises: varargs[Promise]): bool {.raises: [OSError].} =
     let promisesString = promisesToString(promises)
     let pledged = pledge_c(promisesString, nil)
 
     if pledged != 0:
       let errorCode = osLastError()
       raiseOSError(errorCode)
 
-    return pledged == 0
+    result = true
+
 else:
-  proc pledge*(promises: openArray[Promise]): bool =
-    ## Pledge to use only the defined functions, separated by a space. Always returns true on non-OpenBSD systems.
-    return true
+  proc pledge*(promises: varargs[Promise]): bool = true

pledge.nimble

@@ -1,6 +1,16 @@
-[Package]
-name          = "pledge"
-version       = "1.0.0"
+# Package
+
+version       = "1.0.1"
 author        = "Euan T"
-description   = "OpenBSDs pledge(2) for Nim."
+description   = "A wrapper around OpenBSD's pledge(2) systemcall for Nim."
 license       = "BSD"
+
+# Dependencies
+
+requires "nim >= 0.13.0"
+
+task tests, "Run unit tests":
+  exec "nim c -r tests/main"
+
+task docs, "Build package documentation":
+  exec "nim doc2 pledge.nim"

tests/README.md

@@ -1,26 +1,12 @@
-import pledge, unittest, os
+import ../pledge, unittest, os
 
 suite "pledge tests":
   test  "can pledge":
-    check pledge([Promise.Stdio])
+    check pledge(Promise.Stdio, Promise.Rpath)
 
   when defined(openbsd):
     test "can not elevate":
-      check pledge([Promise.Stdio])
+      check pledge(Promise.Stdio)
 
-      try:
-        check pledge([Promise.Stdio, Promise.Rpath]) == false
-        # Should never reach here
-        check false
-      except OSError:
-        let msg = getCurrentExceptionMsg()
-        check msg == "Operation not permitted"
-  else:
-    test "can not elevate":
-      check pledge([Promise.Stdio])
-
-      try:
-        check pledge([Promise.Stdio, Promise.Rpath])
-      except OSError:
-        let msg = getCurrentExceptionMsg()
-        check msg == "Operation not permitted"
+      expect OSError:
+        check pledge(Promise.Stdio, Promise.Rpath) == false