What a module writes down

Step one deleted a library and built anyway. The bill for that arrives here, and it is smaller than you would expect: if a consumer only ever reads declarations, the declarations have to say everything a consumer needs. That is two questions, and R-2 answers both. Which names are written down, and what each one has to say.

Which names#

Go back to the library from step one. One of its three definitions is not exported, and the file says what that costs.

# R-2: not exported, so this is the module's own business. `modules.iyi` can
# neither `import app/greeter::{greeting}` nor reach it by any other route —
# `.iyimod` carries a module's exports and nothing else, so a name left
# unmarked has to be unreachable or that metadata would not be enough to
# compile against (SPEC.md IV.2).
def greeting : String
  "Hello"
end

Read greeting again: it is unreachable from another file rather than merely awkward to access, and the sample says why in the comment above it. A .iyimod artifact carries a module's exports and nothing else. So a name without pub has to be genuinely unreachable, or that artifact would not be enough to compile against. Qualifying it does not help. App::Greeter.greeting fails for the same reason import app/greeter::* does not bring it in: it is not there to be found.

Notice what just happened to step one. "Unreachable rather than absent from an import's names" and "not in the artifact" turned out to be the same sentence. Visibility in iyi is the shape of a file the compiler will later read instead of your source.

And what those names say#

The other half of the rule is about the names that are written down. Here is one from a bigger program, the scanner inside the three module calculator.

pub def scan(source : String) : Array(Token) | BadCharacter
  tokens = [] of Token
  index = 0

  while index < source.size
    c = source[index]

    # A line ends in CRLF on Windows: `echo 2 + 3 * 4| iyi run
    # samples\iyi\calc.iyi` in cmd answered "unexpected character at 9",
    # the `\r`.
    if c == ' ' || c == '\n' || c == '\t' || c == '\r'
      index = index + 1
    elsif digit?(c)
      start = index
      while index < source.size && digit?(source[index])
        index = index + 1
      end
      tokens << Token.new("number", source[start, index - start], start)
    elsif letter?(c)
      start = index
      while index < source.size && (letter?(source[index]) || digit?(source[index]))
        index = index + 1
      end
      tokens << Token.new("name", source[start, index - start], start)
    elsif operator?(c)
      tokens << Token.new("op", source[index, 1], index)
      index = index + 1
    else
      return BadCharacter.new(index, c)
    end
  end

  tokens << Token.new("end", "", index)
  tokens
end

The signature is fully written: one parameter with its type, and a return type that is a union, because scanning can fail and the last step is about what that means. Nothing else in the declaration is left to a reader or to a compiler.

Then look inside the body. tokens, index and start are declared by being assigned, and no local anywhere in that file carries a type. That is the second sentence of the premise doing its work: inference is untouched, and it is untouched everywhere it costs a consumer nothing. Crystal's local inference, flow typing and blocks are all still here, unchanged, because they never crossed a module boundary in the first place.

So the writing is asked for exactly at the edge. That is also where a person would want it: an exported signature is the documentation a consumer reads, and iyi mod dump --declarations prints the module as its consumers see it, which is the same list of signatures with the bodies gone.

Break it three ways#

An exported def with no return type looks like an oversight the compiler could just fix, since the body is right there. It cannot: the body stays in this module, so the consumer never sees it. The compiler says which symbol it would end up asking the linker for.

Then the other two ways to get this rule wrong, recorded the same way. Reach from another module for a name that carries no pub, which is the first half of the rule refusing to be worked around. And write a body that does not honor the return type above it, which is the second half: a written type is a promise to everyone compiling against the artifact, so the body is the thing that has to give.