uCalc Transform Primer for BAS2NIM
The following is a primer for
uCalc Transform in the context of the BAS2NIM project. This program covers uncharted territory and may thus appear daunting before you give it your first try. The purpose of this primer is to start you off with concepts you're familiar with, and gradually introduce unique uCalc Transform functionality, until you feel like you already knew how to use it all along.
Search featureIf you understand how to use the Ctr-F Find feature in most text editors/viewers, you can understand how to use uCalc Transform.
Chances are you are familiar with the Search feature in Notepad, MS Word, Internet Explorer, programing IDEs, and just about any kind of text editing/viewing program. Just press Ctrl-F, and you get a text box where you can enter a word, and it will find that word in your document. Some programs have a better search feature than others. For instance Notepad finds just one occurrence at a time, while Internet Explorer immediately highlights all occurrences. Internet Explorer also conveniently tells you how many occurrences there are. Some programs also let you do advanced searches using "RegEx" patterns.
The above text editors/browsers are apps that happen to have a search feature. On the other hand, at the most basic level you can think of uCalc Transform as an advanced search/replace program that happens to have a text editor. The
Find and
Replace with boxes remain permanently visible in the program. uCalc Transform combines some of the best search features you'll find in other text editors into one program. Type in a word in the
Find box just as you would in any program. Instead of
Enter, press one of the blue navigation buttons to navigate forward or backward through the highlighted search results. Or in the box next to the total count, you can type in which occurrence you want to jump to. You can use RegEx patterns if you like, but uCalc also has its own patterns that are easier to use. More on that later.
You'll notice an additional feature above that's not typical in other text viewers. Instead of just one search box, you can have many. Each pattern is highlighted in a separate color, and each gets its own count.
So uCalc Transform is like Ctrl-F (Find) that you're already familiar with, but with the best features from various programs, plus a few features you won't find elsewhere.
Search/ReplaceThink of uCalc Transform as a very flexible Search/Replace tool.
If you're familiar with the
Find feature in many programs, you're likely also familiar with the related
Find/Replace feature. Type in a word in the
Find box, and another word in the
Replace box, and all occurrences of the word in the
Find box will be replaced with the word in the second box. And that's what uCalc Transform lets you do. But just as it lets you search for more than one word at a time, it also lets you perform Search/Replace on multiple words at a time.
In a way, this is the essence of uCalc Transform. Basically find occurrences of one or more items, and replace it with something else. If you stop right here, and learn nothing more, you can already do a great deal with uCalc Transform. However, a literal replacement may not be sufficient for advanced cases. uCalc's Find/Replace does not just deal with words. It works with patterns.
PatternsAbove, we replaced the word
PRINT with the word
echo. However, that doesn't go far enough. Lets say you wanted to replace statements such as:
PRINT "Hello!"
A = UCase$("Test")
with:
echo("Hello world!")
A = "Test".toUpper
with parenthesis and all. Pause for a moment. Don't peak below just yet. Take a moment to see how to do this either with Notepad, or a more advanced text editor.
You can't? Maybe not with Notepad, but you can at least try with other programs that support Regular Expressions (RegEx). RegEx is nice, but it's also notorious for complexity in some cases. uCalc patterns are generally much easier to deal with (though it supports RegEx as well). So you might do something like:
Where
{data} is just a pattern variable (we could have named it
{text},
{Expr}, or anything else) that captures all tokens until it reaches a statement separator such as end of line, or the end of text.
{var},
{start}, and
{stop} in the second line are also pattern variables. The
For pattern picks up text with
{var} until it reaches "=". Then it picks up more with
{start} until it reaches
To, and picks up the rest after that with
{stop}. Notice how corresponding variables in the
Find box are featured also in the
Replace box.
Here's the converted code:
echo("Hello World!")
for x in countup(1, 10):
A = "Testing".toUpper
Skipping OccurrencesLet's say you wanted to match all occurrences of
PRINT, but not when it has a
# after it. Easy! In the next box after the first
PRINT enter
PRINT #, and select the
Skip Over property for that one. So when it finds
PRINT # that one won't count as a match.
PRINT will be matched only when not followed by
#. By the way, the amount of whitespace between
PRINT and
# doesn't matter. Also, when patterns start the same way, the parser checks for patterns furthest towards the bottom first and works its way up until it finds a match.
What if you also wanted to skip TCP PRINT? Well add a line for that as well.
What if you want to skip COMM PRINT, TCP PRINT, and GRAPHIC PRINT? Well you could add a separate line for each. However, you can conveniently combine them in the same line. There are many ways to do things in UCalc Transform. The following are all equivalent:
- OR -
- OR -
It's up to you to decide on which style you prefer to use.
Skipping commentsThere are various approaches to skipping comments. One easy way is to do something like what we've done with the skip-over for PRINT. Instead of using an ordinary pattern variable for this like
' {comment}, we'll use a regular expression. We don't want any text beyond ' to be parsed in any way. So we can do it like this:
{Comment:"'.*"}
If you're not familiar with
Regular Expressions, then
Google RegEx for details.
If you will be defining a transform with patterns broken down into different passes, you may want to instead define a comment as a token, and assign it the whitespace property. That way, you won't have to define a skip-over comment pattern for each pass. We won't get into that here.
What nextBasically that's it for the primer. This is intended just to get you started. There is so much more you can do. Here's what to do next:
- Download uCalc Transform and try it for yourself
- Play with all the other properties beyond SkipOver
- Check out examples in the uCalcTransform\Examples\PowerBASIC directory
- Check out the \PBtoOtherLanguages directory as well
- Read up on uCalc Patterns
- Read the uCalc String Library documentation
- Download and play with this BAS2NIM starter
- Run Basic.Bat (a basic interpreter) found in the \Language directory
- Examine *.uc (Basic.uc, uCalc.uc, etc) which contains the full source code for the Basic interpreter
- Ask me questions
- Make suggestions (I'm always trying to find ways to make uCalc easier)
IMPORTANT: Remember to load transforms using the
Open Transform button at top:
Transforms (*.uc files) are saved as plain text. However, opening it as plain text will not be of much use.
