Check-in [c602e5096b]

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Fix minor nits found by AK
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: c602e5096b3b3bb6c2663982e2ad1dd7e4f3f8d5f03e984cf318c6b9d4132fb2
User & Date: dkf 2019-04-14 07:57:26
Context
2019-04-14
14:12
TIP vote results recorded check-in: 7c4444a23b user: dkf tags: trunk
07:57
Fix minor nits found by AK check-in: c602e5096b user: dkf tags: trunk
2019-04-12
13:00
New state of tip510. oo::clas like widgets, dynamic configure, additional widgets check-in: 9a757d6209 user: rene tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to tip/160.md.

80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
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.






|







80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
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.

Changes to tip/504.md.

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
...
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
...
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
...
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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






|







 







|







 







|







 







|







 







|







35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
...
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
...
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
...
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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

Changes to tip/507.md.

20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
..
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
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:







|







 







|







20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
..
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
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: