The "Simple Examples.pgs" file is a collection of small, focused Prograph methods that illustrate the language features and some of the more useful primitives supplied with the language. It is hoped that these can serve as a learning aid for people just becoming familiar with Prograph, as well as a useful review for experienced users.
The examples are organized in classes, simply as a device for categorizing them. The methods in each class are described in detail below. If a method is denoted as "not directly executable", that means that you cannot simply select the method and choose "Execute Method" from the Exec menu, because the method requires inputs. Therefore, each of those methods has an example method which calls it, and of course they can be called from your own Prograph code, with the correct inputs.
UNIVERSAL
• Initial
Repeatedly calls method "execute a method" in class "System Examples" until user cancels from one of the dialog boxes. This is the Program method for this file, which will execute when you select Run from the Exec menu or when you compile this program.
CLASS: Control
These methods illustrate the use of Prograph cases and controls (Next Case, Terminate, etc.) to achieve code structures people may be familiar with from other languages (e.g., if...then...else). The C equivalent of the Prograph code is on the comment for each method. Most of these methods also illustrate the "ask", "answer" and "show" primitives.
• if... then... else #1
Uses the "Next case on failure" control in a method with two cases to implement the functionality of "if A then (case 1) else (case 2)".
• if... then... else #2
Uses the "Next case on success" control in a method with two cases to implement the functionality of "if not A then (case 1) else (case 2)".
• cases
Uses the "Next case on failure" control in a method with three cases to implement "if A then (case 1) else if B then (case 2) else (case 3)".
• nested cases
Uses the "Next case on failure" control in two nested levels of locals to combine the test used in IF...THEN...ELSE #1 and the CASES example.
• for loop
Uses the "loop annotation" and a "Terminate on success" control to implement a loop wherein a value gets incremented every time through the loop until it reaches a maximum value and the loop gets terminated.
• do..while loop
Uses the "Loop annotation" and a "Finish on failure" control to implement a loop which, when a certain condition is no longer true, executes the contents one more time and then stops looping.
• while loop
Uses the "Loop annotation" and a "Terminate on failure" control to implement a loop which, when a certain condition is no longer true, stops looping immediately.
• control on the output bar
Illustrates a situation in which putting a "Fail on success" control on the output bar can get you where you want to go. This technique is often overlooked by experienced Prograph programmers and beginners alike.
• propogation of failure
Illustrates the use of "Fail on failure" controls to pass a failure condition up from inside nested locals. This is another often misunderstood technique which is very useful.
CLASS: Math
Just a few simple examples to help you get started visualizing mathematical problems in Prograph dataflow diagrams.
• dataflow formula
The formula for the sum of all integers between 1 and n is n(n+1)÷2. This method asks you for a value of n and computes the answer using the +,* and ÷ primitives.
• evaluate formula
This method uses one "Evaluate operation" to calculate the above formula, instead of the three separate math operations used in the dataflow example. An "Evaluate operation", if it can be used, is more efficient than the dataflow method.
• random (not directly executable)
The "rand" primitive returns a random integer between 1 and 2,147,483,647 (1 and 2^31 - 1). This method uses the rand primitive and the idiv(integer division) primitive to return a random number between 1 and any given number.
• Example Random
Simply calls the random method described above to simulate rolling a die and getting a number between 1 and 6.
CLASS: System Primitives
Prograph's "System Primitives" are sometimes called "Reflexive Primitives" because they allow you to programatically query your own code file. For example, the "classes" primitive returns a list of all the classes in your file. You can easily use these primitives to write a
self-documenter or browser for your source code. The "Instance Finder" example in the Utilities file also makes use of these primitives.
• get a class
Uses the classes primitive and the select primitive to display a list of all the classes in the file and return the one that the user selects.
• show class comments
Calls "get a class", described above, and then uses the class-com primitive to show the comment on the chosen class.
• get a method
Uses the "get a class" method described above, the methods primitive and the select primitive to display a list of all the methods of a particular class (or all the universal methods), and outputs both the class name and the method name the user selected.
• show method comments
Calls "get a method", described above, and then uses the method-com primitive to show the comment on the chosen method.
• execute a method
Calls "get a method", described above, and then uses an "Inject" terminal to call the selected method in the selected class.
CLASS: String Primitives
Most of these methods are trivial examples that let you get the hang of the string primitives ("length", "format", "in", "from-string", etc). The Word and Char methods are more real-life types of examples.
• "length" example
Illustration of the "length" primitive.
• "join" example
Illustration of the "join" primitive.
• "in" example
Uses the "in" primitive to determine if a letter is a vowel or not.
• format example #1
Use of the format primitive to achieve the same functionality as the "join" example.
• format example #2
A little more complicated use of the format primitive to display a column of numbers with the decimals lined up.
• prefix example
Illustration of the prefix primitive.
• suffix example
Illustration of the suffix primitive.
• middle example
Illustration of the middle primitive.
• to-ascii example
Illustration of the to-ascii primitive.
• from-ascii example
Illustration of the from-ascii primitive.
• to-string/from-string
Uses the to-string and from-string primitives to determine the last digit of a given number.
• Char (not directly executable)
Analogous to the "character" chunking function in Hypercard, returns the nth character of a string.
• Char example
Calls the Char method described above
• Word (not directly executable)
Analogous to the "word" chunking function in Hypercard, returns the nth word of a string. Words are delimited by one or more spaces.
• skip spaces (not directly executable)
Given a string and an index, returns the index of the next non-space character. Called by the Word method described above.
• Word example
Calls the Word method described above.
• Line (not directly executable)
Analogous to the "line" chunking function in Hypercard, returns the nth line of a string. Lines are delimited by carriage returns (ascii 0xD).
• Line example
Calls the Line method described above.
CLASS: List Primitives
Some of these methods are just trivial examples to help you get the hang of manipulating lists. The cardinal/ordinal examples and shuffle and sort are more complex, but worth the effort to understand.
• attach-r example
Illustration of the attach-r primitive.
• detach-r example
Illustration of the detach-r primitive.
• attach-l example
Illustration of the attach-l primitive.
• detach-nth example
Illustration of the detach-nth primitive.
• get-nth example
Illustration of the get-nth primitive.
• (length) example
Illustration of the (length) primitive.
• (join) example
Illustration of the (join) primitive.
• (in) example
Illustration of the (in) primitive.
• list annotation example #1
Illustrates how list annotations on roots and terminals work. List annotations are one of the most powerful and useful features of the Prograph language. They are well worth becoming comfortable with!
• list annotation example #2
Illustrates what happens when you list annotate an input to an operation, in this case the show primitive.
• list annotation example #3
Illustrates how you can use a list annotation on the output of a looping operation to collect individual results of each iteration into a list.
• get-cardinal-str (not directly executable)
Given a number (such as 5), returns corresponding string (such as "five"). Uses the find-instance primitive to look up the number in a list of instances stored in the number xref class.
• get-ordinal-str (not directly executable)
Given a number in string or number form (such as 5 or "five"), returns corresponding ordinal number (such as "fifth"). Uses the find-instance primitive to look up the association in the number xref class.
• cardinal-ordinal example
Uses list annotations in an interesting way, calling the get-cardinal-str and get-ordinal-str methods described above.
• palindrome? (not directly executable)
Given a string, uses the to-ascii and reverse primitives to determine if the string is a palindrome (same backward and forward).
• palindrome example
Calls the palindrome? method described above.
• shuffle (not directly executable)
Takes a list as input, and creates a new list with the items randomly inserted. Uses the (length), detach-nth and attach-r primitives, as well as the random method from the Math class in this file.
• shuffle example
Called the shuffle method described above.
• sort (not directly executable)
Implementation of a classic sort algorithm known as "quicksort". Rather sophisticated use of list features of Prograph. Uses a partition annotation, a list annotation, the primitives detach-l, attach-l and (join), and a concept known as recursion wherein a method calls itself.
• sort example
Calls the sort method described above.
CLASS : I/O Primitives
The i/o primitives allow you to easily post simple dialogs to get input from your user or show information. The examples in this class are extremely simple and just give you an overview of the tools available to you.
