7 files changed, 111 insertions, 108 deletions

diff --git a/src/gleam/any.gleam b/src/gleam/any.gleam
index a8358ac..1eec6f1 100644
--- a/src/gleam/any.gleam
+++ b/src/gleam/any.gleam
@@ -20,35 +20,35 @@ pub external fn from(a) -> Any = "gleam_stdlib" "identity";
 //
 pub external fn unsafe_coerce(a) -> b = "gleam_stdlib" "identity";
 
-pub external fn string(Any) -> Result(String, String)
+pub external fn string(from: Any) -> Result(String, String)
   = "gleam_stdlib" "decode_string"
 
-pub external fn int(Any) -> Result(Int, String)
+pub external fn int(from: Any) -> Result(Int, String)
   = "gleam_stdlib" "decode_int"
 
-pub external fn float(Any) -> Result(Float, String)
+pub external fn float(from: Any) -> Result(Float, String)
   = "gleam_stdlib" "decode_float"
 
-pub external fn atom(Any) -> Result(atom.Atom, String)
+pub external fn atom(from: Any) -> Result(atom.Atom, String)
   = "gleam_stdlib" "decode_atom"
 
-pub external fn bool(Any) -> Result(Bool, String)
+pub external fn bool(from: Any) -> Result(Bool, String)
   = "gleam_stdlib" "decode_bool"
 
-pub external fn thunk(Any) -> Result(fn() -> Any, String)
+pub external fn thunk(from: Any) -> Result(fn() -> Any, String)
   = "gleam_stdlib" "decode_thunk"
 
-external fn list_any(Any) -> Result(List(Any), String)
+external fn list_any(from: Any) -> Result(List(Any), String)
   = "gleam_stdlib" "decode_list"
 
