From 822158525bda42edb4f3995afeab5f39c1f049e9 Mon Sep 17 00:00:00 2001 From: Jean Privat Date: Fri, 16 Aug 2013 06:04:51 -0400 Subject: [PATCH] lib: improve examples in documentation Instead of # bla # -> res Use # assert bla == res Signed-off-by: Jean Privat --- lib/for_abuse.nit | 6 ++--- lib/html.nit | 11 +++++---- lib/pipeline.nit | 20 ++++++++-------- lib/standard/collection/abstract_collection.nit | 28 ++++++++++++----------- lib/standard/collection/array.nit | 21 +++++++++-------- lib/standard/file.nit | 16 ++++++------- lib/standard/kernel.nit | 4 ++-- lib/standard/string.nit | 28 +++++++++++------------ lib/standard/string_search.nit | 10 ++++---- 9 files changed, 75 insertions(+), 69 deletions(-) diff --git a/lib/for_abuse.nit b/lib/for_abuse.nit index 1e06ec3..9ecaf63 100644 --- a/lib/for_abuse.nit +++ b/lib/for_abuse.nit @@ -140,7 +140,7 @@ redef class Array[E] # # var a = [1, 3, 2] # for q in a do q.res = q.a <=> q.b - # print a # => 123 + # assert print a == 123 # # Implements a sort by permutation. fun sort_fa: ForAbuser[CompareQuery[E]] @@ -154,8 +154,8 @@ end # Open and read a file trough a `for` abuse. # The abuse just ensures that the file is closed after the reading. # -# for f in file_open(path) do -# print path.read_line +# for f in file_open("/etc/issue") do +# print f.read_line # end # f is automatically closed here fun file_open(path: String): ForAbuser[IFStream] do diff --git a/lib/html.nit b/lib/html.nit index ae473d9..cbc093e 100644 --- a/lib/html.nit +++ b/lib/html.nit @@ -158,7 +158,7 @@ class HTMLTag # Clear all child and set the text of element # var p = new HTMLTag("p") # p.text("Hello World!") - # p.html # -> "

Hello World!

" + # assert p.html == "

Hello World!

" # Text is escaped see: `standard::String::html_escape` fun text(txt: String): HTMLTag do @@ -169,8 +169,10 @@ class HTMLTag # Append text to element # var p = new HTMLTag("p") - # p.append("Hello").add(new HTMLTag("br")).append("World!") - # p.html # -> "

Hello
World!

" + # p.append("Hello") + # p.add(new HTMLTag("br")) + # p.append("World!") + # assert p.html == "

Hello
World!

" # Text is escaped see: standard::String::html_escape fun append(txt: String): HTMLTag do add(new HTMLRaw(txt.html_escape)) @@ -179,7 +181,8 @@ class HTMLTag # Append raw HTML to element # var p = new HTMLTag("p") - # p.append("Hello").add_raw_html("") + # p.append("Hello") + # p.add_raw_html("") # p.html #- "

Hello

