Check-in [c602e5096b]

preferable.  Example uses of raw input include text editors \(such as
vi or emacs\) or terminal-based menu systems.

I propose supporting these operation modes within Tcl through a single
new option to the **fconfigure** command \(to definitely be implemented
on Unix serial channels — because that is the type of stdin in a
normal interactive session — and suitably on other platforms if
possible\): **-inputmode**.  This will have three legal values:

 * **normal**: This will turn on both echoing and cooking of input, and can be
   considered to be the default configuration for all terminals.

 * **password**: This will turn off echoing but leave cooking turned on.  Note
   that on at least one platform (macOS) this additionally changes the cursor
   in the terminal.

preferable.  Example uses of raw input include text editors \(such as
vi or emacs\) or terminal-based menu systems.

I propose supporting these operation modes within Tcl through a single
new option to the **fconfigure** command \(to definitely be implemented
on Unix serial channels — because that is the type of stdin in a
normal interactive session — and suitably on other platforms if
possible\): **-inputmode**.  This will have four legal values:

 * **normal**: This will turn on both echoing and cooking of input, and can be
   considered to be the default configuration for all terminals.

 * **password**: This will turn off echoing but leave cooking turned on.  Note
   that on at least one platform (macOS) this additionally changes the cursor
   in the terminal.

index formats.  Thus it is reasonable to provide a standard substring insertion
command.

