ink lists are hell
Ink is a dialogue scripting language that I absolutely loathe, but to be fair to them it can be difficult to design a scripting language meant for users who are primarily non-technical. Recently, I was reading their documentation so I could help someone with it and I learned how lists work in Ink. Here's what they look like:
LIST colors = red, green, blueIf you have a technical background like me, you
might assume that this defines a new variable that
is of the type list which contains the
values red, green, and
blue in it. Is this what Ink does?
No.
LIST colors = red, green, blue
{colors} // prints nothingOh, okay, it's not set to anything...
interesting. So... colors is null? How
do we set it to a value?
ink lists are enums
Well, that's because Ink lists are actually
enums. See, you can set the value of
colors:
LIST colors = (red), green, blue
{colors} // prints "red"
~ colors = green
{colors} // prints "green""Oh okay," you say, "So we're saying that
colors can be none of those values or
one of those values and we set it to
red. Kind of weird they use the
LIST keyword for that though, isn't
that just an enum type? Why don't they call it an
enum instead of a list?"
Well, yeah, I mean, it's kind-of like an enum.
You can do what you might expect for enum types like
ask what values colors could possibly
have:
LIST colors = red, green, blue
{LIST_ALL(colors)} // prints "red, green, blue"As an aside, you can also declare more variables that use the same enum, like this:
LIST colors = red, green, blue
VAR colors_a = redYou can see here that both colors and colors_a share the same enum type, since they both have the same possible values:
LIST colors = red, green, blue
VAR colors_a = red
{LIST_ALL(colors)} // prints "red, green, blue"
{LIST_ALL(colors_a)} // prints "red, green, blue"It just so happens that LIST colors
actually does two things:
- Declares an named enum with those potential values
- Declares a named variable with whatever value was assigned
You can also get the next and previous enum values by incrementing or decrementing them like numbers:
LIST colors = (red), green, blue
{colors} // prints "red"
~ colors++
{colors} // prints "green"
~ colors--
{colors} // prints "red"Wait a second, it's like a number?
ink lists are numbers
Oh, okay, so ink lists are kind-of like enums,
but they're also kind-of like numbers. Can we see
what numbers are assigned to each enum? You sure
can, because ink lists are kind-of like numbers! You
can use LIST_VALUE to convert the value
into a number:
LIST colors = (red), green, blue
{LIST_VALUE(colors)} // prints "1"
~ colors++
{LIST_VALUE(colors)} // prints "2"
~ colors++
{LIST_VALUE(colors)} // prints "3"And you can convert a number back into the enum too:
LIST colors = red, green, blue
colors = colors(2)
{colors} // prints "green"As you can see, ink lists are 1-indexed and numbers are assigned sequentially. Can you assign numbers to the possible values? You can! Here's what that looks like:
LIST colors = red=1, (green=3), blue=5You can also compare them!
LIST colors = red=1, (green=3), blue=5
{ red < green } // prints "true"
{ green < red } // prints "false"
{ red == blue } // prints "false"
{ colors <= green } // prints "true"Great, so... it's a number, right? We should be able to add the difference between different possible values to get to the respective numbers:
LIST colors = red=1, (green=3), blue=5
~ colors += 2
{colors} // prints "blue"
~ colors -= 4
{colors} // prints "red"Nice! Okay, and obviously, since adding two numbers is the same as adding the sum of the numbers, you should get the same result, right? No; they're only kind-of like numbers:
LIST colors = red=1, (green=3), blue=5
~ colors++
{colors} // prints nothing
~ colors--
{colors} // still prints nothingIn fact, whenever you do some arithmetic and the
resulting value is invalid, it's shunted off into
the void and replaced with 0.
LIST colors = red, green, blue
{colors} // prints nothing
{colors < green} // prints "true"
{LIST_VALUE(colors)} // prints "0""Ah, okay," You say once again, as you recline in
your chair, "So that's why they use 1-indexing. It's
because they're using 0 as a null-like
value that you can't do anything with."
But you're wrong! Ink is perfectly happy letting
you use the value 0, because we can do
that ourselves just fine:
LIST colors = (red=0), green=1, blue=3
{colors} // prints "red"
{LIST_VALUE(colors)} // prints "0"
~ colors++
{colors} // prints "green"
{LIST_VALUE(colors)} // prints "1"...but the moment the value is invalid it becomes
the 0 we can't do anything with instead
of the 0 we can do something
with:
LIST colors = (red=0), green=1, blue=3
{colors} // prints "red"
{LIST_VALUE(colors)} // prints "0"
~ colors++
{colors} // prints "green"
{LIST_VALUE(colors)} // prints "1"
~ colors++
{colors} // prints nothing
{LIST_VALUE(colors)} // prints "0"
~ colors++
{colors} // prints nothing
{LIST_VALUE(colors)} // prints "0"Well, okay, to be pedantic we can still do
something with the 0 by converting back
into the enum:
LIST colors = red=0, blue=2, green=3
{colors} // prints "red"
{LIST_VALUE(colors)} // prints "0"
~ colors++
{colors} // prints nothing
{LIST_VALUE(colors)} // prints "0"
{color(LIST_VALUE(colors))} // prints "red"Anyway, since ink lists are enums that are also numbers, you can of course add and subtract them!
LIST colors = (red=1), green=2, blue=3
{colors} // prints "red"
~ colors += green
{colors} // prints "red, green"Wait a second --
ink lists are lists
"That's right! Have you forgotten?" I say,
shaking you awake by the shoulders. When Ink says
LIST it's definitely a list. Like,
kind-of. You can of course assign lists multiple
values...
LIST colors = (red), (green), blue
{colors} // prints "red, green"...perform some straightforward list operations...
LIST colors = (red), (green), blue
{LIST_COUNT(colors)} // prints "2"
{LIST_MIN(colors)} // prints "red"
{LIST_MAX(colors)} // prints "green"
{LIST_RANDOM(colors)} // prints either "red" or "green"
~ colors += blue // Adds blue to the list
{colors} // prints "red, green, blue"
~ colors -= blue // Removes blue from the list
{colors} // prints "red, green"...and you can compare them to each other by value:
LIST colors = (red), (green), blue
VAR colors_a = (red, green)
VAR colors_b = (green)
{colors_a == colors_b} // prints "false"
// Remember that `colors` is also a variable?
{colors == colors_a} // prints "true"
{colors == colors_b} // prints "false""But wait, so ink lists are lists and
numbers?" You ask, "What does that mean for the
operations from earlier like
LIST_VALUE, arithmetic operations, and
comparisons?"
Well, in the case of LIST_VALUE, it
always returns the value that is the largest:
LIST colors = (red), (green), blue
{LIST_VALUE(colors)} // prints "2"In other words, it's the same as
LIST_MAX. For arithmetic operations,
the operation is applied to every element in the
list:
LIST colors = (red), (green), blue
~ colors++
{colors} // prints "green, blue"For the functional programmers reading this, it's
like fmap! Kinda. So obviously, I think
this qualifies Ink as a fully functional programming
language (/j). And for comparisons, well:
LIST colors = red, green, blue
VAR colors_a = (red, green)
VAR colors_b = (blue)
{colors_a < colors_b} // prints "true"How does that work?
ink lists are ranges
As it turns out, ink lists are also ranges, but not number ranges; you can only use them with defined values.
LIST colors = (red), (green), blue, yellow
{colors < blue} // compiles
{colors < 0} // compiler errorA < B returns true if the range
of A is entirely to the left of the entirety of B.
A > B does the opposite; it returns
true if the range of A is entirely to the right of
B. In both cases, overlaps in the range return
false.
LIST colors = red, green, blue, yellow
VAR a = (red, green)
VAR b = (green, blue)
VAR c = (blue, yellow)
{a < c} // prints "true"
{a < b} // prints "false"
{b < c} // prints "false"
{c < a} // prints "false"
{c > a} // prints "true"
{b > a} // prints "false"
{c > b} // prints "false"
{a > c} // prints "false"A <= B is the same as
< and A >= B is the
same as > except that
overlaps are allowed:
LIST colors = red, green, blue, yellow
VAR a = (red, green)
VAR b = (green, blue)
VAR c = (blue, yellow)
{a <= c} // prints "true"
{a <= b} // prints "true"
{b <= c} // prints "true"
{c <= a} // prints "false"
{c >= a} // prints "true"
{b >= a} // prints "true"
{c >= b} // prints "true"
{a >= c} // prints "false"And notably, doing
A > B or A == B is not equivalent to
A >= B:
LIST colors = red, green, blue
VAR a = (red, green)
VAR b = (red, blue)
{a < b or a == b} // prints "false"
{a <= b} // prints "true"And how does this work with empty ranges? Well, the comparison operators treat an empty list some number that is less than all possible values in the list:
LIST colors = red=-1, green=0, blue=1
{() < red} // prints "true"
{() < blue} // prints "true"
{red < ()} // prints "false"
{blue < ()} // prints "false"Empty lists suck though, so we should probably stick to lists that actually have stuff in them. Lets append lists together:
LIST colors = (red), (green), blue
VAR colors_a = (green)
{colors} // prints "red, green"
{colors + colors_a} // also prints "red, green"Oh no.
ink lists are sets
Ink lists are also sets because they can't contain duplicate values. And since they are sets, you can do the usual things with them like invert them...
LIST colors = (red), (green), blue
{LIST_INVERT(colors)} // prints "blue"...do union, difference, and intersection operations...
LIST colors = red, green, blue
VAR colors_a = (red)
VAR colors_b = (red, blue)
{colors_a + colors_b} // prints "red, blue"
{colors_a - colors_b} // prints nothing
{colors_b - colors_a} // prints "blue"
{colors_a ^ colors_b} // prints "red"...and test whether or not a set contains
something with ? and whether or not it
doesn't have something with !?:
LIST colors = (red), (green), blue
{colors ? red} // prints "true"
{colors ? (red, green)} // prints "true"
{colors ? (red, green, blue)} // prints "false"
{colors !? red} // prints "false"
{colors !? (red, green)} // prints "false"
{colors !? (red, green, blue)} // prints "true"Obviously, this works for variables too:
LIST colors = red, green, blue
VAR colors_a = (red)
VAR colors_b = (red, green, blue)
{colors_a ? colors_b} // prints "false"
{colors_b ? colors_a} // prints "true"
{colors_a !? colors_b} // prints "true"
{colors_b !? colors_a} // prints "false"
{colors ? colors_a} // prints "false"
{colors ? colors_b} // prints "false"
{colors !? colors_a} // prints "false"
{colors !? colors_b} // prints "false"Oh, right, colors is also a variable
and it's not currently set to anything, so it is
empty. Ink actually asserts that nothing can contain
the empty list, not even the empty list itself:
LIST colors = red, green, blue
VAR colors_a = (red)
VAR colors_b = (red, green, blue)
{colors_a ? ()} // prints "false"
{colors_b ? ()} // prints "false"
{colors ? ()} // prints "false"
{() ? ()} // prints "false"
{colors_a !? ()} // prints "true"
{colors_b !? ()} // prints "true"
{colors !? ()} // prints "true"
{() !? ()} // prints "true"Which is, you know, fun:
LIST all_keys = house_key, padlock_key, mail_key
VAR inventory = (mail_key)
VAR required_keys = (house_key, padlock_key)
VAR can_open_door = false
~ can_open_door = inventory ? required_keys
{can_open_door} // prints "false"
// break the door
~ required_keys -= house_key
// break the lock
~ required_keys -= padlock_key
~ can_open_door = inventory ? required_keys
{can_open_door} // prints "false", guess we can't open the door still even though it has no requirementsAnyway, that's about all ink lists can do. It's kind of a funny little thing where you have some constrained set of values a variable can be and you can do a bunch of different things with them. But, at least it guarantees the invariant that a variable can only be a few different things and -- wait -- oh no...
ink lists are untyped
LIST colors = red, green, blue
LIST polygons = triangle, square, pentagon
VAR shape = ()
~ shape += red
~ shape += triangle
{shape} // prints "red, triangle"Ink lists are not actually constrained to only one possible type. You can, at any time, add lists of different types together. So, what does that mean for, well, everything else we reviewed?
Generally speaking, when there is a function that returns one value, you should imagine that it returns the first result in the list that matches. For example:
LIST colors = red, green, blue
LIST polygons = triangle, square, pentagon
VAR shape_a = (red, triangle)
VAR shape_b = (triangle, red)
{LIST_MAX(shape_a)} // prints "red"
{LIST_MAX(shape_b)} // prints "triangle"And when you treat it as a range, all of the values are turned into numbers first for the sake of comparing them:
LIST colors = red, green, blue
LIST polygons = triangle, square, pentagon
VAR shape_a = (red, square)
VAR shape_b = (green, triangle)
{shape_a < shape_b} // prints "false"
{shape_a <= shape_b} // prints "true"And when a function depends on all of the possible values of a list, it only considers the possible values of every type that is currently present in the list, or the type that was last present in the list if it is empty:
LIST colors = red, green, blue
LIST polygons = triangle, square, pentagon
VAR shape = (red, square)
{LIST_ALL(shape)} // prints "red, triangle, green, square, blue, pentagon"
{LIST_INVERT(shape)} // prints "triangle, green, blue, pentagon"
~ shape -= red
{LIST_ALL(shape)} // prints "triangle, square, pentagon"
{LIST_INVERT(shape)} // triangle, pentagon
~ shape -= square
{LIST_ALL(shape)} // prints "triangle, square, pentagon"
{LIST_INVERT(shape)} // prints "triangle, square, pentagon"
~ shape += red
{LIST_ALL(shape)} // prints "red, green, blue"
{LIST_INVERT(shape)} // prints "green, blue"
~ shape -= red
{LIST_ALL(shape)} // prints "red, green, blue"
{LIST_INVERT(shape)} // prints "red, green, blue"And finally, you can replace the list with a value of a different type:
LIST colors = red, green, blue
colors = 2 // This is a number now instead of a list
{colors} // prints "2"As a side note, according to the official documentation, using multiple list types for a variable is the idiomatic way to do record types in Ink:
This allows us to use lists - which have so far played the role of state-machines and flag-trackers - to also act as general properties, which is useful for world modelling.
This is our inception moment. The results are powerful, but also more like "real code" than anything that's come before.
But this is a bad idea because you can accidentally nuke other parts of your state:
LIST state = on, off
LIST temperature = cold, tepid, hot
VAR kettle = (on, cold)
~ kettle = hot // whoops
{kettle} // prints "hot"And you can't enforce invariants like making sure that there is only one possible value for each field:
LIST state = on, off
LIST temperature = cold, tepid, hot
VAR kettle = (on, cold)
~ kettle = LIST_INVERT(kettle) // whoops
{kettle} // prints "off, tepid, hot"Okay! I think that's everything. I think I'm gonna head out before the code crime police shows up. Maybe I'll read some yuri manga...