INPUT /  OUTPUT /  LANGUAGE





Instance Names and Scope

In the last chapter you gave an input box a name, so a button could send its contents to your program. Names are one of the most important ideas in ioL. They let you go back to something you've already put on the screen and read it, change it, or add to it, instead of printing everything again.


Tags and tag instances

When the console reads a tag like <box {Hello}>, it creates a box on the screen. That box stays in the console after the tag has been read: it's a tag instance. The tag was the instruction; the tag instance is the thing it made.

To work with a tag instance later, give it an instance name when you create it, by writing the name and a colon in front of the tag type:

<greeting:span {Hello}>

This creates a span containing Hello, and names it greeting. The name doesn't change how the span looks. It just gives you a way to refer to it.

Choosing names

Reading a tag instance

Write a name where you'd write a value, and you get the value of that tag instance's primary field. You've already done this with <putLn name>. Inside a tag like that, you can write the name on its own; elsewhere, put it in angle brackets like a tag:

<greeting:span {Hello}>
<putLn greeting>             <! sends "Hello" to your program !>
The greeting says: <greeting> <! displays "The greeting says: Hello" !>

To read one of its other fields, add a dot and the field name:

<heading:span size=24,pt {Welcome}>
<putLn heading.size>         <! sends the span's text size !>

Reading gives you a copy

This is important: reading a name gives you a copy of its value at that moment. If the value changes later, the copy doesn't change with it:

<points:scalar 5>
Your score: <points></n>       <! displays "Your score: 5" !>
<points 99>
Your score: <points>            <! displays "Your score: 99" underneath; the line above still says 5 !>

(A scalar tag, used here, is invisible. It just holds a value, much like a variable in Python.) So how do you show something that changes, like a score? You change the tag instance that displays it, which is what the next section is about.

Changing a tag instance

To replace the contents of a tag instance's primary field, write the name followed by the new value, like a tag:

<greeting:span {Hello}>
<greeting {Goodbye}>          <! the span on screen now says Goodbye !>

To change another field, use a dot:

<greeting.color {red}>

You may also see an = written after the name: <greeting={Goodbye}> or <greeting.color={red}>. The = is optional and makes no difference; it's allowed simply because it reads naturally. The same goes for a tag's primary field when it's created: <score:scalar=0> is the same as <score:scalar 0>.

Fields you didn't give at the start

Notice that our span was created without a color field. That doesn't matter: a tag instance has the fields you gave it when you created it, and it gains any other field the first time you use one. So <greeting.color {red}> gives the span a color field and sets it to red, all in one go. You don't have to plan ahead.

Reading works the same way. A field you've never set reads as null, which means "nothing chosen", so the tag looks the way it would by default:

<putLn greeting.italic>       <! sends an empty line: nothing chosen yet !>

Setting a field back to null later returns it to its default appearance.

Check your spelling

Because a tag will take a field you haven't used before, it can't tell a new field from a misspelt one. If you write <greeting.colour {red}>, the span is given a field called colour, which means nothing to a span, and the text stays the colour it was. There's no error message: the span is simply holding a field it has no use for. So if a change seems to do nothing, check the field name first.

A misspelt instance name is different. Only the last name in a path can be new, so if the console can't find greting, it tells you so in the terminal:

ioL | invalid reference | Not defined in reference scope: greting.color.

Not every tag will take any field name, either. Tags you can see on the screen, like spans and boxes, will. Invisible tags like scalar only take the fields they have a use for, so <points.foo 1> gives the same "invalid reference" message.

Example: a scoreboard

Here's a program that keeps a score and displays it. Rather than printing the whole screen again each time the score changes, it creates the display once, with a name, and then just changes it:

score = 0

print('''
<console.title {Scoreboard}>
<span size=14,pt {Score:}></n>
<scoreText:span size=48,pt bold=true {0}></n>
<button {+1} onClick=<putLn {/up}>> <button {-1} onClick=<putLn {/down}>>
<button {Reset} onClick=<putLn {/reset}>> <button {Quit} onClick=<putLn {/quit}>>
''')

while True:
    command = input()
    if command == '/up':
        score += 1
    elif command == '/down':
        score -= 1
    elif command == '/reset':
        score = 0
    elif command == '/quit':
        break
    print('<scoreText ' + str(score) + '>')
    if score < 0:
        print('<scoreText.color {red}>')
    else:
        print('<scoreText.color null>')
