# Release Notes for Version 9.5.1 of Icon

Gregg M. Townsend
Department of Computer Science
The University of Arizona

www.cs.arizona.edu/icon/v951/relnotes.htm
Last updated June 5, 2013

## Introduction

Version 9.5.1 of Icon is an update of version 9.5.0. It incorporates configuration, library, and documentation changes. An execution profiler has been added and there are a few new example programs. Some minor bugs have been fixed.

These notes document:

- changes to the Icon source tree since the previous release
- cumulative earlier amendments of the Icon language and graphics books

## Changes in version 9.5.1

Notable changes in this latest version are listed here.

### Execution profiling

An execution profile can be produced by setting the environment variable `ICONPROFILE` at execution time to specify an output file. For a separately built program, profiling must also be enabled during linking.

For each line of the program that is executed, the profiler reports the number of visits and also the number of timer ticks attributed to the line.

The report is ordered by memory layout, which is based on linkage order. To arrange by filename, use the Unix `sort` utility with keys `–k3,3 –k4n`. To see the CPU hotspots, use `sort –nr | head`.

### Minor enhancements

A `QUIT` signal (`^\`) is now caught to produce a traceback message. If profiling has been enabled, the profile report is also generated.

The command `icon filename.icn` now searches first in the directory of `filename` for `$include` files.

### Minor fixes

Pipes can now be opened in untranslated mode.

A memory leak on every 25th co-expression allocation has been fixed.

The external value examples have been rewritten for standards compliance.

Some configurations have been modified in response to changes in their underlying platforms.

Some perfectly legal code has been tweaked to avoid provoking well-intentioned warning messages from C compilers.

### Library changes

As usual, some files in the Icon program library have been added or edited, but the core library files remain stable. Notable changes include:

    procs/io	Honor "len" parameter in tempname()
    procs/itlib	Use infocmp utility if no termcap file
    procs/levensht	Add procedure for computing Levenshtein edit distance
    procs/numbers	Add quadratic mean procedure qmean(L)
    procs/numbers	Fix spell(i) procedure
    procs/psrecord	Fix positioning of noncircular arcs

    progs/iprofl	Add program for listing source with execution profile
    progs/lisp	Read from standard input after reading named file

    gprogs/mandel3	Add Mandelbrot Set display
    gprogs/othello	Add interactive Othello board game
    gprogs/tess	Add 4-D tesseract display

### Cygwin configuration changes

There is now a single Cygwin configuration. It uses the X Window System if built with graphics enabled. The alternate configuration using native Windows graphics is no longer supported, and its non-standard compatibility functions are no longer available.

## Earlier feature additions

These features appeared in earlier releases of Icon but subsequent to publication of the Icon books.

### External values

(new with version 9.5.0 of Icon)

External code incorporated by `loadfunc()` can now create and return to Icon code opaque values that can be stored and passed on subsequent calls. See External Values for more information.

### Millions of colors

(new with version 9.4.2 of Icon)

Icon's X-windows interface no longer limits each window to 256 colors at one time. Median-cut quantization selects image colors when writing a GIF file.

### Scriptable source files

(new with version 9.4.1 of Icon)

An Icon source file can be made executable under Unix by prefixing it with a comment line

> `#!/usr/bin/env icon`

and setting its execute permission bit. This uses a new `icon` command, which in another form allows a small Icon program to be embedded within a shell script. See the man page for details. The traditional `icont` command remains available when more flexibility is needed.

### Path searching

(new with version 9.4.0 of Icon)

Under Unix, colons (`:`) may now separate directories in the `LPATH` and `IPATH` environment variables as an alternative to spaces. The Icon translator and linker search these paths when looking for `$include` and `link` files respectively.

The Icon program library is now searched automatically, but `LPATH` and `IPATH` can still be set to control the search order. The effective path in each case is:

1. The current directory
2. Any directories named by the environment variable
3. The Icon library directory

Other changes affect the configuration of Icon at installation time and the way executable Icon programs locate the interpreter. These changes, which are transparent to most users, are discussed in more detail on the File Organization page.

### Reading directory contents

(new with version 9.3.2 of Icon)

The files in a directory can be listed by opening the directory as a file. Subsequent reads return the names of the files contained in the directory. The names are returned in no particular order, and for Unix, the directories `"."` and `".."` are included.

### Reading foreign text files

(new with version 9.3.1 of Icon)

The function `read()` recognizes three kinds of line terminators when reading a file opened in translated mode: Windows (CR+LF), Macintosh (CR), or Unix (LF). Consequently, text files created on one platform can be read by an Icon program running on a different platform.

## Limitations, bugs, and problems

(This list has remained essentially unchanged for twenty years. The remaining knotty problems relate to fundamental design decisions.)

Icon deals strictly in 8-bit characters and expects a superset of ASCII such as ISO 8859-1 (“Latin 1”). It does not translate UTF-8 escape sequences and does not support Unicode.

Large integers cannot be used with `i to j`, with `seq()`, or with integer-valued keywords.

Large-integer literals are constructed at run-time, so such literals are best kept outside of loops.

Conversion of a large integer to a string is quadratic in the length of the integer. Conversion of a very large integer may take a long time.

An "evaluation stack overflow" can occur when a procedure is called with a huge number (thousands or more) of arguments. The capacity can be increased by setting the environment variable `MSTKSIZE` or `COEXPSIZE`, as appropriate.

Stack overflow checking uses a heuristic that is not always effective. Stack overflow in a co-expression is especially likely to escape detection and cause a mysterious program malfunction.

Pathologically nested structures can provoke a memory or segmentation fault during garbage collection by reaching the stack limit. The stack limit can be raised by the `limit` or `ulimit` shell command.

If an expression such as `x := create expr` is used in a loop, and `x` is not a global variable, uncollectable co-expressions accumulate with each iteration. This problem can be circumvented by making `x` a global variable or by assigning a value to `x` before the create operation, as in

> `x := &null
> x := create expr`

Integer overflow on exponentiation may not be detected during execution. Such overflow may occur during type conversion.

## Graphics system limitations, bugs, and problems

Icon graphics facilities utilize only server-side fonts (those listed by `xlsfonts`) and not the more modern client-side fonts.

Now that graphics memory is cheap, very few platforms require or support mutable colors. Icon code for mutable colors is still present but untested.

Windows are not always refreshed properly while a program is blocked awaiting standard input.

Depending on the window manager, values set and read back from the `pos`, `posx`, and `posy` attributes may be slightly inconsistent.

## Documentation

See the documentation guide for an overview of the available Icon documentation.

For installation instructions, see Installing Binaries or Building from Source as appropriate.

## Acknowledgments

Carl Sturtivant updated and maintained the Cygwin configuration. Jafar Al-Gharaibeh discovered two problems with co-expression switching and supplied corrective code.

Greg Buchholz published the `mandel3` program in comp.lang.icon. Chris Tenaglia contributed the `tess` program. David Gamey contributed the quadratic mean procedure `qmean()` as well as a fix for `spell()`. Jeremy Cowgar supplied the `levenshtein()` procedure.

Will Evans provided the fix for the PostScript recorder `psrecord`. Clint Jeffery supplied the `itlib` fix. Phillip Thomas and Clint Jeffery modified the `lisp` program. Tom Christopher supplied the `tempname` fix in some very old mail that was recently rediscovered.