gforth warning: hex. is obsolete

[Buzz McCool]

I use gforth in a terminal window to type in some quick conversions
between decimal and hexadecimal numbers. After a recent upgrade to a new
gforth version I see:


$ gforth
Gforth 0.7.9_20240104

$ff ok 1
. 255 ok
255 ok 1
hex.
*terminal*:4:1: warning: hex. is obsolete$FF ok


What am I supposed to be using in place of "hex." to display a number in
hexadecimal? I see some recommendations like "Don’t use hex, use
base-execute instead." in the manual, but I don't understand what that
is trying to tell me. Is there a tutorial on new style gforth number
base conversions somewhere, preferably with lots of examples?

Note that when using a search engine to research this issue, the first
hits that come up are from this site with a very old manual:
https://www.complang.tuwien.ac.at/forth/gforth/Docs-html/
which says "This manual is for Gforth (version 0.7.0, November 2, 2008)".

Further down in the list of search engine suggestions is a recent manual
version https://gforth.org/manual/index.html which says "This manual is
for Gforth (version 0.7.9_20240229, February 29, 2024)".

[dxf]

Post by Buzz McCool
$ gforth
Gforth 0.7.9_20240104
$ff  ok 1
. 255  ok
255  ok 1
hex.
*terminal*:4:1: warning: hex. is obsolete$FF  ok
What am I supposed to be using in place of "hex." to display a number in hexadecimal?

Did you try h. ?

As for docs 'locate hex.' will point you to the file where it's defined and
alternatives might exist.

[a***@spenarnc.xs4all.nl]

Post by Buzz McCool

Post by Buzz McCool
I use gforth in a terminal window to type in some quick conversions

between decimal and hexadecimal numbers. After a recent upgrade to a new

Post by Buzz McCool
$ gforth
Gforth 0.7.9_20240104
$ff  ok 1
. 255  ok
255  ok 1
hex.
*terminal*:4:1: warning: hex. is obsolete$FF  ok
What am I supposed to be using in place of "hex." to display a number

in hexadecimal?
Did you try h. ?
As for docs 'locate hex.' will point you to the file where it's defined and
alternatives might exist.

Neither will work with 0.7.3 that most people have.
Groetjes Albert

[dxf]

Post by a***@spenarnc.xs4all.nl

Post by Buzz McCool

Post by Buzz McCool
I use gforth in a terminal window to type in some quick conversions

between decimal and hexadecimal numbers. After a recent upgrade to a new

Post by Buzz McCool
$ gforth
Gforth 0.7.9_20240104
$ff  ok 1
. 255  ok
255  ok 1
hex.
*terminal*:4:1: warning: hex. is obsolete$FF  ok
What am I supposed to be using in place of "hex." to display a number

in hexadecimal?
Did you try h. ?
As for docs 'locate hex.' will point you to the file where it's defined and
alternatives might exist.

Neither will work with 0.7.3 that most people have.
Groetjes Albert

Too bad. I assumed it was only Windows users that didn't know to compile from
source and must take what's given them.

[Anton Ertl]

Post by a***@spenarnc.xs4all.nl

Post by dxf

Post by Buzz McCool
*terminal*:4:1: warning: hex. is obsolete$FF  ok

[...]

Post by a***@spenarnc.xs4all.nl

Post by dxf
Did you try h. ?
As for docs 'locate hex.' will point you to the file where it's defined and
alternatives might exist.

Neither will work with 0.7.3 that most people have.

But then, if you use Gforth 0.7.3., you don't get this warning.

- anton

[Anton Ertl]

Post by Buzz McCool
I use gforth in a terminal window to type in some quick conversions
between decimal and hexadecimal numbers. After a recent upgrade to a new
$ gforth
Gforth 0.7.9_20240104
$ff ok 1
. 255 ok
255 ok 1
hex.
*terminal*:4:1: warning: hex. is obsolete$FF ok
What am I supposed to be using in place of "hex." to display a number in
hexadecimal?

H.

This is in line with common practice in other Forth systems.

Post by Buzz McCool
I see some recommendations like "Don’t use hex, use
base-execute instead." in the manual, but I don't understand what that
is trying to tell me.

This is about the standard word "HEX", not the Gforth word "HEX.".
HEX permanently changes BASE, whereas BASE-EXECUTE changes it only for
the word which it EXECUTEs. A permanent change is not appropriate for
use in a generally useful definition.

- anton

[Anton Ertl]

Post by Buzz McCool
What am I supposed to be using in place of "hex." to display a number in
hexadecimal?

H.

If you build Gforth from he now-current source, and then ask the new
Gforth

help hex.

it will tell you

'hex.' ( u -- ) gforth-obsolete "hex."
Old name for 'h.' ok

For a slightly older Gforth, the answer you get is:

No documentation for hex., LOCATEing source
stuff.fs:677
[...]
synonym hex. h. \ gforth-obsolete
\G Display @i{u} as an unsigned hex number, prefixed with a "$" and
\G followed by a space.
[...]

Here you can see that HEX. is a synonym for H.

- anton

[minforth]

BTW (I don't know gforth well enough) is there any formatted output in gforth
e.g. similar to C printf?

Contrived: 12 dup "This is %d in hex: %X" -> This is 12 in hex: C

[Anton Ertl]

Post by minforth
BTW (I don't know gforth well enough) is there any formatted output in gforth
e.g. similar to C printf?
Contrived: 12 dup "This is %d in hex: %X" -> This is 12 in hex: C

I would write that as

12 ." This is " dup dec. ." in hex: " h.

Output:

This is 12 in hex: $C

If you insist on output without "$", it would be

12 ." This is " dup dec. ." in hex: " `u. $10 base-execute

Alternatively, you can also use C's printf:

c-library printf-nn-lib
\c #include <stdio.h>
c-function printf-nn printf a n n -- n
end-c-library
"This is %d in hex: %X\000" drop 12 dup printf-nn drop

- anton

[PMF]

Post by Anton Ertl

Post by Buzz McCool
I use gforth in a terminal window to type in some quick conversions
between decimal and hexadecimal numbers. After a recent upgrade to a new
$ gforth
Gforth 0.7.9_20240104
$ff ok 1
. 255 ok
255 ok 1
hex.
*terminal*:4:1: warning: hex. is obsolete$FF ok
What am I supposed to be using in place of "hex." to display a number in
hexadecimal?

H.
This is in line with common practice in other Forth systems.

lxf/ntf has had h. from the beginning. It is one of the most used debugging tools!
There is also h.s which show the stack items in hex and .. that dumps and clears the stack

BR
Peter

[mhx]

Post by PMF

Post by Anton Ertl

Post by Buzz McCool
What am I supposed to be using in place of "hex." to display a number in
hexadecimal?

H.
This is in line with common practice in other Forth systems.

lxf/ntf has had h. from the beginning. It is one of the most used debugging tools!
There is also h.s which show the stack items in hex and .. that dumps and clears the stack

FORTH> .s
Data: ---
System: ---
Float: --- ok
FORTH> 123 77 >s pi .s
Data: 123 ---
System: 77 ---
Float: 3.1415926535897932385 --- ok
[1]<1>{1}FORTH> -1. .s
Data: 123 -1 -1 ---
System: 77 ---
Float: 3.1415926535897932385 --- ok
[3]<1>{1}FORTH> -s e. d. . 3.141593e0 -1 123 ok
FORTH> hex 123 .s
Data: 123 ---
System: ---
Float: --- ok
[1]FORTH> . 123 ok
FORTH> decimal 123 hex .s
Data: 7B ---
System: ---
Float: --- ok
[1]FORTH> . decimal 7B ok

-marcel

[a***@spenarnc.xs4all.nl]

Post by PMF

Post by Anton Ertl

Post by Buzz McCool
I use gforth in a terminal window to type in some quick conversions
between decimal and hexadecimal numbers. After a recent upgrade to a new
$ gforth
Gforth 0.7.9_20240104
$ff ok 1
. 255 ok
255 ok 1
hex.
*terminal*:4:1: warning: hex. is obsolete$FF ok
What am I supposed to be using in place of "hex." to display a number in
hexadecimal?

H.
This is in line with common practice in other Forth systems.

lxf/ntf has had h. from the beginning. It is one of the most used debugging tools!
There is also h.s which show the stack items in hex and .. that dumps and clears the stack

H. is present in almost forth systems originating from the Netherlands.

Post by PMF
BR
Peter

Groetjes Albert

[Buzz McCool]

Post by Anton Ertl

Post by Buzz McCool
What am I supposed to be using in place of "hex." to display a number in
hexadecimal?

H.
This is in line with common practice in other Forth systems.

I see dec. documented,
https://gforth.org/manual/Word-Index.html#Word-Index_fn_letter-D

but not h.
https://gforth.org/manual/Word-Index.html#Word-Index_fn_letter-H

The older 0.7.0 docs does show hex. (but not h.) in both the word index
and the "Simple-numeric-output" section.

[Anton Ertl]

Post by Buzz McCool
but not h.
https://gforth.org/manual/Word-Index.html#Word-Index_fn_letter-H

Yes, I only added H. to the documentation yesterday. In general,
documentation is quite a bit behind development, and the state of the
documentation is why we have not released Gforth 1.0 yet. I document
as I find the time.

- anton

[a***@spenarnc.xs4all.nl]

Post by Anton Ertl

Post by Buzz McCool
but not h.
https://gforth.org/manual/Word-Index.html#Word-Index_fn_letter-H

Yes, I only added H. to the documentation yesterday. In general,
documentation is quite a bit behind development, and the state of the
documentation is why we have not released Gforth 1.0 yet. I document
as I find the time.

Without further comment I recite the history of adding NIP to ciforth. 1]
I was reluctant to introduce it, as it wasn't present in fig-Forth.
ROT and SWAP are changing the stack order, which is bad and is not to
be obscured. I felt that NIP was hiding a SWAP, but after all NIP
doesn't actually change the stack order. That was the reason that
Chuck Moore uses it, probably.
(New words are not added lightly to the ciforth core.)

---------------
worddoc( {JUGGLING},{NIP},{nip},{n1 n2---n2},{ISO},
{Drop the second number from the stack.},
{{DUP},{DROP},{SWAP},{OVER}},
{{S0 @ DSP! 1 2 3 4 NIP .S},{S[ 1 2 4 ]},
{S0 @ DSP!},{} },
enddoc)
CODE_HEADER({NIP},{NIP})
POP AX
POP BX
PUSH AX
_NEXT
---------------

A new word is to be preceeded by a worddoc macro.
It is explained in the documentation of the generic system cifgen.info.
(this is not the forth itself)
---------------------------------------
The 'worddoc' macro defines a structure with additional information
of a word. Generally it is placed in front of the word. The same word
can be found several times in the input file, but only one is selected
in a particular configuration. The same goes for the corresponding
'worddoc' .
Its fields are:
1. Wordset name.
2. Word name.
3. Pronunciation. This is a pure textual and pronounceable
identification of the word. It is also used in 'texinfo' that
doesn't handle special characters well.
4. Stack effect. The stack effect obeys all the conventions put forth
in the user manual.
5. Properties. Properties are i.a. immediate and such, and the
standards with which this word complies. Again this is described
in the user manual.
6. Description.
7. References. This is a list of names of other Forth words, that can
be studied to better understand this one.
8. Tests. This is a list. The first and all other odd members is a
test, code that can be passed to Forth. The second and all other
even members is the expected outcome of the preceding test.
'worddoc' are such that a structure starts with 'worddoc( ' and end
with a '})' at the end of a line. This means that a worddoc can be
simply skipped if it occurs in Forth code, by defining a word 'worddoc('
that reads and ignores source up to the end sentinel.
--------------------------------------------

1] This is as far as it goes. Of course NIP was present in the library.

Post by Anton Ertl
- anton

Groetjes Albert

[minforth]

I am guessing that NIP came in with TOS caching, because with it
NIP is just a stack pointer in- or decrement

[dxf]

Post by minforth
I am guessing that NIP came in with TOS caching, because with it
NIP is just a stack pointer in- or decrement

Likely it was frequency. In the F83 distribution NIP occurs 21 times.
Don't know if it was they who coined it but it seems to have taken off
from there (F83 being the replacement for FigForth).

[Anton Ertl]

Post by dxf

Post by minforth
I am guessing that NIP came in with TOS caching, because with it
NIP is just a stack pointer in- or decrement

Likely it was frequency. In the F83 distribution NIP occurs 21 times.

130 occurences of NIP in the Gforth image (for comparison, 545
occurences of DROP).

- anton

[minforth]

Post by dxf
(F83 being the replacement for FigForth).

You probably mean Forth-83. It did not comprise NIP.
(F83 was Laxen&Perry although popular)

[Paul Rubin]

Post by Anton Ertl
H.
This is in line with common practice in other Forth systems.

The warning message about HEX. is annoying in a system that has been
around for so long. IMHO it would be better for HEX. and H. to both
work, without HEX. generating unnecessary warning messages.

[dxf]

Post by Paul Rubin

Post by Anton Ertl
H.
This is in line with common practice in other Forth systems.

The warning message about HEX. is annoying in a system that has been
around for so long. IMHO it would be better for HEX. and H. to both
work, without HEX. generating unnecessary warning messages.

Can't say I've felt the need for either given auto stack display:

123 -123 ok 123 -123 <
hex ok 7B FF85 <
decimal ok 123 -123 <

Should I need formatted hex in an app I have library routines for that.

[a***@spenarnc.xs4all.nl]

Post by Paul Rubin

Post by Anton Ertl
H.
This is in line with common practice in other Forth systems.

The warning message about HEX. is annoying in a system that has been
around for so long. IMHO it would be better for HEX. and H. to both
work, without HEX. generating unnecessary warning messages.

It is reasonably absurd that there is a warning about HEX. and that
H. is undocumented at the same time.

Groetjes Albert

[Anton Ertl]

Post by Paul Rubin

Post by Anton Ertl
H.
This is in line with common practice in other Forth systems.

The warning message about HEX. is annoying in a system that has been
around for so long. IMHO it would be better for HEX. and H. to both
work,

They both work (for now).

Post by Paul Rubin
without HEX. generating unnecessary warning messages.

You can turn off warnings with

WARNINGS OFF

but of course that also turns off all other warnings.

- anton

[Buzz McCool]

... IMHO it would be better for HEX. and H. to both
work, without HEX. generating unnecessary warning messages.

Given there is a DEC. word, having a HEX. word (that doesn't throw
errors) does seem more intuitive / orthogonal than just the H. found in
other Forth systems.

[a***@spenarnc.xs4all.nl]

Post by Buzz McCool

... IMHO it would be better for HEX. and H. to both
work, without HEX. generating unnecessary warning messages.

Given there is a DEC. word, having a HEX. word (that doesn't throw
errors) does seem more intuitive / orthogonal than just the H. found in
other Forth systems.

Tradition trumps intuition.

If you design a Forth-like language from scratch that is consistent and
orthogonal, there is a whole bunch more that you have to do.

Groetjes Albert

[minforth]

Post by a***@spenarnc.xs4all.nl
If you design a Forth-like language from scratch that is consistent and
orthogonal, there is a whole bunch more that you have to do.

For instance, start with a grammar, and with dynamic strings as fundamental
data type ... ;-)

[mhx]

Post by minforth

Post by a***@spenarnc.xs4all.nl
If you design a Forth-like language from scratch that is consistent and
orthogonal, there is a whole bunch more that you have to do.

For instance, start with a grammar, and with dynamic strings as fundamental
data type ... ;-)

How to define a grammar for a language that allows to change every word in both
name and behavior, depending on various contexts?

Defining a set of useful libraries, now *that* seems possible.

-marcel

[minforth]

Post by mhx

Post by minforth

Post by a***@spenarnc.xs4all.nl
If you design a Forth-like language from scratch that is consistent and
orthogonal, there is a whole bunch more that you have to do.

For instance, start with a grammar, and with dynamic strings as fundamental
data type ... ;-)

How to define a grammar for a language that allows to change every word in both
name and behavior, depending on various contexts?

The first thing to prevent is that standard words can be changed. If you want a variant,
give the variant a different name. E.G.
DUP = fixed standard in capital letters
dup, Dup, mydup, MYDUP etc = variants

And don't call the Forth-like language FORTH to scare away language lawyers ;-)

[dxf]

Post by a***@spenarnc.xs4all.nl

Post by Buzz McCool

... IMHO it would be better for HEX. and H. to both
work, without HEX. generating unnecessary warning messages.

Given there is a DEC. word, having a HEX. word (that doesn't throw
errors) does seem more intuitive / orthogonal than just the H. found in
other Forth systems.

Tradition trumps intuition.
If you design a Forth-like language from scratch that is consistent and
orthogonal, there is a whole bunch more that you have to do.

Intuition is memory - nothing more.

[mhx]

dxf wrote:
[..]

Post by dxf
Intuition is memory - nothing more.

It includes reptile memory.

-marcel

[dxf]

Post by mhx
[..]

Post by dxf
Intuition is memory - nothing more.

It includes reptile memory.
-marcel

That accounts for the printf proposals we keep seeing.

[Buzz McCool]

... If you design a Forth-like language from scratch that is consistent and
orthogonal, there is a whole bunch more that you have to do.

Understood.

I'm also perturbed that even fairly recent gforth releases don't support
the h. word at all (see below). So I have to upgrade all my systems to
the most recent gforth (WSL seems to have heartburn with some of them so
I'll have to work that out), or use hex. and get warning messages on
some of them.

$ gforth
Gforth 0.7.9_20220428

255 ok 1
hex. $FF ok

255 ok 1
h.
*the terminal*:9:1: error: Undefined word

h.<<<

Backtrace:
kernel/int.fs:321:10: 0 $7F96CEE5C430 throw

[Anton Ertl]

Post by Buzz McCool
Given there is a DEC. word, having a HEX. word (that doesn't throw
errors) does seem more intuitive / orthogonal than just the H. found in
other Forth systems.

That's a good argument, and the other is that while H. is more in line
with other Forth systems, HEX. is better if you are using several
Gforth systems with different ages. So I have unobsoleted HEX.

- anton

[Buzz McCool]

... So I have unobsoleted HEX.

Once again Anton, I thank you for your attention and consideration.