Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

better docs: os #10492

Merged
merged 2 commits into from
Jan 30, 2019
Merged

better docs: os #10492

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a94c5a0
better docs: os
narimiran Jan 29, 2019
c030351
remove broken test on osx
narimiran Jan 29, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 35 additions & 7 deletions lib/pure/includes/osenv.nim
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,18 @@ proc findEnvVar(key: string): int =
proc getEnv*(key: string, default = ""): TaintedString {.tags: [ReadEnvEffect].} =
## Returns the value of the `environment variable`:idx: named `key`.
##
## If the variable does not exist, "" is returned. To distinguish
## whether a variable exists or it's value is just "", call
## `existsEnv(key)`.
## If the variable does not exist, `""` is returned. To distinguish
## whether a variable exists or it's value is just `""`, call
## `existsEnv(key) proc <#existsEnv,string>`_.
##
## See also:
## * `existsEnv proc <#existsEnv,string>`_
## * `putEnv proc <#putEnv,string,string>`_
## * `envPairs iterator <#envPairs.i>`_
runnableExamples:
assert getEnv("unknownEnv") == ""
assert getEnv("unknownEnv", "doesn't exist") == "doesn't exist"

when nimvm:
discard "built into the compiler"
else:
Expand All @@ -119,6 +128,14 @@ proc getEnv*(key: string, default = ""): TaintedString {.tags: [ReadEnvEffect].}
proc existsEnv*(key: string): bool {.tags: [ReadEnvEffect].} =
## Checks whether the environment variable named `key` exists.
## Returns true if it exists, false otherwise.
##
## See also:
## * `getEnv proc <#getEnv,string,string>`_
## * `putEnv proc <#putEnv,string,string>`_
## * `envPairs iterator <#envPairs.i>`_
runnableExamples:
assert not existsEnv("unknownEnv")

when nimvm:
discard "built into the compiler"
else:
Expand All @@ -127,7 +144,12 @@ proc existsEnv*(key: string): bool {.tags: [ReadEnvEffect].} =

proc putEnv*(key, val: string) {.tags: [WriteEnvEffect].} =
## Sets the value of the `environment variable`:idx: named `key` to `val`.
## If an error occurs, `EInvalidEnvVar` is raised.
## If an error occurs, `OSError` is raised.
##
## See also:
## * `getEnv proc <#getEnv,string,string>`_
## * `existsEnv proc <#existsEnv,string>`_
## * `envPairs iterator <#envPairs.i>`_

# Note: by storing the string in the environment sequence,
# we guarantee that we don't free the memory before the program
Expand All @@ -154,9 +176,15 @@ proc putEnv*(key, val: string) {.tags: [WriteEnvEffect].} =
raiseOSError(osLastError())

iterator envPairs*(): tuple[key, value: TaintedString] {.tags: [ReadEnvEffect].} =
## Iterate over all `environments variables`:idx:. In the first component
## of the tuple is the name of the current variable stored, in the second
## its value.
## Iterate over all `environments variables`:idx:.
##
## In the first component of the tuple is the name of the current variable stored,
## in the second its value.
##
## See also:
## * `getEnv proc <#getEnv,string,string>`_
## * `existsEnv proc <#existsEnv,string>`_
## * `putEnv proc <#putEnv,string,string>`_
getEnvVarsC()
for i in 0..high(environment):
var p = find(environment[i], '=')
Expand Down
30 changes: 26 additions & 4 deletions lib/pure/includes/oserr.nim
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,24 @@ proc `$`*(err: OSErrorCode): string {.borrow.}
proc osErrorMsg*(errorCode: OSErrorCode): string =
## Converts an OS error code into a human readable string.
##
## The error code can be retrieved using the ``osLastError`` proc.
## The error code can be retrieved using the `osLastError proc <#osLastError>`_.
##
## If conversion fails, or ``errorCode`` is ``0`` then ``""`` will be
## returned.
##
## On Windows, the ``-d:useWinAnsi`` compilation flag can be used to
## make this procedure use the non-unicode Win API calls to retrieve the
## message.
##
## See also:
## * `raiseOSError proc <#raiseOSError,OSErrorCode,string>`_
## * `osLastError proc <#osLastError>`_
runnableExamples:
when defined(posix):
assert osErrorMsg(OSErrorCode(0)) == ""
assert osErrorMsg(OSErrorCode(1)) == "Operation not permitted"
assert osErrorMsg(OSErrorCode(2)) == "No such file or directory"

