@effekt-lang/effekt 0.61.0 → 0.63.0

package/libraries/common/array.effekt

@@ -10,14 +10,14 @@ import exception
 /// A mutable 0-indexed fixed-sized array.
 extern type Array[T]
 
-/** We represent arrays like positive types.
- *  The tag is 0 and the obj points to memory with the following layout:
- *
- *   +--[ Header ]--+------+------------+
- *   | Rc  | Eraser | Size | Fields ... |
- *   +--------------+------+------------+
- */
-
+/// We represent arrays like positive types.
+/// The tag is 0 and the obj points to memory with the following layout:
+///
+/// ```
+///    +--[ Header ]--+------+------------+
+///    | Rc  | Eraser | Size | Fields ... |
+///    +--------------+------+------------+
+/// ```
 extern llvm """
 define void @array_erase_fields(ptr %array_pointer) {
 entry:
@@ -201,17 +201,13 @@ def resize[T](source: Array[T], size: Int): Array[T] = {
   go(0)
 }
 
-/**
- * Creates a copy of `arr`
- */
+/// Creates a copy of `arr`
 def copy[T](array: Array[T]): Array[T] =
   array.resize(array.size)
 
-/**
- * Copies `length`-many elements from `from` to `to`
- * starting at `start` (in `from`) and `offset` (in `to`)
- * Panics if any of those are out of bounds.
- */
+/// Copies `length`-many elements from `from` to `to`
+/// starting at `start` (in `from`) and `offset` (in `to`)
+/// Panics if any of those are out of bounds.
 def copy[T](from: Array[T], start: Int, to: Array[T], offset: Int, length: Int): Unit = {
   def go(i: Int, j: Int, n: Int): Unit =
     if (n > 0) {
@@ -226,7 +222,7 @@ def copy[T](from: Array[T], start: Int, to: Array[T], offset: Int, length: Int):
 
 /// Swap the value at index i with that at index j.
 /// Panics if the indices are out bounds.
-/// 
+///
 /// O(1)
 def swap[A](arr: Array[A], i: Int, j: Int): Unit = {
   val tmp = arr.get(i)
@@ -235,7 +231,7 @@ def swap[A](arr: Array[A], i: Int, j: Int): Unit = {
 }
 
 /// Converts the given array into a list.
-/// 
+///
 /// O(N)
 def toList[T](arr: Array[T]): List[T] = {
   var i = arr.size - 1;
@@ -280,7 +276,7 @@ def foreachIndex[T](arr: Array[T]){ action: (Int, T) {Label} => Unit }: Unit =
   }
 
 /// Sum the elements of the array.
-/// 
+///
 /// O(N)
 def sum(arr: Array[Int]): Int = {
   var acc = 0
@@ -291,7 +287,7 @@ def sum(arr: Array[Int]): Int = {
 }
 
 /// Checks whether two given arrays are equal with respect to an equalty funciton defined on their element.
-/// 
+///
 /// O(N)
 def equals[A](this: Array[A], other: Array[A]) { eq: (A, A) => Bool }: Bool = {
   if (this.size != other.size) false
@@ -330,7 +326,7 @@ def mapped[A, B](arr: Array[A]) { f: A => B }: Array[B] = {
 }
 
 /// Reverses an array in-place.
-/// 
+///
 /// O(N)
 def reverse[A](arr: Array[A]): Unit = {
   val size = arr.size()
@@ -346,12 +342,12 @@ def reverse[A](arr: Array[A]): Unit = {
   }
 }
 /// Creates a new array with elements in reverse order.
-/// 
+///
 /// O(N)
 def reversed[A](arr: Array[A]): Array[A] = {
   val size = arr.size()
   val result = unsafeAllocate[A](size)
-  
+
   // Copy elements in reverse order to new array
   each(0, size) { i =>
     val value = arr.get(i)
@@ -381,7 +377,7 @@ def foldRight[A, B](arr: Array[A], init: B) { f: (A, B) => B }: B = {
 /// Filters a given array with respect to a given predicate such that a
 /// new array containing all the elements for which the predicate
 /// holds is allocated.
-/// 
+///
 /// O(N)
 def filtered[A](arr: Array[A]) { shouldKeep: A => Bool }: Array[A] = {
   val res = arr.copy()
@@ -434,15 +430,15 @@ def count[A](arr: Array[A]) { predicate: A => Bool }: Int = {
 def take[A](arr: Array[A], n: Int): Array[A] = {
   val len = min(max(0, n), arr.size)
   val result = unsafeAllocate[A](len)
-  each(0, len) { i => 
+  each(0, len) { i =>
     result.set(i, arr.get(i))
   }
   result
 }
 
-// Drop first n elements.
+/// Drop first n elements.
 /// Returns a new array.
-/// 
+///
 /// O(N)
 def drop[A](arr: Array[A], n: Int): Array[A] = {
   val start = min(max(0, n), arr.size)
@@ -533,7 +529,7 @@ def partioned[A](arr: Array[A]) { pred: A => Bool }: (Array[A], Array[A]) = {
 }
 
 /// Get the _first_ index of the last occurance of `elem`, if there is any.
-/// 
+///
 /// O(N)
 def indexOf[A](arr: Array[A], toFind: A) { eq: (A, A) => Bool }: Option[Int] = {
   var found = None[Int]()
@@ -547,7 +543,7 @@ def indexOf[A](arr: Array[A], toFind: A) { eq: (A, A) => Bool }: Option[Int] = {
 }
 
 /// Get the _last_ index of the last occurance of `elem`, if there is any.
-/// 
+///
 /// O(N)
 def lastIndexOf[A](arr: Array[A], toFind: A) { eq: (A, A) => Bool }: Option[Int] = {
   var lastFound = None[Int]()
@@ -560,7 +556,7 @@ def lastIndexOf[A](arr: Array[A], toFind: A) { eq: (A, A) => Bool }: Option[Int]
 }
 
 /// Perform binary search to find the index of a given element.
-/// 
+///
 /// O(log N)
 def binarySearch[A](arr: Array[A], toFind: A) { ord: (A, A) => Ordering }: Option[Int] = {
   def binarySearch(lowerIdx: Int, upperIdx: Int): Option[Int] = {
@@ -579,26 +575,24 @@ def binarySearch[A](arr: Array[A], toFind: A) { ord: (A, A) => Ordering }: Optio
 }
 
 /// Sort an array in-place using provided comparison function.
-/// Note: sort is unstable since it uses QuickSort (unlike list::sortBy)
+/// Note: `sort` is unstable since it uses QuickSort (unlike `list::sortBy`)
 ///
 /// O(N log N) average case
 def sort[A](arr: Array[A]) { ord: (A, A) => Ordering }: Unit = {
   def partition(low: Int, high: Int): Int = {
     val pivot = arr.get(high)
     var i = low - 1
-    
+
     each(low, high) { j =>
-      ord(arr.get(j), pivot) match {
-        case Less() =>
-          i = i + 1
-          swap(arr, i, j)
-        case _ => ()
+      if (ord(arr.get(j), pivot) is Less()) {
+        i = i + 1
+        swap(arr, i, j)
       }
     }
     swap(arr, i + 1, high)
     i + 1
   }
-  
+
   def quickSort(low: Int, high: Int): Unit = {
     if (low < high) {
       val par = partition(low, high)
@@ -606,13 +600,13 @@ def sort[A](arr: Array[A]) { ord: (A, A) => Ordering }: Unit = {
       quickSort(par + 1, high)
     }
   }
-  
+
   quickSort(0, arr.size - 1)
 }
 
 /// Sort an array using provided comparison function.
 /// A newly allocated sorted array is returned as result, i.e., the sorting is not in-place.
-/// Note: sort is unstable since it uses QuickSort (unlike list::sortBy)
+/// Note: `sorted` is unstable since it uses QuickSort (unlike `list::sortBy`)
 ///
 /// O(N log N) average case
 def sorted[A](arr: Array[A]) { ord: (A, A) => Ordering }: Array[A] = {
@@ -665,6 +659,7 @@ def each[T](array: Array[T]): Unit / emit[T] = {
   go(0)
 }
 
+/// Connects `array` as a producer to a given pull stream `reader` acting as a consumer.
 def feed[T, R](array: Array[T]) { reader: () => R / read[T] }: R = {
   var i = 0
   try {
@@ -682,10 +677,15 @@ def feed[T, R](array: Array[T]) { reader: () => R / read[T] }: R = {
   }
 }
 
+/// Collects elements emitted by a push stream producer `stream` into a new array,
+/// discarding the result of the producer.
 def collect[A] { stream: () => Unit / emit[A] }: Array[A] =
   returning::collect[A, Unit]{stream}.second
 
 namespace returning {
+
+  /// Collects elements emitted by a push stream producer `stream` into a new array,
+  /// returning the result of the producer as well as the collected array.
   def collect[A, R] { stream: () => R / emit[A] }: (R, Array[A]) = {
     var i = 0
     var a = unsafeAllocate(1)

package/libraries/common/bytearray.effekt

@@ -3,6 +3,7 @@ module bytearray
 import effekt
 import stream
 import control
+import array
 
 /**
  * A memory managed, mutable, fixed-length array of bytes.
@@ -106,6 +107,16 @@ def bytearray(size: Int, init: Byte): ByteArray = {
   arr
 }
 
+/// Builds a new ByteArray of size `size` from a computation `index` which gets an index
+/// and returns a byte that will be on that position in the resulting array
+def build(size: Int) { index: Int => Byte }: ByteArray = {
+  val arr = allocate(size);
+  each(0, size) { i =>
+    set(arr, i, index(i))
+  };
+  arr
+}
+
 def resize(source: ByteArray, size: Int): ByteArray = {
   val target = allocate(size)
   val n = min(source.size, target.size)
@@ -119,6 +130,34 @@ def resize(source: ByteArray, size: Int): ByteArray = {
   go(0)
 }
 
+/// Sorts a given bytearray `arr` in-place using a counting sort,
+/// allocating a temporary array of 256 integers for said counting.
+///
+/// O(N)
+def sort(arr: ByteArray): Unit = {
+  val length = arr.size
+  if (length <= 1) {
+    ()
+  } else {
+    // Count occurrences of each byte value
+    // (maps 0..255 to its count in the byte array)
+    val counts = array::allocateZeros(256)
+    each(0, length) { i =>
+      val byte = arr.get(i).toInt
+      counts.set(byte, counts.get(byte) + 1)
+    }
+
+    // Write back in sorted order (like RLE decoding)
+    var pos = 0
+    counts.foreachIndex { (n, count) =>
+      count.repeat {
+        arr.set(pos, n.toByte)
+        pos = pos + 1
+      }
+    }
+  }
+}
+
 def foreach(arr: ByteArray){ action: Byte => Unit }: Unit =
   each(0, arr.size) { i =>
     action(arr.get(i))

package/libraries/common/bytestream.effekt

@@ -0,0 +1,337 @@
+import option
+import stringbuffer
+import stream
+import char
+import io/error
+import bytearray
+
+// assumes by default:
+// BE byteorder, BE bitorder, unsigned
+
+// Wrappers
+// --------
+/// A with explicit big-endian order
+record BE[A](raw: A)
+/// A with explicit little-endian order
+record LE[A](raw: A)
+/// A with explicit width in current unit
+/// (bits for bitstreams, bytes for bytestreams)
+record OfWidth[A](raw: A, width: Int)
+/// explicitly signed A
+record Signed[A](raw: A)
+
+/// Bits
+type Bit { B0(); B1() }
+
+/// not on Bits
+def not(b: Bit): Bit = b match {
+  case B0() => B1()
+  case B1() => B0()
+}
+
+/// Splices allowed in hex/byte stream literals
+effect HexSplices = {
+  splice[Char], splice[String], 
+  splice[Unit], 
+  splice[Int],
+  splice[Byte],
+  splice[BE[Int]], splice[LE[Int]],
+  splice[LE[Signed[Int]]], splice[OfWidth[LE[Int]]], splice[OfWidth[LE[Signed[Int]]]],
+  splice[BE[Signed[Int]]], splice[OfWidth[BE[Int]]], splice[OfWidth[BE[Signed[Int]]]],
+  splice[ByteArray]
+}
+
+// Splitting
+// ---------
+
+/// emit bytes of the given int as a w bytes in little-endian byte order
+def bytesLE(int: Int, w: Int): Unit / emit[Byte] = {
+  var c = int
+  repeat(w){
+    do emit(mod(c, 256).toByte)
+    c = c / 256
+  }
+}
+
+/// emit bytes of the given int as a 4 bytes in little-endian byte order
+def bytesLE(int: Int): Unit / emit[Byte] = bytesLE(int, 4)
+
+/// emit bytes of the given int as a w bytes in big-endian byte order
+def bytesBE(n: Int, width: Int): Unit / emit[Byte] = {
+  var shift = bitwiseShl(width - 1, 3)
+  repeat(width) {
+    do emit(bitwiseAnd(bitwiseShr(n, shift), 255).toByte)
+    shift = shift - 8
+  }
+}
+
+/// emit bytes of the given int as a 4 bytes in big-endian byte order
+def bytesBE(n: Int): Unit / emit[Byte] = bytesBE(n, 4)
+
+/// emit bytes of the given int as width bytes (in 2s-complement) in little-endian byte order
+def signedBytesLE(int: Int, width: Int): Unit / emit[Byte] =
+  if (int < 0) {
+    bytesLE(bitwiseNot(neg(int)) + 1, width)
+  } else {
+    bytesLE(int, width)
+  }
+/// emit bytes of the given int as width bytes (in 2s-complement) in big-endian byte order
+def signedBytesBE(int: Int, width: Int): Unit / emit[Byte] = {
+  if (int < 0) {
+    bytesBE(bitwiseNot(neg(int)) + 1, width)
+  } else {
+    bytesBE(int, width)
+  }
+}
+
+/// emit bytes of the given int as 4 bytes (in 2s-complement) in little-endian byte order
+def signedBytesLE(int: Int): Unit / emit[Byte] = signedBytesLE(int, 4)
+
+/// emit bytes of the given int as 4 bytes (in 2s-complement) in big-endian byte order
+def signedBytesBE(int: Int): Unit / emit[Byte] = signedBytesBE(int, 4)
+
+
+
+// Splicers
+// --------
+
+/// Splicer to emit the bytes in hex notation given, plus eventual splices
+/// Ignores whitespace
+def hex{ body: => Unit / { write, HexSplices } }: Unit / emit[Byte] = {
+  try {
+    try {
+      body()
+    }
+    with splice[String] { s =>
+      feed(s){ loop { do splice[Char](do read[Char]()) } }
+      resume(())
+    }
+    with splice[ByteArray] { ba =>
+      ba.foreach{ b => do splice[Byte](b) }
+      resume(())
+    }
+  }
+  with write { s =>
+      feed(s){
+        loop {
+          attempt {
+            val upper: Int = hexDigitValue(do read[Char]())
+            val lower: Int = hexDigitValue(do read[Char]())
+            do emit[Byte]((16 * upper + lower).toByte)
+          } { () }
+        }
+      }
+      resume(())
+    }
+  with splice[Char] { c => do emit[Byte](c.toInt.toByte); resume(()) }
+  with splice[Byte] { b => do emit(b); resume(()) }
+  with splice[Unit] { u => resume(()) }
+  with splice[Int] { n => bytesBE(n); resume(()) }
+  with splice[LE[Int]] { w => bytesLE(w.raw); resume(()) }
+  with splice[BE[Int]] { v => bytesBE(v.raw); resume(()) }
+  with splice[LE[Signed[Int]]] { w => signedBytesLE(w.raw.raw); resume(()) }
+  with splice[OfWidth[LE[Int]]] { w => bytesLE(w.raw.raw, w.width); resume(()) }
+  with splice[OfWidth[LE[Signed[Int]]]] { w => signedBytesLE(w.raw.raw.raw, w.width); resume(()) }
+  with splice[BE[Signed[Int]]] { w => signedBytesBE(w.raw.raw); resume(()) }
+  with splice[OfWidth[BE[Int]]] { w => bytesBE(w.raw.raw, w.width); resume(()) }
+  with splice[OfWidth[BE[Signed[Int]]]] { w => signedBytesBE(w.raw.raw.raw, w.width); resume(()) }
+}
+
+/// convert the given hex notation to an integer (big-endian)
+def x{ body: => Unit / { write, HexSplices } }: Int = {
+  var res = 0
+  for[Byte]{ hex{body} }{ v => res = res * 256 + v.toInt }
+  res
+}
+
+
+// Sub-Byte
+// ========
+
+// From/to Bytes
+// -------------
+/// emit bits of the given Byte as 8 Bits in little-endian bit order
+def bitsLE(byte: Byte): Unit / emit[Bit] = {
+  val v = byte.toInt
+  var mask = 1
+  repeat(8){
+    bitwiseAnd(v, mask) match {
+      case 0 => do emit(B0())  
+      case _ => do emit(B1())
+    }
+    mask = mask * 2
+  }
+}
+
+/// emit bits of the given Byte as 8 Bits in big-endian bit order
+def bitsBE(byte: Byte): Unit / emit[Bit] = {
+  val v = byte.toInt
+  var mask = 128
+  repeat(8){
+    bitwiseAnd(v, mask) match {
+      case 0 => do emit(B0())  
+      case _ => do emit(B1())
+    }
+    mask = mask / 2
+  }
+}
+
+/// emit bits of the given Byte as width Bits in little-endian bit order
+def bitsLE(v: Int, width: Int): Unit / emit[Bit] = {
+  var mask = 1
+  repeat(width){
+    bitwiseAnd(v, mask) match {
+      case 0 => do emit(B0())  
+      case _ => do emit(B1())
+    }
+    mask = mask * 2
+  }
+}
+
+/// emit bits of the given int as width Bits in big-endian bit order
+def bitsBE(v: Int, width: Int): Unit / emit[Bit] = {
+  var mask = bitwiseShl(1, width - 1)
+  repeat(width){
+    bitwiseAnd(v, mask) match {
+      case 0 => do emit(B0())  
+      case _ => do emit(B1())
+    }
+    mask = mask / 2
+  }
+}
+
+/// emit bits of the given int as 32 Bits in big-endian bit order
+def bitsBE(int: Int): Unit / emit[Bit] = bitsBE(int, 32)
+
+/// collect bits in big-endian bit order into an Int
+def collectBitsBE{ body: => Unit / emit[Bit] }: Int = {
+  var res = 0
+  try body() with emit[Bit] { b =>
+    res = b match {
+      case B0() => res * 2
+      case B1() => res * 2 + 1
+    }
+    resume(())
+  }
+  res
+}
+
+/// split emitted bytes and emit the individual bits in big-endian bit order
+def ungroupBytesBE{ body: => Unit / emit[Byte] }: Unit / emit[Bit] =
+  for[Byte]{body}{ b => bitsBE(b) }
+
+/// streaming negation in 2s-complement for little-endian bitstreams
+def twoscomplementLE{ body: => Unit / emit[Bit] }: Unit / emit[Bit] = {
+  var carry = true
+  try body()
+  with emit[Bit] {
+    case B0() => if(carry) { do emit(B0()) } else { do emit(B1()) }; resume(())
+    case B1() => if(carry) { do emit(B1()); carry = false } else { do emit(B0()) }; resume(())
+  }
+}  
+
+/// group 8 bits into a byte each, big-endian bit order.
+/// NOTE: The remainder is dropped.
+def groupBytesBE{ body: => Unit / emit[Bit] }: Unit / emit[Byte] = {
+  var next = 0
+  var p = 128
+  for[Bit]{body}{ b =>
+    b match {
+      case B0() => ()
+      case B1() => next = next + p
+    }
+    p = p / 2
+    if(p == 0) {
+      do emit(next.toByte)
+      next = 0
+      p = 128
+    }
+  }
+}
+
+/// group 8 bits into a byte each, little-endian bit order.
+/// NOTE: The remainder is dropped.
+def groupBytesLE{ body: => Unit / emit[Bit] }: Unit / emit[Byte] = {
+  var next = 0
+  var p = 1
+  for[Bit]{body}{ b =>
+    b match {
+      case B0() => ()
+      case B1() => next = next + p
+    }
+    p = p * 2
+    if(p == 256) {
+      do emit(next.toByte)
+      next = 0
+      p = 1
+    }
+  }
+}
+
+// Literals/splices
+// ----------------
+/// Splices allowed in bit stream literals
+effect BitSplices = {
+  splice[Unit], splice[Bit],
+  splice[Byte],
+  splice[LE[Int]], splice[BE[Int]],
+  splice[LE[Signed[Int]]], splice[BE[Signed[Int]]],
+  splice[OfWidth[LE[Int]]], splice[OfWidth[BE[Int]]],
+  splice[OfWidth[LE[Signed[Int]]]], splice[OfWidth[BE[Signed[Int]]]]
+}
+/// Splicer to emit the bits in binary notation given, plus evenutal splices
+/// Ignores whitespace
+def bit{ body: => Unit / { write, BitSplices } }: Unit / emit[Bit] = {
+  try {
+    ungroupBytesBE{
+      try {
+        body()
+      }
+      with splice[LE[Int]] { i => bytesLE(i.raw); resume(()) }
+      with splice[BE[Int]] { i => bytesBE(i.raw); resume(()) }
+      with splice[LE[Signed[Int]]] { i => signedBytesLE(i.raw.raw); resume(()) }
+      with splice[BE[Signed[Int]]] { i => signedBytesBE(i.raw.raw); resume(()) }
+    }
+  }
+  with write { s =>
+    feed(s){
+      loop {
+        do read[Char]() match {
+          case '0' => do emit(B0())
+          case '1' => do emit(B1())
+          case _ => ()
+        }
+      }
+    }
+    resume(())
+  }
+  with splice[Unit] { _ => resume(()) }
+  with splice[Bit] { b => do emit(b); resume(()) }
+  with splice[Byte] { b => bitsBE(b); resume(()) }
+  with splice[OfWidth[LE[Int]]] { i =>
+    bitsLE(i.raw.raw, i.width)
+    resume(())
+  }
+  with splice[OfWidth[LE[Signed[Int]]]] { i =>
+    if(i.raw.raw.raw < 0){
+      twoscomplementLE{ bitsLE(0 - i.raw.raw.raw, i.width) }
+    } else {
+      bitsLE(i.raw.raw.raw, i.width)
+    }
+    resume(())
+  }
+  with splice[OfWidth[BE[Int]]] { i =>
+    bitsBE(i.raw.raw, i.width)
+    resume(())
+  }
+  with splice[OfWidth[BE[Signed[Int]]]] { i =>
+    list::collect[Bit]{
+      if(i.raw.raw.raw < 0){
+        twoscomplementLE{ bitsLE(0 - i.raw.raw.raw, i.width) }
+      } else {
+        bitsLE(i.raw.raw.raw, i.width)
+      }
+    }.reverse.each
+    resume(())
+  }
+}

package/libraries/common/effekt.effekt

@@ -321,6 +321,27 @@ extern def infixNeq(x: Bool, y: Bool) at {}: Bool =
     ret %Pos %adt_boolean
   """
 