-pub fn list(any, decode) {
+pub fn list(from any, containing decoder_type) {
   any
   |> list_any
-  |> result.then(_, list_mod.traverse(_, decode))
+  |> result.then(_, list_mod.traverse(_, decoder_type))
 }
 
-pub external fn pair(Any) -> Result(pair.Pair(Any, Any), String)
+pub external fn pair(from: Any) -> Result(pair.Pair(Any, Any), String)
   = "gleam_stdlib" "decode_pair"
 
-pub external fn field(Any, a) -> Result(Any, String)
+pub external fn field(from: Any, named: a) -> Result(Any, String)
   = "gleam_stdlib" "decode_field"
diff --git a/src/gleam/iodata.gleam b/src/gleam/iodata.gleam
index e1b017e..46f2369 100644
--- a/src/gleam/iodata.gleam
+++ b/src/gleam/iodata.gleam
@@ -1,15 +1,15 @@
 pub external type Iodata;
 
-pub external fn prepend(Iodata, String) -> Iodata =
+pub external fn prepend(to: Iodata, prefix: String) -> Iodata =
   "gleam_stdlib" "iodata_prepend";
 
-pub external fn append(Iodata, String) -> Iodata =
+pub external fn append(to: Iodata, suffix: String) -> Iodata =
   "gleam_stdlib" "iodata_append";
 
-pub external fn prepend_iodata(Iodata, Iodata) -> Iodata =
+pub external fn prepend_iodata(to: Iodata, prefix: Iodata) -> Iodata =
   "gleam_stdlib" "iodata_prepend";
 
-pub external fn append_iodata(Iodata, Iodata) -> Iodata =
+pub external fn append_iodata(to: Iodata, suffix: Iodata) -> Iodata =
   "gleam_stdlib" "iodata_append";
 
 pub external fn from_strings(List(String)) -> Iodata =
@@ -42,15 +42,15 @@ enum Direction =
 external fn erl_split(Iodata, String, Direction) -> List(Iodata) =
   "string" "split"
 
-pub fn split(iodata, on) {
-  erl_split(iodata, on, All)
+pub fn split(iodata, on pattern) {
+  erl_split(iodata, pattern, All)
 }
 
 external fn erl_replace(Iodata, String, String, Direction) -> Iodata =
   "string" "replace"
 
-pub fn replace(iodata, pattern, replacement) {
-  erl_replace(iodata, pattern, replacement, All)
+pub fn replace(in iodata, all pattern, with substitute) {
+  erl_replace(iodata, pattern, substitute, All)
 }
 
 pub external fn is_equal(Iodata, Iodata) -> Bool = "string" "equal"
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index f6b00a3..5c9a926 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -16,7 +16,7 @@ pub fn is_empty(list) {
   list == []
 }
 
-pub fn contains(list, elem) {
+pub fn contains(list, has elem) {
   case list {
   | [] -> False
   | [head | rest] -> head == elem || contains(rest, elem)
@@ -50,8 +50,8 @@ fn do_filter(list, fun, acc) {
   }
 }
 
-pub fn filter(list, fun) {
-  do_filter(list, fun, [])
+pub fn filter(list, for predicate) {
+  do_filter(list, predicate, [])
 }
 
 fn do_map(list, fun, acc) {
@@ -61,7 +61,7 @@ fn do_map(list, fun, acc) {
   }
 }
 
-pub fn map(list, fun) {
+pub fn map(list, with fun) {
   do_map(list, fun, [])
 }
 
@@ -72,7 +72,7 @@ fn do_index_map(list, fun, index, acc) {
   }
 }
 
-pub fn index_map(list, fun) {
+pub fn index_map(list, with fun) {
   do_index_map(list, fun, 0, [])
 }
 
@@ -87,11 +87,11 @@ fn do_traverse(list, fun, acc) {
   }
 }
 
-pub fn traverse(list, fun) {
+pub fn traverse(list, with fun) {
   do_traverse(list, fun, [])
 }
 
-pub fn drop(list, n) {
+pub fn drop(from list, up_to n) {
   case n <= 0 {
   | True -> list
   | False ->
@@ -113,7 +113,7 @@ fn do_take(list, n, acc) {
   }
 }
 
-pub fn take(list, n) {
+pub fn take(from list, up_to n) {
   do_take(list, n, [])
 }
 
@@ -134,50 +134,50 @@ pub fn flatten(lists) {
   do_flatten(lists, [])
 }
 
-pub fn fold(list, acc, fun) {
+pub fn fold(list, from initial, with fun) {
   case list {
-  | [] -> acc
-  | [x | rest] -> fold(rest, fun(x, acc), fun)
+  | [] -> initial
+  | [x | rest] -> fold(rest, fun(x, initial), fun)
   }
 }
 
-pub fn fold_right(list, acc, fun) {
+pub fn fold_right(list, from initial, with fun) {
   case list {
-  | [] -> acc
-  | [x | rest] -> fun(x, fold_right(rest, acc, fun))
+  | [] -> initial
+  | [x | rest] -> fun(x, fold_right(rest, initial, fun))
   }
 }
 
-pub fn find(haystack, f) {
+pub fn find(in haystack, one_that is_desired) {
   case haystack {
   | [] -> Error(Nil)
   | [x | rest] ->
-      case f(x) {
+      case is_desired(x) {
       | Ok(x) -> Ok(x)
-      | _ -> find(rest, f)
+      | _ -> find(in: rest, one_that: is_desired)
       }
   }
 }
 
-pub fn all(list, f) {
+pub fn all(in list, satisfying predicate) {
   case list {
     | [] -> True
     | [x | rest] ->
-      case f(x) {
-      | True -> all(rest, f)
+      case predicate(x) {
+      | True -> all(rest, predicate)
       | _ -> False
       }
   }
 }
 
-pub fn any(list, f) {
+pub fn any(in list, satisfying predicate) {
   case list {
-    | [] -> False
-    | [x | rest] ->
-      case f(x) {
-      | False -> any(rest, f)
-      | _ -> True
-      }
+  | [] -> False
+  | [x | rest] ->
+    case predicate(x) {
+    | False -> any(rest, predicate)
+    | _ -> True
+    }
   }
 }
 
@@ -196,7 +196,7 @@ pub fn strict_zip(l1, l2) {
   }
 }
 
-pub fn intersperse(list, elem) {
+pub fn intersperse(list, with elem) {
   case list {
     | [] -> []
     | [x | []] -> [x]
@@ -204,18 +204,18 @@ pub fn intersperse(list, elem) {
   }
 }
 
-pub fn at(list, i) {
-  case i < 0 {
-    | True -> Error(Nil)
-    | False ->
-      case list {
-        | [] -> Error(Nil)
-        | [x | rest] ->
-          case i == 0 {
-          | True -> Ok(x)
-          | False -> at(rest, i - 1)
-          }
+pub fn at(in list, get index) {
+  case index < 0 {
+  | True -> Error(Nil)
+  | False ->
+    case list {
+    | [] -> Error(Nil)
+    | [x | rest] ->
+      case index == 0 {
+      | True -> Ok(x)
+      | False -> at(rest, index - 1)
       }
+    }
   }
 }
 
@@ -228,13 +228,13 @@ pub fn unique(list) {
 
 fn merge_sort(a, b, compare) {
   case a, b {
-    | [], _ -> b
-    | _, [] -> a
-    | [ax | ar], [bx | br] ->
-      case compare(ax, bx) {
-      | order.Lt -> [ax | merge_sort(ar, b, compare)]
-      | _ -> [bx | merge_sort(a, br, compare)]
-      }
+  | [], _ -> b
+  | _, [] -> a
+  | [ax | ar], [bx | br] ->
+    case compare(ax, bx) {
+    | order.Lt -> [ax | merge_sort(ar, b, compare)]
+    | _ -> [bx | merge_sort(a, br, compare)]
+    }
   }
 }
 
@@ -253,11 +253,11 @@ fn do_sort(list, compare, list_length) {
   }
 }
 
-pub fn sort(list, compare) {
+pub fn sort(list, sort_by compare) {
   do_sort(list, compare, length(list))
 }
 
-pub fn range(start, stop) {
+pub fn range(from start, to stop) {
   case int.compare(start, stop) {
   | order.Eq -> []
   | order.Gt -> [start | range(start - 1, stop)]
@@ -272,7 +272,7 @@ fn do_repeat(a, times, acc) {
   }
 }
 
-pub fn repeat(a, times) {
+pub fn repeat(item a, times times) {
   do_repeat(a, times, [])
 }
 
@@ -287,8 +287,8 @@ fn do_split(list, n, taken) {
   }
 }
 
-pub fn split(list, n) {
-  do_split(list, n, [])
+pub fn split(list list, on target) {
+  do_split(list, target, [])
 }
 
 fn do_split_while(list, f, acc) {
@@ -302,11 +302,11 @@ fn do_split_while(list, f, acc) {
   }
 }
 
-pub fn split_while(list, f) {
-  do_split_while(list, f, [])
+pub fn split_while(list list, while predicate) {
+  do_split_while(list, predicate, [])
 }
 
-pub fn key_find(haystack, needle) {
+pub fn key_find(in haystack, find needle) {
   find(haystack, fn(p) {
     case pair.first(p) == needle {
     | True -> p |> pair.second |> Ok
diff --git a/src/gleam/map.gleam b/src/gleam/map.gleam
index 57c3228..6a7ab47 100644
--- a/src/gleam/map.gleam
+++ b/src/gleam/map.gleam
@@ -24,13 +24,13 @@ pub fn has_key(map, key) {
 pub external fn new() -> Map(key, value)
   = "maps" "new"
 
-pub external fn get(Map(key, value), key) -> Result(value, Nil)
+pub external fn get(from: Map(key, value), get: key) -> Result(value, Nil)
   = "gleam_stdlib" "map_get";
 
 external fn erl_insert(key, value, Map(key, value)) -> Map(key, value)
   = "maps" "put";
 
-pub fn insert(map, key, value) {
+pub fn insert(into map, for key, insert value) {
   erl_insert(key, value, map)
 }
 
@@ -38,7 +38,7 @@ external fn erl_map_values(fn(key, value) -> value, Map(key, value))
   -> Map(key, value)
   = "maps" "map";
 
-pub fn map_values(map, fun) {
+pub fn map_values(in map, with fun) {
   erl_map_values(fun, map)
 }
 
@@ -52,45 +52,45 @@ external fn erl_filter(fn(key, value) -> Bool, Map(key, value))
   -> Map(key, value)
   = "maps" "filter";
 
-pub fn filter(map, fun) {
-  erl_filter(fun, map)
+pub fn filter(in map, for predicate) {
+  erl_filter(predicate, map)
 }
 
 external fn erl_take(List(k), Map(k, v)) -> Map(k, v) = "maps" "with"
 
-pub fn take(map, keys) {
-  erl_take(keys, map)
+pub fn take(from map, drop desired_keys) {
+  erl_take(desired_keys, map)
 }
 
-pub external fn merge(Map(k, v), Map(k, v)) -> Map(k, v) = "maps" "merge"
+pub external fn merge(into: Map(k, v), merge: Map(k, v)) -> Map(k, v) = "maps" "merge"
 
 external fn erl_delete(k, Map(k, v)) -> Map(k, v) = "maps" "remove"
 
-pub fn delete(map, key) {
+pub fn delete(from map, delete key) {
   erl_delete(key, map)
 }
 
-pub fn drop(map, keys) {
-  list.fold(keys, map, fn(key, acc) {
+pub fn drop(from map, drop disallowed_keys) {
+  list.fold(disallowed_keys, map, fn(key, acc) {
     delete(acc, key)
   })
 }
 
-pub fn update(map, key, f) {
+pub fn update(in map, update key, with fun) {
   case get(map, key) {
-  | Ok(value) -> insert(map, key, f(Ok(value)))
-  | Error(_) -> insert(map, key, f(Error(Nil)))
+  | Ok(value) -> insert(map, key, fun(Ok(value)))
+  | Error(_) -> insert(map, key, fun(Error(Nil)))
   }
 }
 
-fn do_fold(list, acc, f) {
+fn do_fold(list, initial, fun) {
   case list {
-    | [] -> acc
-    | [pair.Pair(k, v) | tail] -> do_fold(tail, f(k, v, acc), f)
+    | [] -> initial
+    | [pair.Pair(k, v) | tail] -> do_fold(tail, fun(k, v, initial), fun)
   }
 }
 
-pub fn fold(map, acc, f) {
+pub fn fold(map, from initial, with fun) {
   let kvs = to_list(map)
-  do_fold(kvs, acc, f)
+  do_fold(kvs, initial, fun)
 }
diff --git a/src/gleam/pair.gleam b/src/gleam/pair.gleam
index 32fc6d1..7d6bc45 100644
--- a/src/gleam/pair.gleam
+++ b/src/gleam/pair.gleam
@@ -18,12 +18,12 @@ pub fn swap(tup) {
   Pair(b, a)
 }
 
-pub fn map_first(tup, f) {
+pub fn map_first(of tup, with fun) {
     let Pair(a, b) = tup
-    Pair(f(a), b)
+    Pair(fun(a), b)
 }
 
-pub fn map_second(tup, f) {
+pub fn map_second(of tup, with fun) {
     let Pair(a, b) = tup
-    Pair(a, f(b))
+    Pair(a, fun(b))
 }
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index d62b2d5..cfde7ba 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -15,14 +15,14 @@ pub fn is_error(result) {
   }
 }
 
-pub fn map(result, fun) {
+pub fn map(result, with fun) {
   case result {
   | Ok(x) -> Ok(fun(x))
   | Error(e) -> Error(e)
   }
 }
 
-pub fn map_error(result, fun) {
+pub fn map_error(result, with fun) {
   case result {
   | Ok(x) -> Ok(x)
   | Error(error) -> Error(fun(error))
@@ -36,14 +36,14 @@ pub fn flatten(result) {
   }
 }
 
-pub fn then(result, fun) {
+pub fn then(result, apply fun) {
   case result {
   | Ok(x) -> fun(x)
   | Error(e) -> Error(e)
   }
 }
 
-pub fn unwrap(result, default) {
+pub fn unwrap(result, or default) {
   case result {
   | Ok(v) -> v
   | Error(_) -> default
diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam
index 9c5791c..851dbca 100644
--- a/src/gleam/string.gleam
+++ b/src/gleam/string.gleam
@@ -18,20 +18,23 @@ pub fn reverse(string) {
   |> iodata.to_string
 }
 
-pub fn split(string, on) {
-  string
+pub fn split(string x, on pattern) {
+  x
   |> iodata.new
-  |> iodata.split(_, on)
-  |> list.map(_, iodata.to_string)
+  |> iodata.split(_, on: pattern)
+  |> list.map(_, with: iodata.to_string)
 }
 
-pub fn replace(string, pattern, with) {
+pub fn replace(in string, all pattern, with substitute) {
   string
   |> iodata.new
-  |> iodata.replace(_, pattern, with)
+  |> iodata.replace(_, all: pattern, with: substitute)
   |> iodata.to_string
 }
 
-pub fn append(s1, s2) {
-  iodata.new(s1) |> iodata.append(_, s2) |> iodata.to_string(_)
+pub fn append(to first, suffix second) {
+  first
+  |> iodata.new
+  |> iodata.append(_, second)
+  |> iodata.to_string
 }