From c04ae96e11de4f54e054498c7e44c2fc93c0a99e Mon Sep 17 00:00:00 2001 From: Jakob Oesterling Date: Fri, 25 Sep 2015 18:08:10 +0200 Subject: [PATCH 1/9] added examples in documenation for sizeof high low --- lib/system.nim | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/lib/system.nim b/lib/system.nim index 4d397a5fc5..ca5e180907 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -221,11 +221,21 @@ proc high*[T](x: T): T {.magic: "High", noSideEffect.} ## the highest possible value of an ordinal value `x`. As a special ## semantic rule, `x` may also be a type identifier. ## ``high(int)`` is Nim's way of writing `INT_MAX`:idx: or `MAX_INT`:idx:. + ## + ## .. code-block:: nim + ## var arr = [1,2,3,4,5,6,7] + ## high(arr) #=> 6 + ## high(2) #=> 9223372036854775807 proc low*[T](x: T): T {.magic: "Low", noSideEffect.} ## returns the lowest possible index of an array, a sequence, a string or ## the lowest possible value of an ordinal value `x`. As a special ## semantic rule, `x` may also be a type identifier. + ## + ## .. code-block:: nim + ## var arr = [1,2,3,4,5,6,7] + ## high(arr) #=> 0 + ## high(2) #=> -9223372036854775808 type range*{.magic: "Range".}[T] ## Generic type to construct range types. @@ -584,6 +594,10 @@ proc sizeof*[T](x: T): int {.magic: "SizeOf", noSideEffect.} ## its usage is discouraged - using ``new`` for the most cases suffices ## that one never needs to know ``x``'s size. As a special semantic rule, ## ``x`` may also be a type identifier (``sizeof(int)`` is valid). + ## + ## .. code-block:: nim + ## sizeof('A') #=> 1 + ## sizeof(2) #=> 8 when defined(nimtypedescfixed): proc sizeof*(x: typedesc): int {.magic: "SizeOf", noSideEffect.} @@ -703,12 +717,22 @@ template excl*[T](s: var set[T], flags: set[T]) = proc card*[T](x: set[T]): int {.magic: "Card", noSideEffect.} ## returns the cardinality of the set ``x``, i.e. the number of elements ## in the set. + ## + ## .. code-block:: nim + ## var i = {1,2,3,4} + ## card(i) #=> 4 proc ord*[T](x: T): int {.magic: "Ord", noSideEffect.} ## returns the internal int value of an ordinal value ``x``. + ## + ## .. code-block:: nim + ## card('A') #=> 65 proc chr*(u: range[0..255]): char {.magic: "Chr", noSideEffect.} ## converts an int in the range 0..255 to a character. + ## + ## .. code-block:: nim + ## chr(65) #=> A # -------------------------------------------------------------------------- # built-in operators From e429810220ad61e1d79a0d550f7b479ff8afe991 Mon Sep 17 00:00:00 2001 From: Jakob Oesterling Date: Fri, 25 Sep 2015 18:38:32 +0200 Subject: [PATCH 2/9] added examples in documenation for add del delete repr insert --- lib/system.nim | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/lib/system.nim b/lib/system.nim index ca5e180907..d37a8460e3 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -1337,6 +1337,10 @@ proc add *[T](x: var seq[T], y: openArray[T]) {.noSideEffect.} = ## containers should also call their adding proc `add` for consistency. ## Generic code becomes much easier to write if the Nim naming scheme is ## respected. + ## + ## .. code-block:: nim + ## var s: seq[string] = @["test2","test2"] + ## s.add("test") #=> @[test2, test2, test] let xl = x.len setLen(x, xl + y.len) for i in 0..high(y): x[xl+i] = y[i] @@ -1351,6 +1355,10 @@ proc shallowCopy*[T](x: var T, y: T) {.noSideEffect, magic: "ShallowCopy".} proc del*[T](x: var seq[T], i: Natural) {.noSideEffect.} = ## deletes the item at index `i` by putting ``x[high(x)]`` into position `i`. ## This is an O(1) operation. + ## + ## .. code-block:: nim + ## var i = @[1,2,3,4,5] + ## i.del(2) #=> @[1, 2, 5, 4] let xl = x.len - 1 shallowCopy(x[i], x[xl]) setLen(x, xl) @@ -1358,6 +1366,10 @@ proc del*[T](x: var seq[T], i: Natural) {.noSideEffect.} = proc delete*[T](x: var seq[T], i: Natural) {.noSideEffect.} = ## deletes the item at index `i` by moving ``x[i+1..]`` by one position. ## This is an O(n) operation. + ## + ## .. code-block:: nim + ## var i = @[1,2,3,4,5] + ## i.del(2) #=> @[1, 2, 4, 5] template defaultImpl = let xl = x.len for j in i..xl-2: shallowCopy(x[j], x[j+1]) @@ -1373,6 +1385,10 @@ proc delete*[T](x: var seq[T], i: Natural) {.noSideEffect.} = proc insert*[T](x: var seq[T], item: T, i = 0.Natural) {.noSideEffect.} = ## inserts `item` into `x` at position `i`. + ## + ## .. code-block:: nim + ## var i = @[1,2,3,4,5] + ## i.insert(2,4) #=> @[1, 2, 3, 4, 2, 5] template defaultImpl = let xl = x.len setLen(x, xl+1) @@ -1393,6 +1409,12 @@ proc repr*[T](x: T): string {.magic: "Repr", noSideEffect.} ## takes any Nim variable and returns its string representation. It ## works even for complex data graphs with cycles. This is a great ## debugging tool. + ## + ## .. code-block:: nim + ## var s: seq[string] = @["test2","test2"] + ## var i = @[1,2,3,4,5] + ## repr(s) #=> 0x1055eb050[0x1055ec050"test2", 0x1055ec078"test2"] + ## repr(i) #=> 0x1055ed050[1, 2, 3, 4, 5] type ByteAddress* = int From eed1000252444850523aa5ffe7d86782bd48a26a Mon Sep 17 00:00:00 2001 From: JamesP Date: Sat, 26 Sep 2015 08:18:09 +1000 Subject: [PATCH 3/9] add examples to top of module for stringStream and fileStream --- lib/pure/streams.nim | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/lib/pure/streams.nim b/lib/pure/streams.nim index 8aa8d35d88..3be47744ca 100644 --- a/lib/pure/streams.nim +++ b/lib/pure/streams.nim @@ -11,6 +11,26 @@ ## the `FileStream` and the `StringStream` which implement the stream ## interface for Nim file objects (`File`) and strings. Other modules ## may provide other implementations for this standard stream interface. +## +## Examples: +## +## .. code-block:: Nim +## +## import streams +## var +## ss = newStringStream("""The first line +## the second line +## the third line""") +## line = "" +## while ss.readLine(line): +## echo line +## ss.close() +## +## var fs = newFileStream("somefile.txt", fmRead) +## if not isNil(fs): +## while fs.readLine(line): +## echo line +## fs.close() include "system/inclrtl" From ff9a3d39d76602c929fcadb453a2ae2ca79559bc Mon Sep 17 00:00:00 2001 From: JamesP Date: Sat, 26 Sep 2015 08:18:42 +1000 Subject: [PATCH 4/9] add default file mode to newFileStream() --- lib/pure/streams.nim | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/pure/streams.nim b/lib/pure/streams.nim index 3be47744ca..406a0ec6e8 100644 --- a/lib/pure/streams.nim +++ b/lib/pure/streams.nim @@ -391,7 +391,7 @@ when not defined(js): result.writeDataImpl = fsWriteData result.flushImpl = fsFlush - proc newFileStream*(filename: string, mode: FileMode): FileStream = + proc newFileStream*(filename: string, mode: FileMode = fmRead): FileStream = ## creates a new stream from the file named `filename` with the mode `mode`. ## If the file cannot be opened, nil is returned. See the `system ## `_ module for a list of available FileMode enums. From e0707797a52f68423b2cc9c287d6356366d41c56 Mon Sep 17 00:00:00 2001 From: JamesP Date: Sat, 26 Sep 2015 08:34:59 +1000 Subject: [PATCH 5/9] add test for newFileStream() opening a missing file --- tests/stdlib/tstreams2.nim | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 tests/stdlib/tstreams2.nim diff --git a/tests/stdlib/tstreams2.nim b/tests/stdlib/tstreams2.nim new file mode 100644 index 0000000000..b3e957261b --- /dev/null +++ b/tests/stdlib/tstreams2.nim @@ -0,0 +1,14 @@ +discard """ + test newFileStream opening a missing file returns nil + file: "tstreams2.nim" + output: 'fs is: nil' +""" +import streams +var + fs = newFileStream("amissingfile.txt") + line = "" +echo "fs is: ",repr(fs) +if not isNil(fs): + while fs.readLine(line): + echo line + fs.close() From ca9845dcc01c934256c8d679eb5c533bc7c9f098 Mon Sep 17 00:00:00 2001 From: Jakob Oesterling Date: Sat, 26 Sep 2015 01:08:49 +0200 Subject: [PATCH 6/9] fixed wrong examples --- lib/system.nim | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/system.nim b/lib/system.nim index 784e072a89..59d0d04b78 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -728,7 +728,7 @@ proc ord*[T](x: T): int {.magic: "Ord", noSideEffect.} ## returns the internal int value of an ordinal value ``x``. ## ## .. code-block:: nim - ## card('A') #=> 65 + ## ord('A') #=> 65 proc chr*(u: range[0..255]): char {.magic: "Chr", noSideEffect.} ## converts an int in the range 0..255 to a character. @@ -1371,7 +1371,7 @@ proc delete*[T](x: var seq[T], i: Natural) {.noSideEffect.} = ## ## .. code-block:: nim ## var i = @[1,2,3,4,5] - ## i.del(2) #=> @[1, 2, 4, 5] + ## i.delete(2) #=> @[1, 2, 4, 5] template defaultImpl = let xl = x.len for j in i..xl-2: shallowCopy(x[j], x[j+1]) From 772c25bfe8424bb187690ee0959375cd5027d897 Mon Sep 17 00:00:00 2001 From: JamesP Date: Sun, 27 Sep 2015 15:49:40 +1000 Subject: [PATCH 7/9] fix discard output: section --- tests/stdlib/tstreams2.nim | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tests/stdlib/tstreams2.nim b/tests/stdlib/tstreams2.nim index b3e957261b..90102d8e3a 100644 --- a/tests/stdlib/tstreams2.nim +++ b/tests/stdlib/tstreams2.nim @@ -1,7 +1,6 @@ discard """ - test newFileStream opening a missing file returns nil file: "tstreams2.nim" - output: 'fs is: nil' + output: '''fs is: nil''' """ import streams var From 8b230ec0858f572a171f570191e94f219d97aeb3 Mon Sep 17 00:00:00 2001 From: JamesP Date: Sun, 27 Sep 2015 16:21:47 +1000 Subject: [PATCH 8/9] minor fix - remove comments from discard section so koch test doesn't complain --- tests/stdlib/tmemfiles1.nim | 1 - tests/stdlib/tmemfiles2.nim | 1 - 2 files changed, 2 deletions(-) diff --git a/tests/stdlib/tmemfiles1.nim b/tests/stdlib/tmemfiles1.nim index f7f39f5bc7..8b66dfcc16 100644 --- a/tests/stdlib/tmemfiles1.nim +++ b/tests/stdlib/tmemfiles1.nim @@ -1,5 +1,4 @@ discard """ - test that closing a closed file is ignored (no error raised) file: "tmemfiles1.nim" """ import memfiles, os diff --git a/tests/stdlib/tmemfiles2.nim b/tests/stdlib/tmemfiles2.nim index 04ae8429f6..28af3296a7 100644 --- a/tests/stdlib/tmemfiles2.nim +++ b/tests/stdlib/tmemfiles2.nim @@ -1,5 +1,4 @@ discard """ - test creating/reading/writing/changing memfiles file: "tmemfiles2.nim" output: '''Full read size: 20 Half read size: 10 Data: Hello''' From bb7604c06fb2adc6999d47fdfcbf9cf2979bef9e Mon Sep 17 00:00:00 2001 From: Dominik Picheta Date: Sun, 27 Sep 2015 14:18:03 +0100 Subject: [PATCH 9/9] Improved "Execution of an external program failed" message. --- compiler/extccomp.nim | 10 ++++++---- compiler/msgs.nim | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/compiler/extccomp.nim b/compiler/extccomp.nim index 02198d06e3..29aa03c94c 100644 --- a/compiler/extccomp.nim +++ b/compiler/extccomp.nim @@ -474,7 +474,7 @@ proc execWithEcho(cmd: string, msg = hintExecuting): int = proc execExternalProgram*(cmd: string, msg = hintExecuting) = if execWithEcho(cmd, msg) != 0: - rawMessage(errExecutionOfProgramFailed, "") + rawMessage(errExecutionOfProgramFailed, cmd) proc generateScript(projectFile: string, script: Rope) = let (dir, name, ext) = splitFile(projectFile) @@ -680,7 +680,7 @@ proc callCCompiler*(projectfile: string) = if gNumberOfProcessors <= 1: for i in countup(0, high(cmds)): res = execWithEcho(cmds[i]) - if res != 0: rawMessage(errExecutionOfProgramFailed, []) + if res != 0: rawMessage(errExecutionOfProgramFailed, cmds[i]) elif optListCmd in gGlobalOptions or gVerbosity > 1: res = execProcesses(cmds, {poEchoCmd, poUsePath, poParentStreams}, gNumberOfProcessors) @@ -692,9 +692,11 @@ proc callCCompiler*(projectfile: string) = gNumberOfProcessors) if res != 0: if gNumberOfProcessors <= 1: - rawMessage(errExecutionOfProgramFailed, []) + rawMessage(errExecutionOfProgramFailed, cmds.join()) else: - rawMessage(errGenerated, " execution of an external program failed; " & + rawMessage(errGenerated, + " execution of an external compiler program failed: " & + cmds.join() & "; " & "rerun with --parallelBuild:1 to see the error message") if optNoLinking notin gGlobalOptions: # call the linker: diff --git a/compiler/msgs.nim b/compiler/msgs.nim index c5bc44664c..28f85ac004 100644 --- a/compiler/msgs.nim +++ b/compiler/msgs.nim @@ -203,7 +203,7 @@ const errUseQualifier: "ambiguous identifier: \'$1\' -- use a qualifier", errTypeExpected: "type expected", errSystemNeeds: "system module needs \'$1\'", - errExecutionOfProgramFailed: "execution of an external program failed", + errExecutionOfProgramFailed: "execution of an external program failed: '$1'", errNotOverloadable: "overloaded \'$1\' leads to ambiguous calls", errInvalidArgForX: "invalid argument for \'$1\'", errStmtHasNoEffect: "statement has no effect",