+extern def infixEq(x: Byte, y: Byte) at {}: Bool =
+  js "${x} === ${y}"
+  chez "(equal? ${x} ${y})"
+  llvm """
+    %z = icmp eq %Byte ${x}, ${y}
+    %fat_z = zext i1 %z to i64
+    %adt_boolean = insertvalue %Pos zeroinitializer, i64 %fat_z, 0
+    ret %Pos %adt_boolean
+  """
+  vm "effekt::infixEq(Byte, Byte)"
+
+extern def infixNeq(x: Byte, y: Byte) at {}: Bool =
+  js "${x} !== ${y}"
+  chez "(not (equal? ${x} ${y}))"
+  llvm """
+    %z = icmp ne %Byte ${x}, ${y}
+    %fat_z = zext i1 %z to i64
+    %adt_boolean = insertvalue %Pos zeroinitializer, i64 %fat_z, 0
+    ret %Pos %adt_boolean
+  """
+  vm "effekt::infixNeq(Byte, Byte)"
 
 // Math ops
 // ========
@@ -682,13 +703,19 @@ extern def bitwiseXor(x: Int, y: Int) at {}: Int =
   llvm "%z = xor %Int ${x}, ${y} ret %Int %z"
   vm "effekt::bitwiseXor(Int, Int)"
 
