Migration Guide#

This guide explains how to rewrite existing notations and idioms into equivalent new ones so that scripts follow a new API version.

API Version 5#

The Exit Code on Termination by a Non-Native Error Is Now 1#

Up to API version 4, the process exit code was 0 when terminating with a non-native error.

In API version 5, the process exit code becomes 1 even when terminating with a non-native error.

There is no way to perform the migration while strictly preserving the behavior.

In most cases nothing needs to be done, but the behavior may change for scripts that depend on the exit code on error.

IN Now Reads the Entire Standard Input as a Single String#

Up to API version 4, IN was a stream that read standard input line by line.

In API version 5, it reads the entire standard input as a single string.

To preserve the previous behavior, replace IN with INL (or its alias I).

- IN
+ INL

FILES Now Returns Paths Including the Directory#

Up to API version 4, FILES returned only the filenames directly under the directory.

In API version 5, it returns paths that include the specified directory itself at the beginning.

To preserve the previous behavior, replace calls to FILES with FILE_NAMES.

- FILES("dir")
+ FILE_NAMES("dir")

READ Now Returns a Single String#

Up to API version 4, READ was an alias of READL and returned the file content as a stream of lines.

In API version 5, it returns the entire file content as a single string.

To preserve the previous behavior, replace calls to READ with READL.

- READ("file")
+ READL("file")

EXEC Now Returns the Entire Standard Output as a Single String#

Up to API version 4, EXEC returned a stream that reads the standard output line by line.

In API version 5, it returns the entire standard output decoded as UTF-8 as a single string.

To preserve the previous behavior, replace calls to EXEC with EXECL.

- EXEC("command")
+ EXECL("command")

The $& Operator Now Indents Its Output#

Up to API version 4, the $& operator returned compact output without indentation.

In API version 5, it returns output indented with two spaces.

To preserve the previous behavior, replace the $& operator with JSON[indent: NULL].

- $&value
+ value >> JSON[indent: NULL]

The JSON Function Now Indents Its Output by Default#

Up to API version 4, the JSON function returned compact output without indentation when indent was omitted.

In API version 5, it returns output indented with two spaces.

To preserve the previous behavior, explicitly pass NULL to indent.

- value >> JSON
+ value >> JSON[indent: NULL]

JSONS Has Been Removed#

Up to API version 4, JSONS was an alias for JSONL.

In API version 5, JSONS has been removed.

To preserve the previous behavior, replace calls to JSONS with JSONL.

- JSONS
+ JSONL

SLEEP Now Takes Its Argument in Seconds#

Up to API version 4, SLEEP interpreted its argument as milliseconds.

In API version 5, it interprets the argument as seconds.

To preserve the previous behavior, divide the argument by 1000.

- SLEEP(1500)
+ SLEEP(1.5)

A # Line Comment Can No Longer Begin Except at the Start of a Line or After a Space or Tab#

Up to API version 4, a # line comment could begin regardless of the preceding character.

In API version 5, a # line comment can no longer begin except at the start of a line or immediately after a space or tab.

To preserve the previous behavior, insert a space before any # that previously began a line comment without a preceding space.

- 1#comment
+ 1 #comment