Score:
-2
+1 -1 Reset Quit

The score turns red when it drops below zero, and goes back to its usual colour when the program sets color back to null. scoreText was created without a color field; it gains one the first time the program sets it.

Scope: names inside other tags

Tags can contain other tags, and so can their names. A name created inside another tag belongs to that tag. From outside, you reach it with a dot, like a field:

<card:box {
    <heading:span bold=true {Ada Lovelace}></n>
    <job:span {Mathematician}>
}>

<card.job {Mathematician and writer}>

Writing just job at the top level wouldn't work: there's no job there, only inside card. The part of your document where a name can be used without a dot is called its scope. The rules are:

Scope lets you reuse simple names like heading in different parts of your interface, without them clashing. A card for each of three people could each have its own heading and job. Within the same scope, though, give each tag instance a different name.

Fields and names inside a tag

A dot after a name can lead to a field, like greeting.color, or to a name inside a tag, like card.job. What if a tag has both?

A tag doesn't start out with every field it could have. Tags like box have dozens of possible fields, and if every box had all of them from the start, names like color or title would be taken, and you couldn't use them for tags of your own inside the box. Because a tag only has the fields you've given it (or used), those names stay free: a box without a color field can contain a span named color, and card.color will find the span. So when the console sees card.color, it looks in this order:

  1. a color field that belongs to card itself;
  2. otherwise, something called color inside card;
  3. only if there's nothing, card is given a color field of its own.

Most of the time you won't notice this. But if a tag holds other tags and you want to be certain a field belongs to the tag itself, give it that field when you create it, even if only as color=null. (The last of the "Try it" questions below shows why.)

The console

One tag instance exists before your program prints anything: the console itself. It's named console, and everything your program prints goes inside it. That's what the lines from the chapter on making things look good were doing:

<console.title {My Program}>
<console.backgroundColor {white}>

They change fields of the console tag instance, exactly like <card.job ...> changes a field of card.

Because your output is inside the console, the top level of your output is the console's own scope, and you can leave out the console. part: <title {My Program}> does the same thing. That only works for fields the console already has, such as title: a field is only added when it's written after a dot, so on its own <italic true> is an invalid reference, while <console.italic true> works. Writing it out in full also makes it clearer what's being changed, so the examples in this guide mostly do.

Trusting the user's input

Everything your program receives through the console comes, one way or another, from the user. And users type all sorts of things: by accident, out of curiosity, or occasionally on purpose to see what breaks. Every program that accepts input has to answer two questions about it.

Does it make sense? If your program asks for a number, the user may type a word. If it asks for a name, they may type nothing at all. You've already seen one way to check: isdigit() in the guessing game. You'll meet more as you go on. The rule is simple: check input before you rely on it, and decide what to do if it's wrong.

Could it be mistaken for something else? If your program prints text the user typed, any <, { or } in it could be read as markup. If your program treats certain lines as commands, the user might type one. In both cases, something the user typed as data has been mistaken for instructions.

Mistaking data for instructions is one of the oldest mistakes in computing. In 1988, the Morris worm spread across the early Internet partly by sending a program more input than it had room for, overwriting its instructions. A decade later, programmers discovered SQL injection: if a program builds a database command by pasting in text the user typed, a cleverly typed "name" can become part of the command, and read or destroy whatever it likes. Mistakes like these are still found in new software every year. Whatever language or system you use, it's worth asking of every piece of input: what is this allowed to mean?

The user's text can cross between your program and the console in either direction, and each direction has its own way of keeping things clear:


Try it

  1. Change the scoreboard so the score turns green when it reaches 10.
  2. Make a card for three different people, each a box with its own name and job spans inside. Then change just the second person's job.
  3. Make the scoreboard's score italic as well as red when it's negative.
  4. Try writing <job {Engineer}> at the top level in your card program. What appears in the terminal? Why?
  5. Create <a:span {Some <span color=null {inner}> text}>. The inner span has no name, and a has no color field of its own. So what do you think <a.color {red}> will do? Try it. Then find out what happens if a contains two inner spans with color fields, and if a has a color field of its own. And what if the inner span has a name, or no color field at all?