result = ""
when defined(nimscript):
discard
Expand All @@ -48,13 +58,21 @@ proc osErrorMsg*(errorCode: OSErrorCode): string =
result = $c_strerror(errorCode.int32)

proc raiseOSError*(errorCode: OSErrorCode; additionalInfo = "") {.noinline.} =
## Raises an ``OSError`` exception. The ``errorCode`` will determine the
## message, ``osErrorMsg`` will be used to get this message.
## Raises an `OSError exception <system.html#OSError>`_.
##
## The ``errorCode`` will determine the
## message, `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_ will be used
## to get this message.
##
## The error code can be retrieved using the ``osLastError`` proc.
## The error code can be retrieved using the `osLastError proc
## <#osLastError>`_.
##
## If the error code is ``0`` or an error message could not be retrieved,
## the message ``unknown OS error`` will be used.
##
## See also:
## * `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_
## * `osLastError proc <#osLastError>`_
var e: ref OSError; new(e)
e.errorCode = errorCode.int32
e.msg = osErrorMsg(errorCode)
Expand All @@ -80,6 +98,10 @@ proc osLastError*(): OSErrorCode {.sideEffect.} =
## On Windows some OS calls can reset the error code to ``0`` causing this
## procedure to return ``0``. It is therefore advised to call this procedure
## immediately after an OS call fails. On POSIX systems this is not a problem.
##
## See also:
## * `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_
## * `raiseOSError proc <#raiseOSError,OSErrorCode,string>`_
when defined(nimscript):
discard
elif defined(windows):
Expand Down
32 changes: 16 additions & 16 deletions lib/pure/includes/osseps.nim
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,44 +7,44 @@ const
when defined(Nimdoc): # only for proper documentation:
const
CurDir* = '.'
## The constant string used by the operating system to refer to the
## The constant character used by the operating system to refer to the
## current directory.
##
## For example: '.' for POSIX or ':' for the classic Macintosh.
## For example: `'.'` for POSIX or `':'` for the classic Macintosh.

ParDir* = ".."
## The constant string used by the operating system to refer to the
## parent directory.
##
## For example: ".." for POSIX or "::" for the classic Macintosh.
## For example: `".."` for POSIX or `"::"` for the classic Macintosh.

DirSep* = '/'
## The character used by the operating system to separate pathname
## components, for example, '/' for POSIX or ':' for the classic
## Macintosh.
## components, for example: `'/'` for POSIX, `':'` for the classic
## Macintosh, and `'\\'` on Windows.

AltSep* = '/'
## An alternative character used by the operating system to separate
## pathname components, or the same as `DirSep` if only one separator
## character exists. This is set to '/' on Windows systems
## where `DirSep` is a backslash.
## pathname components, or the same as `DirSep <#DirSep>`_ if only one separator
## character exists. This is set to `'/'` on Windows systems
## where `DirSep <#DirSep>`_ is a backslash (`'\\'`).

PathSep* = ':'
## The character conventionally used by the operating system to separate
## search patch components (as in PATH), such as ':' for POSIX
## or ';' for Windows.
## search patch components (as in PATH), such as `':'` for POSIX
## or `';'` for Windows.

FileSystemCaseSensitive* = true
## true if the file system is case sensitive, false otherwise. Used by
## `cmpPaths` to compare filenames properly.
## True if the file system is case sensitive, false otherwise. Used by
## `cmpPaths proc <#cmpPaths,string,string>`_ to compare filenames properly.

ExeExt* = ""
## The file extension of native executables. For example:
## "" for POSIX, "exe" on Windows.
## `""` for POSIX, `"exe"` on Windows (without a dot).

ScriptExt* = ""
## The file extension of a script file. For example: "" for POSIX,
## "bat" on Windows.
## The file extension of a script file. For example: `""` for POSIX,
## `"bat"` on Windows.

DynlibFormat* = "lib$1.so"
## The format string to turn a filename into a `DLL`:idx: file (also
Expand Down Expand Up @@ -127,4 +127,4 @@ else: # UNIX-like operating system
const
ExtSep* = '.'
## The character which separates the base filename from the extension;
## for example, the '.' in ``os.nim``.
## for example, the `'.'` in ``os.nim``.
Loading