Taking a couple of sample scripts, you will learn about scripting featurein Partial Recall as well as its limitation compared with other programingtools.
You can write your own function in a Recall note, using NewtonScript,and call it from another Recall note by a single gesture. When you makea Recall gesture, you can pass one or more parameters to the function,by striking through them along with the function name.
Parital Recall intends to provide user an option to implement user specificcalculation, search method, or data manipulation. It is not to give anenvironment to write application, which is much more complicated task fornon-programmer.
Unlike Newton Tool Kit or any other programming tools, Partial Recalldoes not offer any framework, macro, pre-processor or those kind of things.There is no graphical user interface builder either. However, this doesnot mean that you are heavily restricted writing NewtonScript program.With a little practice, you may create a view which offers user interfacelike other application. You will see a sample which shows the possibility.
For basic structure of NewtonScript, please refer to "NewtonScriptReference". And for detail about NewtonScript programming languagealong with reference of system services, see "Newton Programmer'sGuide". Both documents are provided Apple Computer, Inc.
You can write a function so that it takes parameters from user and manipulatethem. When you call a function from a Recall note, you write the functionname followed by one or more parameters. For example:
sum 123 456 789
When you strike through "sum" to "789", PartialRecall calls a function named "sum" with a series of parameters(123, 456, and 789).
NOTE: When you call a function,you have to give at least one parameter, whether the function takes itor not. If no parameter is given, Partial Recall would assume that youintend to do usual Recall action, and pull the function script into thecurrent note.
Your function receives the parameters through a variable named "args",which is an array of strings. Each string in args correspondsto each parameters you pass. In the above example, the args inthe function sum shows:
["123", "456", "789"]
Now, the sum function might be written like this:
result := 0;foreach item in args do result := result + StringToNumber(item);return result;
NOTE: All parameters are passedin string format. If you need to manipulate them differently, you haveto convert them properly. In the above example, we use StringToNumber()global function to convert a string representing a number to a real number.
When execution of a function reached to the end, a value of the lastexpression in the script is returned as a result of Recall action. Youmay return a value explicitly in a return statement.
The return value is converted to a string before it is actually putback into the note. Numbers, strings, characters, and symbols are convertedto their natural form, but the other data types like frames, arrays, andbooleans are converted to an empty string.
NOTE: In case a function returnsnil, Partial Recall will leave the original text, and put anythingin the note.
If you want to return an array or frame of values, you need to flattenthem into a string at the end of function. The following example collectsthe name and size of the installed packages, and then stuffs elements inthe result array into a string.
packages := foreach item in GetPackages() collect item.title && "(" & NumberStr(Real(item.size)) & ")" & "\n";return Stringer(packages);Let's name the script "package" and try Recall the followingline:
package list
As mentioned earlier, there is no graphical user interface builder providedin Parital Recall. So, it is not easy to write a function which shows aview on the screen. However with a little practice, you can write sucha script. Here is a sample script which creates a simple sticky note view:
main := { viewBounds: {left: 0, top: 0, right: 200, bottom: 106}, viewJustify: 80, _proto: @180 };memo := { viewBounds: {left: 8, top: 8, right: 192, bottom: 88}, viewFlags: 33553921, viewFormat: 12545, viewLineSpacing: 20, viewClass: 81 };DeclareChild(main, memo, 'memo);newSticky := BuildContext(main); newSticky :Open();return nil;In this example, we have to specify literal values for viewJustify,viewFlags, viewFormat, and viewClass. BecausePartial Recal does not offer pre-defined constants that are used to specifythose values. The viewClass 81, for example, represents clParagraphView.For more about those slots and the constant values, please refer to "NewtonProgrammer's Guide".
The main view is based on protoFloatNGo proto, whichis represented by a value @180. This is a special expression torefer to prototype frames or other objects in Newton OS. You can find thosevalues in "Newton 2.0 Defs" file which comes with Newton Toolkit.
DeclareChild() is a special function that Partial Recall providesfor you. It helps you structure a view with children views. If you createa child view which belongs to another view, you must call this functionto declare the relationship:
DeclareChild(<parent view>, <child view>, <child view symbol>);
The above example does not take any parameter, but you still need togive one when you call. If you name the function "sticky", youcan call it like this way:
sticky open
Although Partial Recall scripting function is not designed for buildinga large structured program, you may still need to write shared scriptsor subroutines within your script. You can easily achieve this using NewtonScript'sframe objects.
The next example shows how to create a frame that provides a set offunctions that can be shared inside the script. The frame named accessNameshas two functions namely person() and phone(). Person()takes an array of keywords, and finds a person record from Names soup.Phone() takes a person record, and returns the phone number. Whenyou call this script along with a person's name, it returns his/her phonenumber.
accessNames := { person: func(keys) begin soup := GetUnionSoupAlways("Names"); cursor := soup:query({words:keys}); return cursor:entry(); end, phone: func(person) begin if person.phones[0] = nil then return "no phone"; return person.phones[0]; end,};person := accessNames:person(args);if person = nil then return "no such a person";return accessNames:phone(person); Here is another example, which shows more complicated frame model. Thecalculator frame object owns a stack and its accessor methodspush(), pop(), and next(). The calculatorworks like a stack machine, taking an expression in postfix notation (forexample, the postfix notation for an expression "1 * 2 + 3"is "1 2 * 3 +"). Each element or token of an expressionis passed through next() function. When a calculation complete,you can find the result on the top of the stack.
calculator := { stack: Array(80, nil), offset: 0, lookup: nil, push: func(data) begin stack[offset] := data; offset := offset + 1; end, pop: func() begin offset := offset - 1; return stack[offset]; end, next: func(token) begin if (temp := StringToNumber(token)) then :push(temp); else (lookup := operators.(Intern(token))) and :lookup(); end, operators: { |+|: func() :push(:pop() + :pop()), |-|: func() :push(-1 * (:pop() - :pop())), |*|: func() :push(:pop() * :pop()), |/|: func() :push(1 / (:pop() / :pop())), },};foreach token in args do calculator:next(token);return calculator:pop(); Assuming you name the function "calc", you can call it like:
calc 12 34 + 56 78 90 / - *
The fuction would give you 2536.13333333333 as a result of the expression(12 + 34) * (56 - 78 / 90).
NOTE: There is no error handlerimplemented in the example. For use in real world, you must be carefulabout checking data types in every places.
As you noticed in the last example, there is another frame operatorsembeded in calculator frame. This frame defines a set of functionsfor each operator (+, -, *, and /).When the next() function encounters an operator, it sets the functionobject to lookup slot. In this way, each operator function caninherit the stack accessor methods.
You may come out a smarter way to propagate frame values to anotherusing the NewtonScript inheritance mechanism. For more information aboutframe and inheritance, please refer to "NewtonScript Reference".