Observations on in(char) and out(number) Command Behaviors

[Hjokrenl]

Hello,

First of all, thank you for creating and maintaining this excellent Piet interpreter. It's a very robust and well-structured project.

I'm opening this issue to report some observations on the behavior of two commands, in(char) and out(number), which seem to differ from common expectations for Piet interpreters and can impact how certain programs are designed.

1. The in(char) command appears to skip all whitespace characters.

When using the in(char) command, any whitespace characters in the standard input (such as spaces, tabs, or newlines) seem to be consumed and discarded by the interpreter. The command only pushes the next non-whitespace character onto the stack.

This behavior makes it impossible for a Piet program to read and process these characters. For example, a common technique is to read characters within a loop that terminates when a newline character (stack value 10) is detected. With the current implementation, this pattern is not feasible because the newline is never passed to the program, which can lead to unexpected infinite loops.

2. The out(number) command automatically appends a newline character.

When the out(number) command is executed, it prints the number from the top of the stack to standard output, followed immediately by a newline character.

The Piet language specification does not appear to mandate this automatic newline. This behavior prevents programs from controlling their output formatting, such as printing a sequence of numbers on a single line separated by spaces or other characters.

I wanted to bring these behaviors to your attention for your consideration. They represent deviations from what many Piet programmers might expect and place certain constraints on the types of programs that can be written.

Thank you again for your time and for your great work on this project.

Best regards.
(By using Gemini-2.5-pro)

[your-diary]

@Hjokrenl
Thank you very much for taking a look at this project and creating a detailed issue.
And sorry for the inconvenience.

The out(number) command automatically appends a newline character.

When the out(number) command is executed, it prints the number from the top of the stack to standard output, followed immediately by a newline character.

The Piet language specification does not appear to mandate this automatic newline. This behavior prevents programs from controlling their output formatting, such as printing a sequence of numbers on a single line separated by spaces or other characters.

This is a bug.

out(number) should be consistent with out(char), which isn't followed by a newline in my implementation.

I'll remove newlines from out(number).

The in(char) command appears to skip all whitespace characters.

When using the in(char) command, any whitespace characters in the standard input (such as spaces, tabs, or newlines) seem to be consumed and discarded by the interpreter. The command only pushes the next non-whitespace character onto the stack.

This behavior makes it impossible for a Piet program to read and process these characters. For example, a common technique is to read characters within a loop that terminates when a newline character (stack value 10) is detected. With the current implementation, this pattern is not feasible because the newline is never passed to the program, which can lead to unexpected infinite loops.

Theoretically this is not a bug, but practically this may be a bug and I should fix it.

I'm considering adding the following section to the 3. Specification chapter of README.md and updating the implementation accordingly.

What do you think about this approach? Does it align with your expectations?

---

3.8 in(number), in(char) command

The spec is vague about how to determine number/character boundaries; it only states:

Reads a value from STDIN as either a number or character

Data values exist only as integers, though they may be read in or printed as Unicode character values with appropriate commands.

Practically, we assume that, when users want to input a series of numbers, they would separate them by whitespace (e.g. 1 -2 -3, 1\n-2\n-3, etc.) though lining up numbers without whitespace is also theoretically possible (e.g. 123-5-6 may be interpreted as [1, 2, 3, -5, -6]).

On the other hand, when users want to input a string, they typically do not want to ignore whitespace (e.g. Hello, world!\n should be read as is) though skipping whitespace is also theoretically possible (e.g. a b c may be interpreted as ['a', 'b', 'c']).

To support both use-cases, we adopt the following implementation:

• in(char) literally reads the next Unicode character, including whitespace.

• in(number) follows the regex [ \t\n]*(+|-)?[0-9]+[ \t\n]* (i.e. an optionally-signed integer with any amount of leading/trailing whitespace).

  For example, if stdin contains 123 hello, then in(number) consumes 123 and leaves hello.

[Hjokrenl]

Thank you so much for your incredibly fast and thoughtful response. I truly appreciate you taking the time to consider the issue in such detail.

I'm very happy to hear that you'll be adjusting the out(number) command. Removing the automatic newline will definitely make it more flexible and consistent with out(char), which will be a great improvement.

Regarding the in(char) and in(number) commands, the approach you've proposed is absolutely perfect. It completely aligns with my expectations and, I believe, with what most programmers would find intuitive and useful.

Having in(char) read the next literal character (including whitespace) is exactly what's needed for handling raw text input and using newlines as terminators. Clearly defining that in(number) will consume surrounding whitespace also makes perfect sense for its use case. Separating these two behaviors is an ideal solution.

I also think that documenting this behavior clearly in the README is an excellent idea. It will prevent future confusion and make the interpreter's behavior transparent for all users.

Thank you again for your positive engagement and for your willingness to make these improvements. I look forward to seeing the changes.

Best regards.
(By using Gemini-2.5-pro)

[your-diary]

@Hjokrenl
Thank you for the feedback.

The fix has been implemented in cee0539.

Basically the fix follows this draft.
One exception is, for in(number), it uses the pseudo regex [ \t\n]*(+|-)?[0-9]+[ \t]*\n? instead of [ \t\n]*(+|-)?[0-9]+[ \t\n]* for the reasons discussed in README.md.

I'll close this issue after releasing a new version including the fix (soon).

[your-diary]

@Hjokrenl
v3.0.0, which includes the fix, has been released.

Thank you for opening the issue!