Differences

This shows you the differences between two versions of the page.

--- en:pfw:library [2024-08-25 20:21] – [The library is just bare ASCII] willem
+++ en:pfw:library [2025-02-06 17:59] (current) – [A library for Forth] willem
@@ Line 1: / Line 1: @@
 ====== A library for Forth ======
+*W.O.*
@@ Line 9: / Line 11: @@
 The interface consists of the following word: ''%%NEED%%''
-  * ''%%NEED%%''  ''%%( "name" -- i*x )%%'' Make sure “name” is present in the dictionary. If not, load it from a library. If "name" already exists, do nothing.
+  * ''%%NEED%%''  ''%%( i*x "name" -- j*x )%%'' Make sure “name” is present in the dictionary. If not, load it from a library. If "name" already exists, do nothing.
 An optional word as suggested by Ulrich Hoffmann
@@ Line 15: / Line 17: @@
 Optional words as suggested by Willem Ouwerkerk
-  * ''%%NEEDED%%''  ''%%( a b -- i*x )%%'' Make sure that name represented by the string a b is present in the dictionary. If not, load it from a library. If name already exists, do nothing.
+  * ''%%NEEDED%%''  ''%%( i*x a b -- j*x )%%'' Make sure that name represented by the string a b is present in the dictionary. If not, load it from a library. If name already exists, do nothing.
+  * ''%%RUN%%'' ''%%( i*x "name" -- j*x )%%'' Find "name" in the library and load & run the script from a library.
   * ''%%.LIB%%''  ''%%( -- )%%'' Show all section/chapter headers of the current library in one or more columns
+  * ''%%VIEW%%'' ''%%( "name" -- )%%'' View the code from the libary, that belongs to "name".
 ===== Pseudo code =====
@@ Line 34: / Line 38: @@
 Function: .LIB     ( -- )
     Print all chapter headers in a human readable form.
+Function: VIEW     ( "name" --)
+    When the keyword "name" is found view the source code chapter,
+    otherwise issue an error message
 Function: FROM     ( "name" -- )
@@ Line 60: / Line 68: @@
 They act as separators and are not part of the text itself.
-The ''%%09%%'' marks the end beginning of a chapter, like this:\\
+The ''%%09%%'' marks the end of a chapter, like this:\\
-Note that: The library starts with a dummy ''%%09%%'' so that the first keyword line can be found.\\
-  * ''%%09%%'' chapter-1 ''%%09%%'' chapter-2 ''%%09%%'' last-chapter ''%%09%%''
+  * chapter-1 ''%%09%%'' chapter-2 ''%%09%%'' last-chapter ''%%09%%''
 The ''%%0D%%'' marks the end of a line:\\
   * line-1 ''%%0D%%'' line-2 ''%%0D%%'' last-line ''%%0D%%''
-The first line of each library chapter starts with case insensitive keyword(s) separated by spaces. The word ''%%CHAPTER%%'' builds this the first line, and provides this line with a
+The first line of each library chapter starts with a case insensitive keyword. The word ''%%CHAPTER%%'' builds this the first line, and provides this line with a
 backslash to prevent the keywords for being executed while loading a chapter. Then it adds all source code until the ''<nowiki>%%</nowiki>'' marker is found. The end of each chapter is marked by ''%%09%%''
 The end of the library is kept in a pointer that is updated when we extend the library.\\
@@ Line 95: / Line 103: @@
 : 2TUCK   2swap 2over ;     ( x1 x2 x3 x4 -- x3 x4 x1 x2 x3 x4 )<0D>
 <09>
 \ 2ROT<0D>
 \ Rotate third double to top of stack<0D>
 : 2ROT    2>r 2swap  2r> 2swap ;<0D>
 <09>
 \ -2ROT<0D>
 \ Rotate top double to third double position on the stack<0D>
@@ Line 110: / Line 116: @@
 <code>
-Function: NEEDED   ( a +n -- i*x )
+Function: NEEDED   ( i*x a +n -- j*x )
     a) Save the string a +n and make the string uppercase
     b) If this string is already present in the dictionary, do nothing
@@ Line 117: / Line 123: @@
     e) When a keyword is not found issue an error message
-Function: NEED     ( "name" -- i*x )
+Function: NEED     ( i*x "name" -- j*x )
     a) Parse the next word form the input stream and perform the function of NEEDED
@@ Line 273: / Line 279: @@
 </code>
+===== A viewer for the library =====
+This viewer shows 16 or less lines at a time.
+It stops at a <09> character, prints a divider line and waits for user input.
+When the spacebar was hit, it goes on displaying the next chapter.
+Any other key leaves the viewer.
+<code forth>
+( A library consists of 09 {tab}, 0D {cr} and ASCII chars )
+( ranging from blank to ~ others chars are not allowed )
+\ Show the library source code of a chapter
+: .LINE     ( a1 -- a2 ch ) begin c@+ dup BL < 0= while emit repeat ;
+: .DIVIDER  ( -- )          cr  10 0 do ." -- " loop  cr ;
+: LIBTYPE   ( a -- )
+    begin
+0 do                         \ Max. 16 lines at a time
+            cr .line 09 =               \ End of source chapter?
+            if  .divider leave  then    \ Show divider & ready
+        loop
+    dup libhere < while                 \ More library source to be done?
+        key BL <> if drop exit then     \ Yes, ask key, stop on non space
+    repeat  drop ;
+: VIEW      ( "name" -- )       bl word count  lib-find libtype ;
+</code>
 ===== A sample library source =====
 This examples shows how many different code parts can be used inside the library.\\
@@ Line 291: / Line 324: @@
 chapter RESTORE-LIB
 v: inside   \ Restore LIBHERE in case it got lost
-    libhere hx 40000 +  lib   hx FF scan  nip to libhere
+    lib hx 50000 +  lib   hx FF scan  nip to libhere
     cr .( Libhere ) libhere u.
     cr .( Size ) libhere lib - dm . .( bytes )
-    freeze
 v: fresh
 %%
@@ Line 352: / Line 384: @@
     \ RESTORE-LIB
 v: inside   \ Restore LIBHERE in case it got lost
-    libhere hx 40000 +  lib   hx FF scan  nip to libhere
+    lib hx 50000 +  lib   hx FF scan  nip to libhere
     cr .( Libhere ) libhere u.
     cr .( Size ) libhere lib - dm . .( bytes )
-    freeze
 v: fresh
@@ Line 397: / Line 428: @@
 ==== A little extra ====
-Loading a lot of library code in one go. it is used like this: ''%%need( -rot -2rot d- asm\ )%%''\\
+Loading a lot of library code in one go. It must be used like this: ''%%need( -rot -2rot d- asm\ )%%''\\
 Note that ''%%BL-WORD%%'' is a typical noForth word that uses ''%%REFILL%%'' inside, so it can load multiple lines of library words when you need too.