amforth-devel

[Amforth] AmForth Weekend 4

[<ho...@tj...>]

Dear AmForthers,

I liked Erich's "AmForth Weekend" format, so I'm sticking with
it. This is AmForth Weekend 4. This weekend's motto is "Try not to
break anything".

The focus is on AVR8, amforth-shell.py and the website.

No release yet, but some activity in trunk.

Let me know what works, and what does not.

Best wishes,
Tristan

# SUMMARY

## AMFORTH-SHELL.PY

amforth-shell.py has had some syntax warning fixes and one new
feature. The syntax was correct at the time, but python has moved on.

A directive #stack has been added. This toggles on and off displaying
the contents of the mcu data stack as a prompt (if the word .s exists
on the device)

## AVR8

Within the existing codebase, some minor fixes to a handful of .asm
files that avra was rightly flagging with warnings about misalignment
in word name .db statements. Whilst avra padded these out correctly,
better to fix.

*Request for help* - I'm not a MS windows user, but I am keen that the
existing build system still works for MS windows. If you are a MS 
windows
user I would be grateful if you could try and build AmForth from trunk
and let me know if it still works for you.

## WEBSITE

This wasn't top of my initial list of things to look at. However,
without documentation, prebuilt hex files are of diminished
use. AmForth's documentation is a very special resource.  Time and
reST/Sphinx (the system that turns documentation source into html and
the website), however, have moved on. Running the documentation
through a modern Sphinx broke a few things on the site. These have
been fixed. Some missing svg files that were produced from dia format
files were salvaged from the 6.8 release. There remain some broken
links to missing pdfs/frt on the recognizer page. The documentation
source is available, but rebuilding requires a chain of personal
system upgrades I'm not quite ready for yet.

As an apprentice piece in writing something with reST, I've added a post
on the Opinion page.

## WHAT IS NEXT

Reference card
Prebuilt hex files for AVR8

## COMMITS

r2458 change of maintainer

r2459 minor fixes to amforth-shell.py syntax warnings fixed, modify #!
to a less fragile one

r2460 adds directive #stack to amforth-shell.py #stack toggles whether
the mcu data stack is displayed to left of input prompt > Default is
no.

r2461 fix .db padding warnings (from avra)

r2462 website update

Re: [Amforth] AmForth Weekend 4

[Martin N. <amf...@mg...>]

On Sun, 02 Nov 2025 14:40:07 +0000
ho...@tj... wrote:

> Dear AmForthers,
> 
> I liked Erich's "AmForth Weekend" format, so I'm sticking with
> it. This is AmForth Weekend 4. This weekend's motto is "Try not to
> break anything".
> 
> The focus is on AVR8, amforth-shell.py and the website.
> 
> No release yet, but some activity in trunk.
> 
> Let me know what works, and what does not.
> 
> Best wishes,
> Tristan
> 
> # SUMMARY
> 
> ## AMFORTH-SHELL.PY
> 
> amforth-shell.py has had some syntax warning fixes and one new
> feature. The syntax was correct at the time, but python has moved on.
> 
> A directive #stack has been added. This toggles on and off displaying
> the contents of the mcu data stack as a prompt (if the word .s exists
> on the device)
> 
> ## AVR8
> 
> Within the existing codebase, some minor fixes to a handful of .asm
> files that avra was rightly flagging with warnings about misalignment
> in word name .db statements. Whilst avra padded these out correctly,
> better to fix.
> 
> *Request for help* - I'm not a MS windows user, but I am keen that the
> existing build system still works for MS windows. If you are a MS 
> windows
> user I would be grateful if you could try and build AmForth from trunk
> and let me know if it still works for you.
> 
> ## WEBSITE
> 
> This wasn't top of my initial list of things to look at. However,
> without documentation, prebuilt hex files are of diminished
> use. AmForth's documentation is a very special resource.  Time and
> reST/Sphinx (the system that turns documentation source into html and
> the website), however, have moved on. Running the documentation
> through a modern Sphinx broke a few things on the site. These have
> been fixed. Some missing svg files that were produced from dia format
> files were salvaged from the 6.8 release. There remain some broken
> links to missing pdfs/frt on the recognizer page. The documentation
> source is available, but rebuilding requires a chain of personal
> system upgrades I'm not quite ready for yet.
> 
> As an apprentice piece in writing something with reST, I've added a
> post on the Opinion page.
> 
> ## WHAT IS NEXT
> 
> Reference card
> Prebuilt hex files for AVR8
> 
> ## COMMITS
> 
> r2458 change of maintainer
> 
> r2459 minor fixes to amforth-shell.py syntax warnings fixed, modify #!
> to a less fragile one
> 
> r2460 adds directive #stack to amforth-shell.py #stack toggles whether
> the mcu data stack is displayed to left of input prompt > Default is
> no.
> 
> r2461 fix .db padding warnings (from avra)
> 
> r2462 website update
> 
> 
> 
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
> 
> 

Thanks Tristan. Efforts much appreciated.

You didn't ask for them, but I have a couple of ideas for
amforth-shell.py:

1.
Have an "#ifndef FORTHWORD forthword.frt" directive. "#ifdef" also.

2.
Directives that take a path or filename will look for a partial path.
i.e:	#require project1/main.frt
	#require project2/main.frt
