6502.org Forum  Projects  Code  Documents  Tools  Forum
It is currently Sat Apr 27, 2024 11:41 pm

All times are UTC




Post new topic Reply to topic  [ 10 posts ] 
Author Message
PostPosted: Tue Mar 16, 2021 3:59 pm 
Offline

Joined: Sun Apr 26, 2020 3:08 am
Posts: 357
My dictionary is getting quite large and is wondering what some do to remember a words' usage?

A method I find helps is with the use of symbols at the beginning of a word to identify a word type:

w=word
-w (dashw) - used in words that start a search or do a negative rotation ( -FIND -ROT )
(w) - used on words that are a dependency - words are not called directly
[w] - used on words that are immediate
?w - used on words that question an operation and leave a flag: ( Is it empty? or Should it be? as in ?STACK ?DEPTH ?DUP ?KEY )
w? - used on words that want a calculated value returned or text entered as in ( MEM? enter FILENAME? KEY?)
difference between: ?KEY - checks if a key has been pressed whereas KEY? returns a character that was pressed
same as: ?DEPTH - checks if stack is empty, but DEPTH? returns how deep the stack is
.w (dotw) - used on words that print a value or do a calculation ( PAD returns the address whereas .PAD returns its contents )
v.w - identifies a variable
c.w - identifies a constant
u.w - identifies a user variable

Or is there an easier method of remembering dictionary words and their usage?


Top
 Profile  
Reply with quote  
PostPosted: Tue Mar 16, 2021 6:00 pm 
Offline

Joined: Sun May 13, 2018 5:49 pm
Posts: 247
Have you seen the Forth style guide (titled "Summary of Style Conventions") in the back of "Thinking Forth" by Leo Brodie (in Appendix E).
http://thinking-forth.sourceforge.net/

There's also an HTML version of that same style guide on forth.org, but it has lost some of the formatting from the book and suffers greatly for it. Go look up the book (starting on page 283, but it shows as page 301 in my PDF reader) to get the original version.

While you are certainly welcome to use whatever convention works for you, having a style guide is nice when you'd like to work with others - it reduces their mental burden of having to figure out what your conventions are. It's not a completely exhaustive list, but it's a good place to start and reading it helped me be able to read other people's Forth code.


Top
 Profile  
Reply with quote  
PostPosted: Tue Mar 16, 2021 7:03 pm 
Offline
User avatar

Joined: Fri Aug 30, 2002 1:09 am
Posts: 8428
Location: Southern California
It's always good to have some sort of manual available as you program, whether on the screen, on paper, whatever. I have all my 6502 or '816 Forth source code available in text files and a quick search always gets me everything I could ever want to know about a word. My work goes in waves, so I might be developing code for some application, and when that part of the work is done, I might not have much contact with Forth at all for many months, and then when I come back to it the next time I may not remember if UM/MOD leaves the remainder on top for example. The source code will have the stack-effect comments, show dependencies, precedence (ie, whether it's IMMEDIATE or not), and other things.

I would encourage sticking with the standards anytime you don't have a good reason to deviate though. For example, the standard word for returning the data stack depth is DEPTH, not DEPTH? which sounds like it should return a flag. PAD returns an address, and the standard way to get the contents would be PAD @ . However, PAD is used for strings, including pictured numeric output, meaning you might not have much use for a word that returns the contents of just the one byte at address PAD. For my '816 Forth, I have the equivalent of shadow-screen files (although they're text files, not screen files) that have more explanation on the words that need it, including a few short paragraphs on the use of PAD. These files also have the equivalent Forth code describing what primitives are doing. For example, the "shadow screen" file has for ABS (the word that replaces the value at the TOS with its absolute value):

Code:
: ABS                           ( n -- |n| )    \               SF97
   DUP 0<
   IF  NEGATE THEN      ;

(the "SF97" meaning it's in "Starting Forth," page 97); but in the assembly-language source code it's

Code:
      HEADER "ABS", NOT_IMMEDIATE             ; ( n -- |n| )
ABS:  PRIMITIVE
      LDY     1,X             ; Look at high byte only.
      BMI     NEGATE+2        ; If it's negative, negate the number.
      GO_NEXT
 ;-------------------
which is both five bytes shorter and much, much faster-executing.

_________________
http://WilsonMinesCo.com/ lots of 6502 resources
The "second front page" is http://wilsonminesco.com/links.html .
What's an additional VIA among friends, anyhow?


Top
 Profile  
Reply with quote  
PostPosted: Tue Mar 16, 2021 8:36 pm 
Offline

Joined: Sun Apr 26, 2020 3:08 am
Posts: 357
SamCoVT wrote:
Have you seen the Forth style guide (titled "Summary of Style Conventions") in the back of "Thinking Forth" by Leo Brodie (in Appendix E).
http://thinking-forth.sourceforge.net/

No I hadn't. Thanks. I didn't expect it to be such a detailed read. Everything else I came across was just basic stuff.


Top
 Profile  
Reply with quote  
PostPosted: Tue Mar 16, 2021 9:09 pm 
Offline

Joined: Sun Apr 26, 2020 3:08 am
Posts: 357
GARTHWILSON wrote:
[color=#000000]It's always good to have some sort of manual available as you program, whether on the screen, on paper, whatever. I have all my 6502 or '816 Forth source code available in text files and a quick search always gets me everything I could ever want to know about a word.

Yep. I wouldn't have accomplished as much if it wasn't for the ability to multi-task on a modern machine. Very handy to keep lots of notes. But I will be uploading my work to a group of people who want to play on their real machines. Multi-tasking and tons of text files for notes won't be an option.

Quote:
I would encourage sticking with the standards anytime you don't have a good reason to deviate though. For example, the standard word for returning the data stack depth is DEPTH, not DEPTH? which sounds like it should return a flag. PAD returns an address, and the standard way to get the contents would be PAD @ . However, PAD is used for strings, including pictured numeric output, meaning you might not have much use for a word that returns the contents of just the one byte at address PAD. For my '816 Forth, I have the equivalent of shadow-screen files (although they're text files, not screen files) that have more explanation on the words that need it, including a few short paragraphs on the use of PAD.

The one nice thing about the Forth I am using is that it can be programmed to follow any standard without actuall following a standard. My Forth (which is an adaptation between all Forths from 78 to Ansi) is actually quite a bit less convoluted than any single Forth standard. Which means it is a lot less complicated and a lot easier to understand. I will leave it up to the user to create the necessary words to which standard they wish to follow. For now though still picking out the best methods of each standard to adopt. Although Ansi is the newest standard to follow, I still find it somewhat restrictive in some cases and over-bloated in others for what I need to accomplish.

?DEPTH is supposed to do exactly what you understood. It is meant to leave a flag to indicate if the stack is empty. For instance, the normal way to do a LIST is (screen #) LIST. But if I program ?DEPTH into LIST, LIST can now be used without a number on the data stack, and if the data stack is empty, it will use the last screen number that was saved into SCR. Very handy when the screen constantly scrolls off the top of the monitor window when testing code and have to constantly re-list the current screen.

.PAD was just an example but yes I agree, maybe {b]."PAD[/b] is a better choice for printing PAD.

Although I am programming using an emulator with all my notes handy, I am also thinking and adapting Forth for those who don't have multi-tasking and want to use Forth on their real 8-bit machines.


Top
 Profile  
Reply with quote  
PostPosted: Tue Mar 16, 2021 10:27 pm 
Offline
User avatar

Joined: Fri Aug 30, 2002 1:09 am
Posts: 8428
Location: Southern California
IamRob wrote:
Yep. I wouldn't have accomplished as much if it wasn't for the ability to multi-task on a modern machine. Very handy to keep lots of notes. But I will be uploading my work to a group of people who want to play on their real machines. Multi-tasking and tons of text files for notes won't be an option.

What kind of machines? I have had up to three dozen or more files open at once in my DOS-based MultiEdit text editor, and I don't have to leave the editor to compile and try things on the workbench computer which is tethered by an RS-232 link. I'm not using any TSRs either. As you know, MS-DOS is not multitasking. I understand DrDOS or FreeDOS is, but I have not been able to find out much. I have not tried in several years though.

Quote:
For now though still picking out the best methods of each standard to adopt.

I do that too, but try to prevent conflict between them. For example, one standard has RSHIFT and LSHIFT, and another has only SHIFT but takes in a positive or negative number of bits of distance to shift. It takes very little extra memory to have both.

Quote:
Although ANSI is the newest standard to follow, I still find it somewhat restrictive in some cases and over-bloated in others for what I need to accomplish.

I agree.

Quote:
?DEPTH is supposed to do exactly what you understood. It is meant to leave a flag to indicate if the stack is empty.

?STACK is a common Forth word, but it's to give an error message if the stack is empty when a parameter is needed.

Quote:
For instance, the normal way to do a LIST is (screen #) LIST. But if I program ?DEPTH into LIST, LIST can now be used without a number on the data stack, and if the data stack is empty, it will use the last screen number that was saved into SCR. Very handy when the screen constantly scrolls off the top of the monitor window when testing code and have to constantly re-list the current screen.

Don't forget that something unrelated might purposely remain pending on the stack.

_________________
http://WilsonMinesCo.com/ lots of 6502 resources
The "second front page" is http://wilsonminesco.com/links.html .
What's an additional VIA among friends, anyhow?


Top
 Profile  
Reply with quote  
PostPosted: Wed Mar 17, 2021 4:19 am 
Offline

Joined: Sun Apr 26, 2020 3:08 am
Posts: 357
GARTHWILSON wrote:
Quote:
What kind of machines?
8-bit Apple II's mostly

Quote:
For now though still picking out the best methods of each standard to adopt.

Quote:
I do that too, but try to prevent conflict between them. For example, one standard has RSHIFT and LSHIFT, and another has only SHIFT but takes in a positive or negative number of bits of distance to shift. It takes very little extra memory to have both.
I use bit-shifting and bit manipulation quite a bit in ML programming and thought it might be handy in Forth. But the Leo Brodie document actually frowns against it. Nevertheless, I have a screen full of bit manipulation words such as: SetBit ClrBit ReadBit RotR RotL ABSL ABSR, which all leave a zero or non-zero result as a flag on the stack. For basic programming they won't be used much, but I thing they will be a real boon down the road when I start programming adventure games that require a lot of on/off type switches that need to be remembered.

Quote:
Although ANSI is the newest standard to follow, I still find it somewhat restrictive in some cases and over-bloated in others for what I need to accomplish.

I agree.

Quote:
?DEPTH is supposed to do exactly what you understood. It is meant to leave a flag to indicate if the stack is empty.

?STACK is a common Forth word, but it's to give an error message if the stack is empty when a parameter is needed.
My error routine prints the error, but also exits back to ABORT which I try to avoid as much as possible.

Quote:
For instance, the normal way to do a LIST is (screen #) LIST. But if I program ?DEPTH into LIST, LIST can now be used without a number on the data stack, and if the data stack is empty, it will use the last screen number that was saved into SCR. Very handy when the screen constantly scrolls off the top of the monitor window when testing code and have to constantly re-list the current screen.

Quote:
Don't forget that something unrelated might purposely remain pending on the stack.

Nope haven't forgotten. Doesn't really hurt anything unless the value on the stack is less than zero. If the value is less than zero, it is programmed to abort and if it is out of range, just gives the regular error. Plus when testing word definitions I got into the habit of ending a word being tested with a warning if the stack is empty or not, since am mostly likely to use LIST immediately after the test.


Top
 Profile  
Reply with quote  
PostPosted: Wed Mar 17, 2021 8:19 pm 
Offline

Joined: Fri May 05, 2017 9:27 pm
Posts: 851

In Fleet Forth, LIST makes the editor vocabulary the context vocabulary and stores the screen number in the editor variable SCR .
In the editor vocabulary there is a word L . It takes no parameters and lists the screen number in SCR .
Code:
: LIST  ( SCR -- )
   RB EDITOR  R# OFF DUP SCR !
   CR ." SCR# " U. HEX  10 0
   DO
      CR I 1 .R ." : "
      I LINE -TRAILING QTYPE
      DONE? ?LEAVE
   LOOP
   CR ;

: L  ( -- )
   SCR @ LIST ;

If I just wrote a Forth word and I'm doing a quick trace by hand, the listing could scroll off the screen before I'm done. There may parameters on the stack that I'm still using. With the editor word L , I don't loose any stack parameters that I'm still using for the trace.
[Edit: just fixed a mistake.]


Top
 Profile  
Reply with quote  
PostPosted: Fri Apr 21, 2023 2:45 pm 
Offline

Joined: Fri May 05, 2017 9:27 pm
Posts: 851
IamRob wrote:
My dictionary is getting quite large and is wondering what some do to remember a words' usage?

A method I find helps is with the use of symbols at the beginning of a word to identify a word type:

w=word
[w] - used on words that are immediate

Words for the IF control structure and BEGIN loops are immediate.


Top
 Profile  
Reply with quote  
PostPosted: Sat Apr 22, 2023 2:30 pm 
Offline

Joined: Fri May 05, 2017 9:27 pm
Posts: 851

My previous post was somewhat brief. Sorry about that, I was pressed for time. Continuing with this train of thought, I don't think having names of the form [w] is a good rule of thumb to remember which are immediate.
Although all the words in my Forth with a name starting with an open bracket and ending with a close bracket are immediate, there are far more immediate words which do not follow this formula.
All the immediate words in the Forth vocabulary in my Forth:
Code:
[IF]      [ELSE]    [THEN]    DIR"      DOS"      TO        IS
A>CS      CS>A      ;COMMENT  COMMENT:  ?PASS     RERUN     RECURSE
"         ASCII"    ASCII     CS-ROT    CS-SWAP   CS-DROP   CS-DUP
>ASSEM    END-CODE  ;CODE     -->       +LOOP     LOOP      ?DO
DO        REPEAT    UNTIL     AGAIN     BEGIN     ELIF      WHILE
ELSE      THEN      IF        AHEAD     (         .(        [COMPILE]
[']       ABORT"    ."        DOES>     ;         -;        LITERAL
//        [         

Although ['] and [COMPILE] are immediate, I think the brackets are used to distinguish them from ' and COMPILE just as brackets are used to distinguish [IF] [ELSE] and [THEN] from IF ELSE and THEN .
@IamRob: It's been over a year since your headpost and I'm curious. Assuming you've finalized your design, how many of the words in your system have become second nature in their use?


Top
 Profile  
Reply with quote  
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 10 posts ] 

All times are UTC


Who is online

Users browsing this forum: No registered users and 8 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to: