Skip to content

Commit 6f10987

Browse files
authored
Merge pull request #1867 from RickBarretto/update-documentation
Update documentation
2 parents 1feabea + 6c8e7f8 commit 6f10987

File tree

9 files changed

+231
-17
lines changed

9 files changed

+231
-17
lines changed

src/library/Arithmetic.nim

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,7 @@ proc defineLibrary*() =
134134
returns = {Floating,Rational,Quantity,Object,Nothing},
135135
example = """
136136
print fdiv 5 2 ; 2.5
137+
print 5 // 2 ; 2.5
137138
..........
138139
a: 6
139140
fdiv 'a 3 ; a: 2.0

src/library/Collections.nim

Lines changed: 63 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -442,6 +442,14 @@ proc defineLibrary*() =
442442
AGE: 35
443443
]
444444
; e: [name:John, surname:Doe, age:35]
445+
..........
446+
entity: "EU"
447+
448+
location: dictionary.with: [entity][
449+
country: "Spain"
450+
]
451+
452+
print location\entity ; => EU
445453
""":
446454
#=======================================================
447455
var dict: ValueDict
@@ -1403,6 +1411,34 @@ proc defineLibrary*() =
14031411
},
14041412
returns = {Range},
14051413
example = """
1414+
; range of :integers
1415+
1416+
range 0 5 ; 0..5
1417+
0..5 ; 0..5
1418+
@0..5 ; [0 1 2 3 4 5]
1419+
..........
1420+
; range of :chars
1421+
1422+
'a'..'e' ; 'a'..'e'
1423+
@'a'..'e' ; [a b c d e]
1424+
..........
1425+
; range with steps
1426+
1427+
@range.step: 2 1 5 ; [1 3 5]
1428+
..........
1429+
; iterate a range
1430+
1431+
0..5 | loop 'i -> print ~"|i|. hello"
1432+
; 0. hello
1433+
; 1. hello
1434+
; 2. hello
1435+
; 3. hello
1436+
; 4. hello
1437+
; 5. hello
1438+
..........
1439+
; check bounds
1440+
1441+
in? 5 0..10 ; => true
14061442
""":
14071443
#=======================================================
14081444
var limX: int
@@ -1466,19 +1502,26 @@ proc defineLibrary*() =
14661502
example = """
14671503
remove "hello" "l" ; => "heo"
14681504
print "hello" -- "l" ; heo
1505+
remove [1 2 3 4] 4 ; => [1 2 3]
14691506
..........
14701507
str: "mystring"
14711508
remove 'str "str"
14721509
print str ; mying
14731510
..........
1511+
remove.key #[name: "John" surname: "Doe"] "surname" ; => #[name: "John"]
1512+
..........
14741513
print remove.once "hello" "l"
14751514
; helo
14761515
14771516
; Remove each element of given block from collection once
14781517
remove.once [1 2 [1 2] 3 4 1 2 [1 2] 3 4] [1 2]
14791518
; [[1 2] 3 4 1 2 [1 2] 3 4]
14801519
..........
1481-
remove [1 2 3 4] 4 ; => [1 2 3]
1520+
remove.index: 2 "Ruby" "u" ; => Rby
1521+
remove.index: 2 "Ruby" "a" ; => Ruby
1522+
..........
1523+
remove.prefix "--empty --flag" "--" ; => "empty --flag"
1524+
remove.suffix "test.txt file.txt" ".txt" ; => "test.txt file"
14821525
..........
14831526
remove.instance [1 [6 2] 5 3 [6 2] 4 5 6] [6 2] ; => [1 5 3 4 5 6]
14841527
remove.instance.once [1 [6 2] 5 3 [6 2] 4 5 6] [6 2] ; => [1 5 3 [6 2] 4 5 6]
@@ -2013,6 +2056,16 @@ proc defineLibrary*() =
20132056
; 1 : Urgent!
20142057
; 2 : Important
20152058
; 3 : Low priority
2059+
..........
2060+
spanishWords: ["uno","dos","tres","Uno","perversión","ábaco","abismo", "aberración"]
2061+
sort.as: 'es spanishWords
2062+
; => ["ábaco" "aberración" "abismo" "dos" "perversión" "tres" "uno" "Uno"]
2063+
..........
2064+
sort.sensitive ["c" "C" "CoffeeScript" "nim" "Arturo" "coffeescript" "arturo" "Nim"]
2065+
; => ["Arturo" "C" "CoffeeScript" "Nim" "arturo" "c" "coffeescript" "nim"]
2066+
..........
2067+
sort.values #[ name: "John" surname: "Doe" age: 35 income: 5000]
2068+
; => #[age: 35 income: 5000 surname: "Doe" name: "John" ]
20162069
""":
20172070
#=======================================================
20182071
var sortOrdering = SortOrder.Ascending
@@ -2180,6 +2233,12 @@ proc defineLibrary*() =
21802233
split "hello" ; => [`h` `e` `l` `l` `o`]
21812234
..........
21822235
split.words "hello world" ; => ["hello" "world"]
2236+
split.by: "," "hello,world" ; => ["hello" "world"]
2237+
split.lines "hello\nworld" ; => ["hello" "world"]
2238+
split.path "/usr/bin" ; => ["usr" "bin"]
2239+
2240+
; windows only:
2241+
split.path "\\usr\\bin" ; => ["usr" "bin"]
21832242
..........
21842243
split.every: 2 "helloworld"
21852244
; => ["he" "ll" "ow" "or" "ld"]
@@ -2519,6 +2578,8 @@ proc defineLibrary*() =
25192578
arr: [1 2 4 1 3 2]
25202579
unique 'arr
25212580
print arr ; 1 2 4 3
2581+
..........
2582+
unique.id "user-" ; => user-67915b7a409e222b2f9a6bed
25222583
""":
25232584
#=======================================================
25242585
if (hadAttr("id")):
@@ -2554,8 +2615,7 @@ proc defineLibrary*() =
25542615
surname: "Doe"
25552616
]
25562617
2557-
values user
2558-
=> ["John" "Doe"]
2618+
values user ; => ["John" "Doe"]
25592619
""":
25602620
#=======================================================
25612621
if xKind == Block:

src/library/Colors.nim

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,8 @@ proc defineLibrary*() =
207207
palette.triad #red ; => [#FF0000 #00FF00 #0000FF]
208208
palette.tetrad #red ; => [#FF0000 #80FF00 #00FFFF #7F00FF]
209209
..........
210+
palette.split #red ; => [#FF0000 #CCFF00 #0066FF]
211+
..........
210212
palette.monochrome #red
211213
; => [#FF0000 #D40000 #AA0000 #7F0000 #550000 #2A0000]
212214

src/library/Converters.nim

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,25 @@ proc defineLibrary*() =
8484
print as.binary 123 ; 1111011
8585
print as.octal 123 ; 173
8686
print as.hex 123 ; 7b
87+
..........
88+
inspect as.agnostic [hello world]
89+
; [ :block
90+
; hello :literal
91+
; world :literal
92+
; ]
93+
..........
94+
example: "Hello, world"
95+
example ; => Hello, world
96+
as.code example ; => "Hello, world"
97+
..........
98+
as.code #[name: "John" surname: "Doe"]
99+
; => #[name: "John" surname: "Doe" ]
100+
101+
as.code.pretty #[name: "John" surname: "Doe"]
102+
; => #[
103+
; name: "John"
104+
; surname: "Doe"
105+
; ]
87106
""":
88107
#=======================================================
89108
if (hadAttr("binary")):

src/library/Core.nim

Lines changed: 99 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -619,9 +619,55 @@ proc defineLibrary*() =
619619
"all" : ({Logical},"export everything, regardless of whether it's been marked as public (makes sense only for modules)")
620620
},
621621
returns = {Nothing},
622-
# TODO(Core\export) add documentation example
623-
# labels: library, documentation, easy
624622
example = """
623+
greeting: module [
624+
greet: method.public [user :string][
625+
print ~"Hello, |user|!"
626+
]
627+
]
628+
629+
export greeting!
630+
631+
greet "Anonymous" ; Hello, Anonymous!
632+
..........
633+
; You can't use private methods
634+
greeting: module [
635+
greet: method [user :string][
636+
print ~"Bye, bye, |user|!"
637+
]
638+
]
639+
640+
export greeting!
641+
642+
greet "Anonymous"
643+
; Cannot resolve requested value
644+
;
645+
; Identifier not found:
646+
; greet
647+
;
648+
; ┃ File: example.art
649+
; ┃ Line: 9
650+
; ┃
651+
; ┃ 7 ║ ]
652+
; ┃ 8 ║
653+
; ┃ 9 ║► export greeting!
654+
; ┃ 10 ║
655+
; ┃ 11 ║ greet "Anonymous"
656+
;
657+
; Hint: Perhaps you meant... greeting ?
658+
; or... repeat ?
659+
; or... greater? ?
660+
..........
661+
; You can export private functions using the `.all` attribute
662+
greeting: module [
663+
greet: method [user :string][
664+
print ~"Bye, bye, |user|!"
665+
]
666+
]
667+
668+
export.all greeting!
669+
670+
greet "Anonymous" ; Bye, bye, Anonymous!
625671
""":
626672
#=======================================================
627673
let exportAll = hadAttr("all")
@@ -1175,6 +1221,57 @@ proc defineLibrary*() =
11751221
# TODO(Core\module) add documentation example
11761222
# labels: library, documentation, easy
11771223
example = """
1224+
ui: module [
1225+
1226+
namedRule: method [title :string width :integer][
1227+
title: ~" |title| "
1228+
pad.center.with: '=' title width
1229+
]
1230+
1231+
section: method.public [title :string content :string width :integer][
1232+
~{
1233+
|\namedRule title width|
1234+
|content|
1235+
|\namedRule title width|
1236+
}
1237+
]
1238+
]
1239+
1240+
export ui!
1241+
1242+
print section "Hello" "World" 50
1243+
; ===================== Hello ======================
1244+
; World
1245+
; ===================== Hello ======================
1246+
print set? 'ui ; true
1247+
print set? 'namedRule ; false
1248+
print set? 'section ; true
1249+
..........
1250+
ui: [
1251+
1252+
init: method [symbol :char][
1253+
\symbol: symbol
1254+
]
1255+
1256+
namedRule: method [title :string width :integer][
1257+
title: ~" |title| "
1258+
pad.center.with: \symbol title width
1259+
]
1260+
1261+
section: method.public [title :string content :string width :integer][
1262+
~{
1263+
|\namedRule title width|
1264+
|content|
1265+
|\namedRule title width|
1266+
}
1267+
]
1268+
]
1269+
1270+
export module.with: ['~'] ui!
1271+
print section "Example" "This is an example" 40
1272+
; ~~~~~~~~~~~~~~~ Example ~~~~~~~~~~~~~~~~
1273+
; This is an example
1274+
; ~~~~~~~~~~~~~~~ Example ~~~~~~~~~~~~~~~~
11781275
""":
11791276
#=======================================================
11801277
var definitions: ValueDict = newOrderedTable[string,Value]()

src/library/Net.nim

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -382,7 +382,7 @@ proc defineLibrary*() =
382382
"routes" : {Block, Function}
383383
},
384384
attrs = {
385-
"port" : ({Integer},"use given port"),
385+
"port" : ({Integer},"use given port. Default: 18966"),
386386
"silent" : ({Logical},"don't print info log"),
387387
"chrome" : ({Logical},"open in Chrome windows as an app")
388388
},

src/library/Strings.nim

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -366,9 +366,9 @@ proc defineLibrary*() =
366366
str: "hello World, 你好!"
367367
lower 'str ; str: "hello world, 你好!"
368368
..........
369-
ch: `A`
369+
ch: 'A'
370370
lower ch
371-
; => `a`
371+
; => 'a'
372372
""":
373373
#=======================================================
374374
if xKind==String: push(newString(x.s.toLower()))
@@ -904,9 +904,9 @@ proc defineLibrary*() =
904904
str: "hello World, 你好!"
905905
upper 'str ; str: "HELLO WORLD, 你好!"
906906
..........
907-
ch: `a`
907+
ch: 'a'
908908
upper ch
909-
; => `A`
909+
; => 'A'
910910
""":
911911
#=======================================================
912912
if xKind==String: push(newString(x.s.toUpper()))
@@ -974,9 +974,9 @@ proc defineLibrary*() =
974974
attrs = NoAttrs,
975975
returns = {Logical},
976976
example = """
977-
ascii? `d` ; true
977+
ascii? 'd' ; true
978978
..........
979-
ascii? `😀` ; false
979+
ascii? '😀' ; false
980980
981981
ascii? "hello world" ; true
982982
ascii? "Hællø wœrld" ; false

src/library/System.nim

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,41 @@ proc defineLibrary*() =
199199
200200
split.lines execute "ls"
201201
; => ["tests" "var" "data.txt"]
202+
......................
203+
execute.args: ["-s"] "ls"
204+
; => total 15
205+
; 0 aoc
206+
; 0 architectures
207+
; 4 bundle
208+
; 0 cave
209+
; 4 cmd.c
210+
; 1 expr.art
211+
; 0 galilee
212+
; 4 generic_klist.c
213+
; 1 jquery.js
214+
; 0 shell
215+
; 1 test.art
216+
......................
217+
execute.code "ls"
218+
; => [output:aoc
219+
; architectures
220+
; bundle
221+
; cave
222+
; cmd.c
223+
; expr.art
224+
; galilee
225+
; generic_klist.c
226+
; jquery.js
227+
; shell
228+
; test.art
229+
; code:0]
230+
......................
231+
; This prints the output directly
232+
; And only returns the exit code.
233+
execute.code.directly "ls"
234+
aoc bundle cmd.c galilee jquery.js test.art
235+
architectures cave expr.art generic_klist.c shell
236+
=> 0
202237
""":
203238
#=======================================================
204239
when defined(SAFE): Error_OperationNotPermitted("execute")
@@ -340,7 +375,7 @@ proc defineLibrary*() =
340375
341376
print "done. let's continue..."
342377
..........
343-
print "waiting for 2 seconds
378+
print "waiting for 2 seconds"
344379
345380
pause 2:s ; let's sleep for a while
346381

0 commit comments

Comments
 (0)