+extern def bitwiseNot(x: Int) at {}: Int =
+  js "(~${x})"
+  chez "(lognot ${x})"
+  llvm "%z = xor %Int ${x}, -1 ret %Int %z"
+  vm "effekt::bitwiseNot(Int)"
+
 
 // Byte operations
 // ===============
 extern def toByte(n: Int) at {}: Byte =
-  js "${n}"
+  js "(${n} & 0xFF)"
   llvm "%z = trunc %Int ${n} to %Byte ret %Byte %z"
-  chez "${n}"
+  chez "(logand ${n} 255)"
 
 extern def toInt(n: Byte) at {}: Int =
   js "${n}"
@@ -790,9 +817,9 @@ def locally[R] { p: => R } : R = p()
 //
 //     "foo ${42} bar ${43}"
 //
-// to the following stream of `literal`s and `splice[Int]`s:
+// to the following stream of `write`s and `splice[Int]`s:
 //
-//     do literal("foo "); do splice(42); do literal(" bar "); do splice(43)
+//     do write("foo "); do splice(42); do write(" bar "); do splice(43)
 //
 // The stream is wrapped into a handler function, which defaults to `stringbuffer::s`
 //
@@ -800,7 +827,8 @@ def locally[R] { p: => R } : R = p()
 //
 // but can be specified by prefixing the string interpolation `custom"..."`.
 
-effect literal(s: String): Unit
+effect write(s: String): Unit
+
 effect splice[A](x: A): Unit