Getting Into Working With Warps {Also Called Pointers}, and Arrays
When you want to call a function not by name, but by its position in RAM, you do so by what conventionally was called 'pointer' but which we always call 'warp' or 'warp address' or such. There's a bunch of cards connected to this little text, but most of them are composed of texts, and there is really deliciously little to explain about them.
The first point is that the cards, L1 to L12, this time HAVE to be performed in something like the High-Powered PMN Terminal rather than in the basic, most elementary PMN Terminal. So the utility menu you can come to by clicking at the colons in the Home Page and onwards, called D:15, has this High-Powered stuff, and it lists it as existing at D22000. That means that you can look into the source there when you want to. The source of the high-powered stuff has two parts: the first has all the PDs and such, and then, at the card number that D22000 tells you rather clearly, the PMN code itself begins--that's well over a thousand cards above D22000, by the way. So we're into D23000 something. There, at some point, is defined a very useful little function called ISWITHIN. It tells you 1 if a number is within a range set by two other numbers, and 0 if otherwise. This, as well as some predefined functions that handle warps, come in handedly when we do our little work with this program. By the way, if you want to wrap up a program so that you can start it with just one click, without having to first load in a terminal, you simply copy the cards of the terminal, append your own program, and be sure that you remove any traces of a 'ZZ' at the completion of the part you pasted in just before your program. In that way, you can also set up apps and the like.
If you wish to type in this program, when you see two similar cards after one another, you might as well do a CTR-C and copy it, and then a CTR-T followed by Space after you have done PgDn to next card. You can start by modifying the card just before the homecard, which you come to by clicking <HOME> button then PgUp, and this is of course the G:14 card. G14, then, you can put in e.g. L:1 and a text, namely that this is a warp-example program. Then, why not also type in D%22000, so you get a pointer to the High-Powered PMN Terminal, and can start it straight from this very easily accessible page. So you save the G14 by CTR-S, then activate the mouse by CTR-W, and you can go to L1 quickly, then back to it, then to the High-Powered PMN Terminal, back and forth, until you get it to work. And do REB each time you have done an important change to disk and are out to set your foot in a new place!
So all cards from L1 to L4 are just very easy text functions, making it easier to write small, neat, compact, beautiful functions further on. You won't need all that many comments inside a function when the names of the functions themselves work as comments. However see that the predefined function FF is used. This locates a function--and produces a number, when the function quoted (three letters or more) is found. The number it produces is, indeed, the much-wanted warp. These warps can be gathered up, put in an array, and later used to perform functions without having to again refer to them by name. The function used to perform these at that time is PF. {You can use a text-search as part of High-Powered PMN Terminal to locate comments inside the programming of these functions, when you are getting really into G15 PMN work. It takes a little bit to get used to how to do it, for instance you would search on “pf:” not just “pf”, or use some other trick to enhance exactness of the search; and the comments may be a bit tight and obscure sometimes, and then it is better to search for uses of a function inside a program that is more readable.}
At L5 there is a funny one: goldpath= &12345&. What's all that? It is an example of a very short array. For any longer array than a dozen numbers or so, you do it in different ways. But since the G15 PMN language is dedicated through and through to 32-bit, it means that even though &12345& is a text-quote, it can handle MUCH more than just letters and digits there {although, to be precise, you can also pack stuff to 8-bit format; that's an advanced topic}. In each position of this little quote, you can put a whole big vast number up to a billion and more. And the warp addresses, or warps, are just such numbers. We are going to have a program where we let the human interactor--you, presumably--tell what's supposed to be in that array, from a list of three alternatives, for how to proceed from where one is to get a gold treasure. You type in a sequence of 5 digits, such as 3, 2, 3, 1, 3 and the program will change this array each time. Significantly, it will convert each digit you type to a full-fledged warp. We don't have to look at these warp-numbers, they are usually very huge and may vary between one G15 platform and another, or even within two compilations of the same program on the same computer. We just want them to be right within the context of each run.
Then there's more text stuff, as known--using B9 or PP to put text to the screen, and using the &..& quote style, or the ^-style. Please note that since the dot (.) is such a highly significant symbol in G15 PMN, it should never be used at the completion of a comment, for it would look like a signal that the function is done at that point, and it may lead to funny messages if these dots are put there without attention to them. Also, always stick to the &..& stuff rather than the ^.. stuff when there's a dot in the line you wish to quote; or use the other quote-type, for quotes over several lines {talked about elsewhere}.
At L6, we also find the 'SH'. It comes after the KK. So KK reads anything pressed on the keyboard, but in this case, we just wanted to tell the human user something, then wait for a lineshift or such, and then drop it, shuck it. So SH shucks it, throws the number on top of stack.
At L7, we see how a function can be very nicely commented by a line with In or Input or something, and then a line with Gives or something, to tell what comes out of it. This expects a number from 1..3 but the function tells of itself, in the comments in L7, that 'wild' numbers are okay--that is to say, this one checks that the input is right or not. If not, it has quiet, well-thought ways of handling with the 'wildness'. The number is stored in I1, or we should write i1 for clarity in this text, by means of S1. As output of the function is the warp.
In the next card, L8, we see that ISWITHIN is used to check whether i1 is in 1..3. Then the N? is used. This converts 0 to 1 and 1 to 0. It means, of course, "No?" -- and it is the Boolean NOT.
So, in L8, there is a check as to whether i1 is 1 OR whether it is outside of range: when anyone of these conditions are satisified, the function RIGHTWARP is called. This one produces the warp of the function that talks about 'taking the next path to the right'.
Note how easy it is to divide up thought into modules so that each module, or card, can be given attention to all on its own. This is the type of thing that makes programming more a relaxing, graceful task, and less a thing that leads to stress in mind or body.
At L9, it is just a simple check on whether i1 is 2 or 3, and the other warps are chosen then. Having made simple short functions earlier on makes it easy to implement this type of mechanism. There are other ways of doing this, but here the emphasis is clarity, that it looks easy enough, relatively speaking.
In L10, you see that the comment indicates that SETPATH wants two things as input, not just one: it wants part#, and it also wants--on top of stack, as it says--the path, which is 1-3. The first number is 1-5, and the second is 1-3, but wild numbers okay. Note that this is the usual way of writing about inputs to a function, and outputs also: the last thing mentioned is on top of the stack. That's also why the stack is sometimes called LIFO, Last In, First Out. For that number which is put to it last, is on top of it. It is first taken off it.
And indeed, GETPATHWARP is used at once, without further ado. Assuming, then, that GETPATHWARP has done its work and it is now a proper good warp on the stack, we need to shuffle the stack a bit, so as to get things right. For we going to store things in the little array we defined, named GOLDPATH. For this we use the predefined word YA, and to get things off the array again we can use AY {YA/AY, same letters, opposite sequence, in parallel to KL/LK, which is used to put stuff and get stuff from single variables, rather than arrays, as here}.
So W is a single letter function like F, but whereas F forges a duplicate of what is on top of stack, W sWitches it around. There are three such one-letter predefined functions of vital importance in all essential stack use: F, W and D. F duplicates. W switches. D doubles the second number, copies it over to the top.
The YA function wants the array on top of the stack. Just before that, it wants the position in the stack. Just before that again, it wants the value. So you see that W is needed to put it in right sequence. We could also have put it to i1, i2, i3 or the like first, but this was the shortest way, and understandable enough, in this context.
Note that when we progress in thinking about the program from L1 to L10 we have never anticipated a function very much; rather, we go from one definition to the next, using only PREVIOUS definitions. In addition, we take care not to define things that may already have been defined in the High-Powered PMN Terminal, when that is the context within which we run this PMN program.
Having made a suitable number of small essential functions, we wrap it up in L11 and L12 rather elegantly.
In L11, we have a loop--it begins with LL:5 and completes with LO. It gives some text first, and cleanses screen by CE after it. It calls on SETPATH. Note that it has a keyboard-reading word in it, KI {which is a more general word, typically used in the High-Powered PMN Terminal; however note that if you use the keyboard numbers very extensively, there are side-implementions of G15 PMN in which the KI may give a different number for a few keys--notably for the so-called "dos" version of G15 PMN}.
After KI reads a digit from the keyboard, 48 is substracted from the number, the PD 'SU' does this. This is the ASCII thing again. 0 has ASCII value 48, 1 49, 2 50, and so on for the digits. So substracting 48 is done when we access the keyboard in this way. There are other ways of getting numbers from keyboards, especially if we call on the High-Powered PMN Terminal extensions, as we talk about elsewhere.
In L12, we use AY rather than YA to get the warp out. The AY expects the position in the array to be told, then, on top of stack, the array itself should be indicated--in this case, GOLDPATH. {Note that for longer arrays, it is often convenient to store the place of them in a variable, in which case not just the name of variable pointing to the array is given, but also the command LK to fetch that place, --also called warp, even though it's just an array}.
Having got the warp on stack, we finally do a PF on it. This happens five times.
Experiment with the program. You see that in a way, as a human interactor with the program, you are somehow changing the program, not just filling an array with 1, 2, 3, 4, and 5, but filling it with direct commands, where in RAM to warp to. The whole process of working with warps has in it the fullness of fun and responsibility, as well, as assembly programming can sometimes give, at its best; and in addition, it gives you a direct sense of relating to the computer. Finally, it can be intensely useful, you can have variables, arrays, matrices, with a lot of stuff in them, and these can themselves hold the functions that are supposed to go along with these objects, or what we call them. If you like, you can derive some new objects from earlier ones, by this: so warps are the power-features of that which is also called 'objects' in 'object-oriented' proramming, but they are far more flexible, less rigid, less hierarchical, and much more fun.