The current design of [`string replace`] expressly (albeit inexplicably)
prevents its use for performing string insertion.  TIP 323 originally proposed
to extend [`string replace`] to allow string insertion, but this aspect of TIP
323 was [withdrawn]
(https://core.tcl.tk/tips/fdiff?v1=6e0ba0ee9838accc&v2=34809f1432fc528f&sbs=1)
for the sake of compatibility.

> *Clarification: TIP 504 proposes no changes to the semantics of [`string
> replace`].*

To mirror the behavior of [`linsert`], [`string insert`] at `end` should append
to the string.  This is in conflict with [`string replace`], were it to be
................................................................................
>
    # Bind [string insert] to [::tcl::string::insert].
    namespace ensemble configure string -map [dict replace\
            [namespace ensemble configure string -map]\
            insert ::tcl::string::insert]

More sample implementations can be found on the [Additional String Functions]
(http://wiki.tcl.tk/44#pagetoc706ab8bb) page of the Tcler's Wiki, but at time of
writing, they do not handle end-relative indexing nor can be used to append to a
string.  Since they are implemented in terms of [`string replace`] and do not
perform any index arithmetic of their own, they actually do support TIP 176
indexes.

# Compatibility Considerations

................................................................................

Add a new [`string insert`] command:

> **string insert** *string index insertString*

> Returns a copy of *string* with *insertString* inserted at the *index*'th
> character.  *index* may be specified as described in the [**STRING
> INDICES**](https://www.tcl.tk/man/tcl/TclCmd/string.htm#M54) section.

> If *index* is start-relative, the first character inserted in the returned
> string will be at the specified index.  If *index* is end-relative, the last
> character inserted in the returned string will be at the specified index.

> If *index* is at or before the start of *string* (e.g., *index* is **0**),
> *insertString* is prepended to *string*.  If *index* is at or after the end of
................................................................................
> *string* (e.g., *index* is **end**), *insertString* is appended to *string*.

# Reference Implementation

A pure Tcl reference implementation is given [above](#ref).

The [`dgp-string-insert`]
(http://core.tcl.tk/tcl/timeline?t=dgp-string-insert) branch in the Tcl Fossil
repository provides an implementation of the proposed subcommand, complete
with documentation, bytecode compilation, and a set of test cases.

# Future Work

The direct evaluation of [`string insert`] is routed though a new 
internal routine `TclStringReplace`. It is a conventional substring
................................................................................
of functionality for other [`string foo`] subcommands.

The existing internal routine `TclStringReplace` does not include
the full collection of optimizations that the prior routine
`Tcl_ReplaceObj` did. Since this routine remains internal, it can
continue to gain these revisions without further TIP examination.
Likewise, alternative bytecode compiler and execution strategies may
also be pursuse internally.

These routines may be good candidates to become available to applications
and extensions in the public C API. The current TIP does not propose that.
It is out of scope. A set of questions will need to be addressed when
considering converting these routines into public ones. First it will
need to be determined what level of robustness to present in a public
interface. Should such a function be permitted to fail or even abort

index formats.  Thus it is reasonable to provide a standard substring insertion
command.

The current design of [`string replace`] expressly (albeit inexplicably)
prevents its use for performing string insertion.  TIP 323 originally proposed
to extend [`string replace`] to allow string insertion, but this aspect of TIP
323 was [withdrawn]
(https://core.tcl-lang.org/tips/fdiff?v1=6e0ba0ee9838accc&v2=34809f1432fc528f&sbs=1)
for the sake of compatibility.

> *Clarification: TIP 504 proposes no changes to the semantics of [`string
> replace`].*

To mirror the behavior of [`linsert`], [`string insert`] at `end` should append
to the string.  This is in conflict with [`string replace`], were it to be
................................................................................
>
    # Bind [string insert] to [::tcl::string::insert].
    namespace ensemble configure string -map [dict replace\
            [namespace ensemble configure string -map]\
            insert ::tcl::string::insert]

More sample implementations can be found on the [Additional String Functions]
(https://wiki.tcl-lang.org/page/Additional+string+functions#d87fded503e2e2268e274b6a4d499750adb9d4c3e4dd2ec833c76a1d0a3254ca) page of the Tcler's Wiki, but at time of
writing, they do not handle end-relative indexing nor can be used to append to a
string.  Since they are implemented in terms of [`string replace`] and do not
perform any index arithmetic of their own, they actually do support TIP 176
indexes.

# Compatibility Considerations

................................................................................

Add a new [`string insert`] command:

> **string insert** *string index insertString*

> Returns a copy of *string* with *insertString* inserted at the *index*'th
> character.  *index* may be specified as described in the [**STRING
> INDICES**](https://www.tcl-lang.org/man/tcl/TclCmd/string.htm#M54) section.

> If *index* is start-relative, the first character inserted in the returned
> string will be at the specified index.  If *index* is end-relative, the last
> character inserted in the returned string will be at the specified index.

> If *index* is at or before the start of *string* (e.g., *index* is **0**),
> *insertString* is prepended to *string*.  If *index* is at or after the end of
................................................................................
> *string* (e.g., *index* is **end**), *insertString* is appended to *string*.

# Reference Implementation

A pure Tcl reference implementation is given [above](#ref).

The [`dgp-string-insert`]
(https://core.tcl-lang.org/tcl/timeline?t=dgp-string-insert) branch in the Tcl Fossil
repository provides an implementation of the proposed subcommand, complete
with documentation, bytecode compilation, and a set of test cases.

# Future Work

The direct evaluation of [`string insert`] is routed though a new 
internal routine `TclStringReplace`. It is a conventional substring
................................................................................
of functionality for other [`string foo`] subcommands.

The existing internal routine `TclStringReplace` does not include
the full collection of optimizations that the prior routine
`Tcl_ReplaceObj` did. Since this routine remains internal, it can
continue to gain these revisions without further TIP examination.
Likewise, alternative bytecode compiler and execution strategies may
also be pursued internally.

These routines may be good candidates to become available to applications
and extensions in the public C API. The current TIP does not propose that.
It is out of scope. A set of questions will need to be addressed when
considering converting these routines into public ones. First it will
need to be determined what level of robustness to present in a public
interface. Should such a function be permitted to fail or even abort

image formats do not scale and are too tiny on high resolution mobile devices.
The same goes for the image formats provided by the [Img][] extension.

The response to this challenge in general (on the web, in applications, etc.)
has been to adopt the [SVG][] format, as that is scalable and does not
typically depend on being rendered at a particular resolution.
Moreover, there is already a Tk image extension to do the conversion,
[tksvg][]. The implementation is using the [nanosvg][] library It has no other
external dependencies and is only 2 header files.

[nanosvg][] was choosen because it:

- has a suitable license
- is written in 2 plain C header files and can be easily included
- is really lightweight
................................................................................
scope of this TIP.
A description of the features and limitations of the current implementation is in section [Supported SVG](#Supported-SVG). It will be also described in the photo(n) man page.

The **svg** image format has the following format suboptions:

 > **svg** **-dpi** _dpiValue_ **-scale** _scaleValue_ **-unit** _unitValue_

*dpiValue* is used in conversion between given coordiantes and screen resolution. The value must be greater then 0.0. The default value is `96`.

*scaleValue* is used to scale the resulting image. The value must be greater then 0.0. The default value is `1.0`.

*unitValue* is the unit of all coordinates in the svg data. Available units are `px` (default, coordinates in pixel), `pt` (1/72 inch), `pc` (12 pt), `mm`, `cm` and `in`.

The given format options are only used at creation time of the image and are not preserved in the image. This means that:

image formats do not scale and are too tiny on high resolution mobile devices.
The same goes for the image formats provided by the [Img][] extension.

The response to this challenge in general (on the web, in applications, etc.)
has been to adopt the [SVG][] format, as that is scalable and does not
typically depend on being rendered at a particular resolution.
Moreover, there is already a Tk image extension to do the conversion,
[tksvg][]. The implementation is using the [nanosvg][] library. It has no other
external dependencies and is only 2 header files.

[nanosvg][] was choosen because it:

- has a suitable license
- is written in 2 plain C header files and can be easily included
- is really lightweight
................................................................................
scope of this TIP.
A description of the features and limitations of the current implementation is in section [Supported SVG](#Supported-SVG). It will be also described in the photo(n) man page.

The **svg** image format has the following format suboptions:

 > **svg** **-dpi** _dpiValue_ **-scale** _scaleValue_ **-unit** _unitValue_

*dpiValue* is used in conversion between given coordinates and screen resolution. The value must be greater then 0.0. The default value is `96`.

*scaleValue* is used to scale the resulting image. The value must be greater then 0.0. The default value is `1.0`.

*unitValue* is the unit of all coordinates in the svg data. Available units are `px` (default, coordinates in pixel), `pt` (1/72 inch), `pc` (12 pt), `mm`, `cm` and `in`.

The given format options are only used at creation time of the image and are not preserved in the image. This means that: