From f84ccb6f786b015fa1b5866c379a9993416d7b9b Mon Sep 17 00:00:00 2001 From: Paolo Di Tommaso Date: Wed, 5 Aug 2020 16:56:20 +0200 Subject: [PATCH] Improve docs replacing suscribe{println it} with view() --- docs/operator.rst | 140 ++++++++++++++++++++++------------------------ 1 file changed, 66 insertions(+), 74 deletions(-) diff --git a/docs/operator.rst b/docs/operator.rst index 699dac084b..47b118d7e7 100644 --- a/docs/operator.rst +++ b/docs/operator.rst @@ -56,7 +56,7 @@ begins with ``a``:: Channel .from( 'a', 'b', 'aa', 'bc', 3, 4.5 ) .filter( ~/^a.*/ ) - .subscribe { println it } + .view() :: @@ -70,7 +70,7 @@ are returned:: Channel .from( 'a', 'b', 'aa', 'bc', 3, 4.5 ) .filter( Number ) - .subscribe { println it } + .view() :: @@ -87,7 +87,7 @@ a channel emitting numbers so that the `odd` values are returned:: Channel .from( 1, 2, 3, 4, 5 ) .filter { it % 2 == 1 } - .subscribe { println it } + .view() :: @@ -113,7 +113,7 @@ For example:: Channel .from( 1,1,1,5,7,7,7,3,3 ) .unique() - .subscribe { println it } + .view() :: @@ -129,7 +129,7 @@ For example:: Channel .from(1,3,4,5) .unique { it % 2 } - .subscribe { println it } + .view() :: @@ -193,26 +193,26 @@ a Java `class` type or any boolean `predicate`. For example:: Channel .from( 1, 2, 3 ) .first() - .subscribe { println it } + .view() // emits the first String value: 'a' Channel .from( 1, 2, 'a', 'b', 3 ) .first( String ) - .subscribe { println it } + .view() // emits the first item matching the regular expression: 'aa' Channel .from( 'a', 'aa', 'aaa' ) .first( ~/aa.*/ ) - .subscribe { println it } + .view() // emits the first item for which the predicate evaluates to true: 4 Channel .from( 1,2,3,4,5 ) .first { it > 3 } - .subscribe { println it } + .view() randomSample @@ -270,7 +270,7 @@ The ``last`` operator creates a channel that only returns the last item emitted Channel .from( 1,2,3,4,5,6 ) .last() - .subscribe { println it } + .view() :: @@ -375,7 +375,7 @@ Associative arrays are handled in the same way, so that each array entry is emit Channel.from ( 1, 2, 3 ) .flatMap { it -> [ number: it, square: it*it ] } - .subscribe { println it.key + ': ' + it.value } + .view { it.key + ': ' + it.value } :: @@ -406,7 +406,7 @@ For example:: Channel .from( 1, 2, 3, 4, 5 ) .reduce { a, b -> println "a: $a b: $b"; return a+b } - .subscribe { println "result = $it" } + .view { "result = $it" } It prints the following output:: @@ -443,7 +443,7 @@ For example:: Channel .from('hello','ciao','hola', 'hi', 'bonjour') .groupBy { String str -> str[0] } - .subscribe { println it } + .view() :: @@ -475,7 +475,7 @@ For example:: Channel .from( [1,'A'], [1,'B'], [2,'C'], [3, 'B'], [1,'C'], [2, 'A'], [3, 'D'] ) .groupTuple() - .subscribe { println it } + .view() It prints:: @@ -489,7 +489,7 @@ By default the first entry in the tuple is used a the grouping key. A different Channel .from( [1,'A'], [1,'B'], [2,'C'], [3, 'B'], [1,'C'], [2, 'A'], [3, 'D'] ) .groupTuple(by: 1) - .subscribe { println it } + .view() Grouping by the second value in each tuple the result is:: @@ -552,7 +552,7 @@ the source channel into subsets: Channel .from( 1,2,3,1,2,3 ) .buffer { it == 2 } - .subscribe { println it } + .view() // emitted values [1,2] @@ -570,7 +570,7 @@ the source channel into subsets: Channel .from( 1,2,3,4,5,1,2,3,4,5,1,2 ) .buffer( 2, 4 ) - .subscribe { println it } + .view() // emits bundles starting with '2' and ending with'4' [2,3,4] @@ -583,7 +583,7 @@ the source channel into subsets: Channel .from( 1,2,3,1,2,3,1 ) .buffer( size: 2 ) - .subscribe { println it } + .view() // emitted values [1, 2] @@ -596,7 +596,7 @@ add the parameter ``remainder`` specifying ``true``, for example:: Channel .from( 1,2,3,1,2,3,1 ) .buffer( size: 2, remainder: true ) - .subscribe { println it } + .view() // emitted values [1, 2] @@ -612,7 +612,7 @@ add the parameter ``remainder`` specifying ``true``, for example:: Channel .from( 1,2,3,4,5,1,2,3,4,5,1,2 ) .buffer( size:3, skip:2 ) - .subscribe { println it } + .view() // emitted values [3, 4, 5] @@ -632,7 +632,7 @@ The ``collate`` operator transforms a channel in such a way that the emitted val Channel .from(1,2,3,1,2,3,1) .collate( 3 ) - .subscribe { println it } + .view() :: @@ -646,7 +646,7 @@ If you want to avoid this, specify ``false`` as the second parameter. For exampl Channel .from(1,2,3,1,2,3,1) .collate( 3, false ) - .subscribe { println it } + .view() :: @@ -660,7 +660,7 @@ are collected in tuples. For example:: Channel .from(1,2,3,4) .collate( 3, 1 ) - .subscribe { println it } + .view() :: @@ -723,7 +723,7 @@ is flattened so that each single entry is emitted separately by the resulting ch Channel .from( [1,[2,3]], 4, [5,[6]] ) .flatten() - .subscribe { println it } + .view() :: @@ -847,9 +847,7 @@ text entries. For example:: Channel .from( 'alpha,beta,gamma\n10,20,30\n70,80,90' ) .splitCsv() - .subscribe { row -> - println "${row[0]} - ${row[1]} - ${row[2]}" - } + .view { row -> "${row[0]} - ${row[1]} - ${row[2]}" } The above example shows hows CSV text is parsed and is split into single rows. Values can be accessed by its column index in the row object. @@ -860,9 +858,7 @@ allows you to reference each value by its name, as shown in the following exampl Channel .from( 'alpha,beta,gamma\n10,20,30\n70,80,90' ) .splitCsv(header: true) - .subscribe { row -> - println "${row.alpha} - ${row.beta} - ${row.gamma}" - } + .view { row -> "${row.alpha} - ${row.beta} - ${row.gamma}" } It will print :: @@ -876,9 +872,7 @@ as shown below:: Channel .from( 'alpha,beta,gamma\n10,20,30\n70,80,90' ) .splitCsv(header: ['col1', 'col2', 'col3'], skip: 1 ) - .subscribe { row -> - println "${row.col1} - ${row.col2} - ${row.col3}" - } + .view { row -> "${row.col1} - ${row.col2} - ${row.col3}" } Available parameters: @@ -913,7 +907,7 @@ each:: Channel .fromPath('misc/sample.fa') .splitFasta( by: 10 ) - .subscribe { print it } + .view() .. warning:: By default chunks are kept in memory. When splitting big files specify the parameter ``file: true`` to save the chunks into files in order to not incur in a ``OutOfMemoryException``. See the available parameter table below for details. @@ -930,7 +924,7 @@ required the fields, as shown in the example below:: .fromPath('misc/sample.fa') .splitFasta( record: [id: true, seqString: true ]) .filter { record -> record.id =~ /^ENST0.*/ } - .subscribe { record -> println record.seqString } + .view { record -> record.seqString } .. note:: In this example, the file ``misc/sample.fa`` is split into records containing the ``id`` and the ``seqString`` fields @@ -1058,7 +1052,7 @@ For example:: Channel .fromPath('/some/path/*.txt') .splitText() - .subscribe { print it } + .view() It splits the content of the files with suffix ``.txt``, and prints it line by line. @@ -1082,7 +1076,7 @@ The following example shows how to split text files into chunks of 10 lines and Channel .fromPath('/some/path/*.txt') .splitText( by: 10 ) { it.toUpperCase() } - .subscribe { print it } + .view() .. note:: Text chunks returned by the operator ``splitText`` are always terminated by a ``newline`` character. @@ -1264,7 +1258,7 @@ For example:: ch1 = Channel.from( 1,2,3 ) ch2 = Channel.from( 1,0,0,2,7,8,9,3 ) - ch1 .phase(ch2) .subscribe { println it } + ch1 .phase(ch2) .view() It prints:: @@ -1279,7 +1273,7 @@ as shown in the following example:: ch1 = Channel.from( [sequence: 'aaaaaa', id: 1], [sequence: 'bbbbbb', id: 2] ) ch2 = Channel.from( [val: 'zzzz', id: 3], [val: 'xxxxx', id: 1], [val: 'yyyyy', id: 2]) - ch1 .phase(ch2) { it -> it.id } .subscribe { println it } + ch1 .phase(ch2) { it -> it.id } .view() It prints:: @@ -1293,7 +1287,7 @@ is missing, by specifying the optional parameter ``remainder`` as shown below:: ch1 = Channel.from( 1,0,0,2,5,3 ) ch2 = Channel.from( 1,2,3,4 ) - ch1 .phase(ch2, remainder: true) .subscribe { println it } + ch1 .phase(ch2, remainder: true) .view() It prints:: @@ -1322,7 +1316,7 @@ or the value itself for any other data type. For example:: source = Channel.from( [1, 'alpha'], [2, 'beta'] ) target = Channel.from( [1, 'x'], [1, 'y'], [1, 'z'], [2,'p'], [2,'q'], [2,'t'] ) - source.cross(target).subscribe { println it } + source.cross(target).view() It will output:: @@ -1434,9 +1428,7 @@ For example the following snippet shows how sort the content of the result file Channel .from('Z'..'A') .collectFile(name:'result', sort: true, newLine: true) - .subscribe { - println it.text - } + .view { it.text } It will print:: @@ -1455,7 +1447,7 @@ The following example shows how use a `closure` to collect and sort all sequence .collectFile( name:'result.fa', sort: { it.size() } ) { it.sequence } - .subscribe { println it.text } + .view { it.text } .. warning:: The ``collectFile`` operator to carry out its function need to store in a temporary folder that is @@ -1525,7 +1517,7 @@ For example:: b = Channel.from(1,2,3) c = Channel.from('p','q') - c.concat( b, a ).subscribe { println it } + c.concat( b, a ).view() It will output:: @@ -1687,7 +1679,7 @@ the others into ``queue2`` source.choice( queue1, queue2 ) { a -> a =~ /^Hello.*/ ? 0 : 1 } - queue1.subscribe { println it } + queue1.view() See also `branch`_ operator. @@ -1813,15 +1805,15 @@ The ``tap`` can be useful in certain scenarios where you may be required to conc as in the following example:: - log1 = Channel.create().subscribe { println "Log 1: $it" } - log2 = Channel.create().subscribe { println "Log 2: $it" } + log1 = Channel.create().view { "Log 1: $it" } + log2 = Channel.create().view { "Log 2: $it" } Channel .from ( 'a', 'b', 'c' ) .tap( log1 ) .map { it * 2 } .tap( log2 ) - .subscribe { println "Result: $it" } + .view { "Result: $it" } :: @@ -1847,11 +1839,11 @@ Using the closure syntax the above example can be rewritten as shown below:: .tap { log1 } .map { it * 2 } .tap { log2 } - .subscribe { println "Result: $it" } + .view { "Result: $it" } - log1.subscribe { println "Log 1: $it" } - log2.subscribe { println "Log 2: $it" } + log1.view { "Log 1: $it" } + log2.view { "Log 2: $it" } See also `into`_ and `separate`_ operators. @@ -1876,8 +1868,8 @@ list will be assigned to the output channel with the corresponding position inde .from ( 2,4,8 ) .separate( queue1, queue2 ) { a -> [a+1, a*a] } - queue1.subscribe { println "Channel 1: $it" } - queue2.subscribe { println "Channel 2: $it" } + queue1.view { "Channel 1: $it" } + queue2.view { "Channel 2: $it" } :: @@ -1901,8 +1893,8 @@ For example:: .from([1,2], ['a','b'], ['p','q']) .separate( alpha, delta ) - alpha.subscribe { println "first : $it" } - delta.subscribe { println "second: $it" } + alpha.view { "first : $it" } + delta.view { "second: $it" } It will output:: @@ -1920,9 +1912,9 @@ For example:: source = Channel.from(1,2,3) (queue1, queue2, queue3) = source.separate(3) { a -> [a, a+1, a*a] } - queue1.subscribe { println "Queue 1 > $it" } - queue2.subscribe { println "Queue 2 > $it" } - queue3.subscribe { println "Queue 3 > $it" } + queue1.view { "Queue 1 > $it" } + queue2.view { "Queue 2 > $it" } + queue3.view { "Queue 3 > $it" } The output will look like the following fragment:: @@ -1973,7 +1965,7 @@ items emitted by the source channel. For example:: Channel .from(9,1,7,5) .count() - .subscribe { println it } + .view() // -> 4 @@ -1985,19 +1977,19 @@ a literal value, a Java class, or a `boolean predicate` that needs to be satisfi Channel .from(4,1,7,1,1) .count(1) - .subscribe { println it } + .view() // -> 3 Channel .from('a','c','c','q','b') .count ( ~/c/ ) - .subscribe { println it } + .view() // -> 2 Channel .from('a','c','c','q','b') .count { it <= 'c' } - .subscribe { println it } + .view() // -> 4 @@ -2013,7 +2005,7 @@ For example:: Channel .from( 'x', 'y', 'x', 'x', 'z', 'y' ) .countBy() - .subscribe { println it } + .view() :: @@ -2027,7 +2019,7 @@ that associates each item with the grouping key. For example:: Channel .from( 'hola', 'hello', 'ciao', 'bonjour', 'halo' ) .countBy { it[0] } - .subscribe { println it } + .view() :: @@ -2046,7 +2038,7 @@ For example:: Channel .from( 8, 6, 2, 5 ) .min() - .subscribe { println "Min value is $it" } + .view { "Min value is $it" } :: @@ -2059,7 +2051,7 @@ item that has the minimum length:: Channel .from("hello","hi","hey") .min { it.size() } - .subscribe { println it } + .view() :: @@ -2072,7 +2064,7 @@ taking two parameters that represent two emitted items to be compared. For examp Channel .from("hello","hi","hey") .min { a,b -> a.size() <=> b.size() } - .subscribe { println it } + .view() .. _operator-max: @@ -2086,7 +2078,7 @@ For example:: Channel .from( 8, 6, 2, 5 ) .min() - .subscribe { println "Max value is $it" } + .view { "Max value is $it" } :: @@ -2100,7 +2092,7 @@ item that has the maximum length:: Channel .from("hello","hi","hey") .max { it.size() } - .subscribe { println it } + .view() :: @@ -2113,7 +2105,7 @@ taking two parameters that represent two emitted items to be compared. For examp Channel .from("hello","hi","hey") .max { a,b -> a.size() <=> b.size() } - .subscribe { println it } + .view() .. _operator-sum: @@ -2127,7 +2119,7 @@ For example:: Channel .from( 8, 6, 2, 5 ) .sum() - .subscribe { println "The sum is $it" } + .view { "The sum is $it" } :: @@ -2140,7 +2132,7 @@ a function that, given an item, returns the value to be summed. For example:: Channel .from( 4, 1, 7, 5 ) .sum { it * it } - .subscribe { println "Square: $it" } + .view { "Square: $it" } ::