lib/for_abuse.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # This file is free software, which comes along with NIT.  This software is
   4 # distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
   5 # without  even  the implied warranty of  MERCHANTABILITY or  FITNESS FOR A
   6 # PARTICULAR PURPOSE.  You can modify it is you want,  provided this header
   7 # is kept unaltered, and a notification of the changes is added.
   8 # You  are  allowed  to  redistribute it and sell it, alone or is a part of
   9 # another product.
  10
  11 # Service management trough the `for` control structure.
  12 #
  13 # The module is a proof-of-concept to investigate the abuse of
  14 # the `for` structure to implement various services.
  15 #
  16 # The idea is that, with a `for`, the service-provider can:
  17 # * control the end of the service (thus can finalize things
  18 #   like releasing ressources)
  19 # * communicate data with the user on each iteration; the used can
  20 #   also communicate results to the provider.
  21 module for_abuse
  22
  23 # Encapsulation of service in a `for`-compatible interface.
  24 #
  25 # The service is not effectively started until the iterate method
  26 # is called. Then, each step of the iteration is a step in the service.
  27 #
  28 # While, for a typing point of view, abusers are just classes with an
  29 # iterator method, the point of this class is to tag services that return
  30 # a ForAbuser object.
  31 #
  32 # Note that using having `ForAbuser` as a genuine subclass of `Collection`
  33 # works but is not recommended since it may cause mental health issues.
  34 interface ForAbuser[E]
  35         # Starts and control the service
  36         fun iterator: Iterator[E] is abstract
  37 end
  38
  39 # Abuser to read a file, see `file_open`
  40 private class ReadFileForAbuser
  41         super ForAbuser[IFStream]
  42         var path: String
  43         redef fun iterator do return new ReadFileForAbuserIterator(path)
  44 end
  45
  46 # Abuser iterator to read a file, see `file_open`
  47 private class ReadFileForAbuserIterator
  48         super Iterator[IFStream]
  49         redef var item: IFStream
  50         redef var is_ok = true
  51         init(path: String)
  52         do
  53                 # start of service is to open the file, and return in
  54                 item = new IFStream.open(path)
  55         end
  56         redef fun next
  57         do
  58                 # end of service is to close the file
  59                 # there is only one iteration
  60                 is_ok = false
  61                 item.close
  62         end
  63 end
  64
  65 ####
  66
  67 # A comparison query.
  68 # The user is asked to compare `a` with `b` then set `res` accordingly.
  69 #
  70 # * if `a < b` then the user sets `res` to -1
  71 # * if `a > b` then the user sets `res` to 1
  72 # * if `a == b` then the user sets `res` to 0
  73 #
  74 # It is the responsibility of the user to implement a total order.
  75 # ie. the implemented comparison must be asymmetric, transitive and total.
  76 class CompareQuery[E]
  77         # The first element to compare
  78         var a: E
  79         # The second element to compare
  80         var b: E
  81         # The result of the comparison (according to the user)
  82         var res = 0 is writable
  83 end
  84
  85 # Abuser for sorting array, see `sort_fa`
  86 private class SortAbuser[E]
  87         super ForAbuser[CompareQuery[E]]
  88         var array: Array[E]
  89         redef fun iterator do return new SortAbuserIterator[E](array)
  90 end
  91
  92 # Abuser iterator for sorting array, see `sort_fa`
  93 # Implements a sort by permutation
  94 private class SortAbuserIterator[E]
  95         super Iterator[CompareQuery[E]]
  96         # The index of the big loop
  97         var i: Int
  98         # The index of the small loop
  99         var j: Int
 100         # The array to sort
 101         var array: Array[E]
 102         # The query used to communicate with the user.
 103         # For ecological concerns, a unique CompareQuery is instatiated.
 104         var query: nullable CompareQuery[E]
 105         redef fun item do return query.as(not null)
 106         init(array: Array[E])
 107         do
 108                 self.array = array
 109                 # Initialize the algorithm, see `next` for the rest
 110                 i = 0
 111                 j = 0
 112                 if not is_ok then return
 113                 query = new CompareQuery[E](array[i], array[j])
 114         end
 115         redef fun is_ok do return i < array.length - 1
 116         redef fun next
 117         do
 118                 # Process the last query
 119                 if item.res > 0 then
 120                         var tmp = array[i]
 121                         array[i] = array[j]
 122                         array[j] = tmp
 123                 end
 124                 # Get the next iteration
 125                 j += 1
 126                 if j >= array.length then
 127                         # End of small loop
 128                         i += 1
 129                         j = i + 1
 130                 end
 131                 if not is_ok then return
 132                 # Prepare the next query
 133                 item.a = array[i]
 134                 item.b = array[j]
 135                 item.res = 0
 136         end
 137 end
 138
 139 redef class Array[E]
 140         # Sort an array trough a `for` abuse.
 141         # The user uses the provided query (item) to implements its own comparison
 142         #
 143         #     var a = [1, 3, 2]
 144         #     for q in a.sort_fa do q.res = q.a <=> q.b
 145         #     assert a ==  [1, 2, 3]
 146         #
 147         # Implements a sort by permutation.
 148         fun sort_fa: ForAbuser[CompareQuery[E]]
 149         do
 150                 return new SortAbuser[E](self)
 151         end
 152 end
 153
 154 ####
 155
 156 # Open and read a file trough a `for` abuse.
 157 # The abuse just ensures that the file is closed after the reading.
 158 #
 159 #     for f in file_open("/etc/issue") do
 160 #         var l = f.read_line
 161 #         print l
 162 #         assert not l.is_empty
 163 #     end # f is automatically closed here
 164 fun file_open(path: String): ForAbuser[IFStream]
 165 do
 166         return new ReadFileForAbuser(path)
 167 end