" # Note: the HTML in insered as it, no verification is done fun add_raw_html(txt: String): HTMLTag do diff --git a/lib/pipeline.nit b/lib/pipeline.nit index 35e26c3..81d68c5 100644 --- a/lib/pipeline.nit +++ b/lib/pipeline.nit @@ -30,7 +30,7 @@ redef interface Collection[E] # SEE: `sort_with` for details # REQUIRE: self isa Iterator[Comparable] # - # [1,3,2].sort_filter #=> [1,2,3] + # assert [1,3,2].sort_filter.to_a == [1,2,3] fun sort_filter: Collection[E] do assert self isa Collection[Comparable] @@ -55,7 +55,7 @@ redef interface Collection[E] # Important: rely on `==` and `hash` # Important: require O(m) in memory, where m is the total number of uniq items. # - # [1,2,1,1,1,3,2].uniq #=> [1,2,3] + # assert [1,2,1,1,1,3,2].uniq.to_a == [1,2,3] # # REQUIRE: self isa Iterator[Object] fun uniq: Collection[E] @@ -68,7 +68,7 @@ redef interface Collection[E] # # Important: rely on `==`. # - # [1,2,1,1,1,3,2].seq_uniq #=> [1,2,1,3,2] + # assert [1,2,1,1,1,3,2].seq_uniq.to_a == [1,2,1,3,2] fun seq_uniq: Collection[E] do return new PipeSeqUniq[E](self) @@ -76,7 +76,7 @@ redef interface Collection[E] # The view of two combined collections. # - # ([1..20[ + [20..40[) #=> [1..40[ + # assert ([1..20[ + [20..40[).to_a == ([1..40[).to_a fun +(other: Collection[E]): Collection[E] do return new PipeJoin[E](self, other) @@ -84,7 +84,7 @@ redef interface Collection[E] # Alternate each item with `e`. # - # [1,2,3].alternate(0) #=> [1,0,2,0,3] + # assert [1,2,3].alternate(0).to_a == [1,0,2,0,3] fun alternate(e: E): Collection[E] do return new PipeAlternate[E](self, e) @@ -92,7 +92,7 @@ redef interface Collection[E] # Filter: reject a given `item`. # - # [1,1,2,1,3].skip(1) #=> [2,3] + # assert [1,1,2,1,3].skip(1).to_a == [2,3] fun skip(item: E): Collection[E] do return new PipeSkip[E](self, item) @@ -100,7 +100,7 @@ redef interface Collection[E] # Filter: keep only the first `length` items. # - # [1,2,3,4,5].head(2) #=> [1,2] + # assert [1,2,3,4,5].head(2).to_a == [1,2] fun head(length: Int): Collection[E] do return new PipeHead[E](self, length) @@ -108,7 +108,7 @@ redef interface Collection[E] # Filter: reject the first `length` items. # - # [1,2,3,4,5].skip_head(2) #=> [3,4,5] + # assert [1,2,3,4,5].skip_head(2).to_a == [3,4,5] # # ENSURE: self == return fun skip_head(length: Int): Collection[E] @@ -118,7 +118,7 @@ redef interface Collection[E] # Filter: keep only the last `length` items. # - # [1,2,3,4,5].tail(2) #=> [4,5] + # assert [1,2,3,4,5].tail(2).to_a == [4,5] # # Important: require O(length) in memory fun tail(length: Int): Collection[E] @@ -128,7 +128,7 @@ redef interface Collection[E] # Filter: reject the last `length` items. # - # [1,2,3,4,5].skip_tail(2) #=> [1,2,3] + # assert [1,2,3,4,5].skip_tail(2).to_a == [1,2,3] # # Important: require O(length) in memory fun skip_tail(length: Int): Collection[E] diff --git a/lib/standard/collection/abstract_collection.nit b/lib/standard/collection/abstract_collection.nit index 8d76839..cc58acd 100644 --- a/lib/standard/collection/abstract_collection.nit +++ b/lib/standard/collection/abstract_collection.nit @@ -203,12 +203,12 @@ end # Abstract sets. # # Set contains contains only one element with the same value (according to ==). -# var s: Set[E] +# var s: Set[String] = new ArraySet[String] # var a = "Hello" # var b = "Hel" + "lo" # # ... # s.add(a) -# s.has(b) # --> true +# assert s.has(b) == true interface Set[E: Object] super SimpleCollection[E] @@ -271,7 +271,7 @@ interface MapRead[K: Object, E] fun keys: Collection[K] is abstract # Is there no item in the collection? - fun is_empty: Bool is abstract + fun is_empty: Bool is abstract # Number of items in the collection. fun length: Int is abstract @@ -281,23 +281,25 @@ end # # The main operator over maps is []. # -# var map: Map[U, V] +# var map: Map[String, Int] = new ArrayMap[String, Int] # # ... -# map[u1] = v1 # Associate 'v1' to 'u1' -# map[u2] = v2 # Associate 'v2' to 'u2' -# print map[u1] # -> v1 -# print map[u2] # -> v2 +# map["one"] = 1 # Associate 'one' to '1' +# map["two"] = 2 # Associate 'two' to '2' +# assert map["one"] == 1 +# assert map["two"] == 2 # # Instances of maps can be used with the for structure # -# for key, value in map do # things with `key` and `value` +# for key, value in map do +# assert (key == "one" and value == 1) or (key == "two" and value == 2) +# end # # The keys and values in the map can also be manipulated directly with the `keys` and `values` methods. # -# map.keys.has(u1) # -> true -# map.keys.has(u3) # -> false -# map.values.has(v1) # -> true -# map.values.has(v3) # -> false +# assert map.keys.has("one") == true +# assert map.keys.has("tree") == false +# assert map.values.has(1) == true +# assert map.values.has(3) == false # interface Map[K: Object, E] super MapRead[K, E] diff --git a/lib/standard/collection/array.nit b/lib/standard/collection/array.nit index ecb29be..23fcf5f 100644 --- a/lib/standard/collection/array.nit +++ b/lib/standard/collection/array.nit @@ -97,7 +97,7 @@ abstract class AbstractArrayRead[E] # Return a new array that is the reverse of `self` # - # [1,2,3].reversed # -> [3, 2, 1] + # assert [1,2,3].reversed == [3, 2, 1] fun reversed: Array[E] do var cmp = _length @@ -114,7 +114,7 @@ abstract class AbstractArrayRead[E] # var a = [1, 2, 3, 4] # var b = [10, 20, 30, 40, 50] # a.copy_to(1, 2, b, 2) - # b # -> [10, 20, 2, 3, 50] + # assert b == [10, 20, 2, 3, 50] protected fun copy_to(start: Int, len: Int, dest: AbstractArray[E], new_start: Int) do # TODO native one @@ -201,7 +201,7 @@ abstract class AbstractArray[E] # # var a= [10, 20, 30, 40] # a.insert(100, 2) - # a # -> [10, 20, 100, 30, 40] + # assert a == [10, 20, 100, 30, 40] fun insert(item: E, pos: Int) do enlarge(length + 1) @@ -241,7 +241,7 @@ abstract class AbstractArray[E] # # var a = [10, 20, 30, 40] # a.swap_at(1, 3) - # a # -> [10, 40, 30, 20] + # assert a == [10, 40, 30, 20] fun swap_at(a: Int,b: Int) do var e = self[a] @@ -253,12 +253,13 @@ end # Resizable one dimension array of objects. # # Arrays have a literal representation. -# a = [12, 32, 8] -# is equivalent with: -# a = new Array[Int] -# a.push(12) -# a.push(32) -# a.push(8) +# var a = [12, 32, 8] +# # is equivalent with: +# var b = new Array[Int] +# b.push(12) +# b.push(32) +# b.push(8) +# assert a == b class Array[E] super AbstractArray[E] super ArrayCapable[E] diff --git a/lib/standard/file.nit b/lib/standard/file.nit index 0d8bf2e..88d0adc 100644 --- a/lib/standard/file.nit +++ b/lib/standard/file.nit @@ -241,10 +241,10 @@ redef class String # * no I/O access is performed # * the validity of the path is not checked # - # "some/./complex/../../path/from/../to/a////file//".simplify_path # -> "path/to/a/file" - # "../dir/file".simplify_path # -> "../dir/file" - # "dir/../../".simplify_path # -> ".." - # "//absolute//path/".simplify_path # -> "/absolute/path" + # assert "some/./complex/../../path/from/../to/a////file//".simplify_path == "path/to/a/file" + # assert "../dir/file".simplify_path == "../dir/file" + # assert "dir/../../".simplify_path == ".." + # assert "//absolute//path/".simplify_path == "/absolute/path" fun simplify_path: String do var a = self.split_with("/") @@ -266,10 +266,10 @@ redef class String # Using a standard "{self}/{path}" does not work when `self` is the empty string. # This method ensure that the join is valid. # - # "hello".join_path("world") # -> "hello/world" - # "hel/lo".join_path("wor/ld") # -> "hel/lo/wor/ld" - # "".join_path("world") # -> "world" - # "/hello".join_path("/world") # -> "/world" + # assert "hello".join_path("world") == "hello/world" + # assert "hel/lo".join_path("wor/ld") == "hel/lo/wor/ld" + # assert "".join_path("world") == "world" + # assert "/hello".join_path("/world") == "/world" # # Note: you may want to use `simplify_path` on the result # diff --git a/lib/standard/kernel.nit b/lib/standard/kernel.nit index dea9da5..ac3d5b6 100644 --- a/lib/standard/kernel.nit +++ b/lib/standard/kernel.nit @@ -160,8 +160,8 @@ interface Discrete # The distance between self and d. # - # 10.distance(15) # --> 5 - # 'Z'.distance('A') # --> 25 + # assert 10.distance(15) == 5 + # assert 'Z'.distance('A') == 25 fun distance(d: OTHER): Int do var cursor: OTHER diff --git a/lib/standard/string.nit b/lib/standard/string.nit index 8c69ad5..b136c58 100644 --- a/lib/standard/string.nit +++ b/lib/standard/string.nit @@ -36,10 +36,10 @@ abstract class AbstractString # Create a substring. # - # "abcd".substring(1, 2) # --> "bc" - # "abcd".substring(-1, ) # --> "a" - # "abcd".substring(1, 0) # --> "" - # "abcd".substring(2, 5) # --> "cd" + # assert "abcd".substring(1, 2) == "bc" + # assert "abcd".substring(-1, ) == "a" + # assert "abcd".substring(1, 0) == "" + # assert "abcd".substring(2, 5) == "cd" # # A `from` index < 0 will be replaced by 0. # Unless a `count` value is > 0 at the same time. @@ -64,9 +64,9 @@ abstract class AbstractString # Create a substring from `self` beginning at the `from` position # - # "abcd".substring_from(1) # --> "bcd" - # "abcd".substring_from(-1) # --> "abcd" - # "abcd".substring_from(2) # --> "cd" + # assert "abcd".substring_from(1) == "bcd" + # assert "abcd".substring_from(-1) == "abcd" + # assert "abcd".substring_from(2) == "cd" # # As with substring, a `from` index < 0 will be replaced by 0 fun substring_from(from: Int): String @@ -77,8 +77,8 @@ abstract class AbstractString # Does self have a substring `str` starting from position `pos`? # - # "abcd".has_substring("bc",1) # --> true - # "abcd".has_substring("bc",2) # --> false + # assert "abcd".has_substring("bc",1) == true + # assert "abcd".has_substring("bc",2) == false fun has_substring(str: String, pos: Int): Bool do var itsindex = str.length - 1 @@ -98,14 +98,14 @@ abstract class AbstractString # Is this string prefixed by `prefix`? # - # "abc".has_prefix("abcd") # --> true - # "bc".has_prefix("abcd") # --> false + # assert "abcd".has_prefix("ab") == true + # assert "abcbc".has_prefix("bc") == false fun has_prefix(prefix: String): Bool do return has_substring(prefix,0) # Is this string suffixed by `suffix`? # - # "abcd".has_suffix("abc") # --> false - # "abcd".has_suffix("bcd") # --> true + # assert "abcd".has_suffix("abc") == false + # assert "abcd".has_suffix("bcd") == true fun has_suffix(suffix: String): Bool do return has_substring(suffix, length - suffix.length) # If `self` contains only digits, return the corresponding integer @@ -453,7 +453,7 @@ class String # The comparison between two strings is done on a lexicographical basis # - # "aa" < "b" # => true + # assert "aa" < "b" == true redef fun <(other) do if self.object_id == other.object_id then return false diff --git a/lib/standard/string_search.nit b/lib/standard/string_search.nit index 8249bac..6f59bac 100644 --- a/lib/standard/string_search.nit +++ b/lib/standard/string_search.nit @@ -295,12 +295,12 @@ redef class String # for i in "hello world".search_all('o') do # a.add(i.from) # end - # a # -> [4, 7] + # assert a == [4, 7] fun search_all(p: Pattern): Array[Match] do return p.search_all_in(self) # Split `self` using `p` as separator. # - # "hello world".split('o') # -> ["hell", " w", "rld"] + # assert "hello world".split('o') == ["hell", " w", "rld"] fun split(p: Pattern): Array[String] do var matches = p.split_in(self) @@ -314,8 +314,8 @@ redef class String # Replace all occurences of a pattern with a string # - # "hlelo".replace("le", "el") # -> "hello" - # "hello".replace('l', "") # -> "heo" + # assert "hlelo".replace("le", "el") == "hello" + # assert "hello".replace('l', "") == "heo" fun replace(p: Pattern, string: String): String do return self.split_with(p).join(string) @@ -323,7 +323,7 @@ redef class String # Escape the four characters < > & and " with their html counterpart # - # "a&b->\"x\"".html_escape # -> "a&b->"x"" + # assert "a&b->\"x\"".html_escape == "a&b->"x"" fun html_escape: String do var ret = self -- 1.7.9.5