are considered different files. 

If either of these can be achieved by some other means, then please
chip in. I am aware of "#cd".

-- 
Regards,

Martin Nicholas.

E-mail: rep...@mg... (Address will be valid throughout 2025).

Re: [Amforth] AmForth Weekend 4

[<ho...@tj...>]

On 2025-11-05 08:46, Martin Nicholas via Amforth-devel wrote:
> On Sun, 02 Nov 2025 14:40:07 +0000

CUT

> You didn't ask for them, but I have a couple of ideas for
> amforth-shell.py:
> 
> 1.
> Have an "#ifndef FORTHWORD forthword.frt" directive. "#ifdef" also.
> 
> 2.
> Directives that take a path or filename will look for a partial path.
> i.e:	#require project1/main.frt
> 	#require project2/main.frt
> are considered different files.
> 
> If either of these can be achieved by some other means, then please
> chip in. I am aware of "#cd".

Hi Martin,

Thank you. Ideas are always welcome, and yours are very timely.

For 1. There might be an AmForth way or an amforth-shell way. Depends 
upon what we want to use #ifdef for.

AmForth way - with a "bigger" Forth than AmForth there would be the 
option of using [IF]..[ELSE]..[THEN]. AmForth does not have these 
extension words from [1] but it does have [DEFINED] and [UNDEFINED]. 
 From [2] on the website, a limited (by current SOURCE) Conditional 
Interpret can be achieved.

|S|    1|anew empty
|W|    2|
|S|    3|: ?\ ( f -- ) if postpone \ then ; immediate
|W|    4|
|S|    5|[defined]   3+ 0= ?\ : xx 3+ ;
|S|    6|[undefined] 3+ 0= ?\ : xx 2 + ;
|W|    7|
|S|    8|100 xx . cr
|O|    8|102
|W|    9|
|S|   10|: 3+ ( n -- n ) 3 + ;
|W|   11|
|S|   12|[defined]   3+ 0= ?\ : yy 3+ ;
|S|   13|[undefined] 3+ 0= ?\ : yy 2 + ;
|W|   14|
|S|   15|100 yy . cr
|O|   15|103

I *think* this can be extended a little

|S|   17|anew empty
|W|   18|
|S|   19|: ifdef  postpone   [defined] invert if postpone \ then  ; 
immediate
|S|   20|: ifndef postpone [undefined] invert if postpone \ then  ; 
immediate
|W|   21|
|S|   22|: zz
|S|   23|    ifdef  3+ 3+
|S|   24|    ifndef 3+ 2 +
|S|   25|;
|W|   26|
|S|   27|100 zz . cr
|O|   27|102
|W|   28|
|S|   29|: 3+ ( n -- n ) 3 + ;
|W|   30|
|S|   31|: zz
|S|   32|    ifdef  3+ 3+
|S|   33|    ifndef 3+ 2 +
|S|   34|;
|W|   35|
|S|   36|100 zz . cr
|O|   36|103

I've not tested this beyond the snippet above. It's not 
[IF]..[ELSE]..[THEN] by a long chalk but it's "all Forth" and it might 
do the job. Alternatively,

amforth-shell way - amforth-shell does some [pre|post]processing of 
serial streams to/from the mcu and can also interact using Forth with 
the mcu.  However, it has no conditional i.e. #ifdef ... capability. 
This is something I've wanted, but I've been putting off as

(a) amforth-shell.py is very reliable and I don't want to break it
(b) the serial "handshaking" needed is not easy - goto (a)

Recently, however, I have merged amforth-shell with a preprocessor. I've 
just added your idea, but renamed #ifdef to #ifword as #ifdef taken. 
Forth source can look like this. #dictionary queries mcu and fills local 
cache, #ifword queries local cache.

anew empty
#dictionary
: zz
     #ifword 3+
     3+
     #else
     2 +
     #endif
;
100 zz . cr
: 3+ ( n -- n ) 3 + ;
#dictionary
: zz
     #ifword 3+
     3+
     #else
     2 +
     #endif
;
100 zz . cr

which when uploaded to the mcu it looks like this. You only get to "see" 
what was left after the preprocessor has done its work.

|S|    1|anew empty
|S|    2|: zz
|S|    3|    2 +
|S|    4|;
|S|    5|100 zz . cr
|O|    5|102
|S|    6|: 3+ ( n -- n ) 3 + ;
|S|    7|: zz
|S|    8|    3+
|S|    9|;
|S|   10|100 zz . cr
|O|   10|103

It needs a lot more testing before it goes anywhere near the repo. If 
you are willing to alpha test it, I will tidy it up.

Best wishes,
Tristan

[1] 15.6.2 Programming-Tools extension words
     https://forth-standard.org/standard/tools

[2] 
https://amforth.sourceforge.net/TG/recipes/Conditional-Interpret.html

Re: [Amforth] AmForth Weekend 4

[Martin N. <amf...@mg...>]

On Fri, 07 Nov 2025 17:28:45 +0000
ho...@tj... wrote:
 
> It needs a lot more testing before it goes anywhere near the repo. If 
> you are willing to alpha test it, I will tidy it up.
> 

Certainly, send it over.

-- 
Regards,

Martin Nicholas.

E-mail: rep...@mg... (Address will be valid throughout 2025).