jb wrote:It’s hard (for me) to switch off the familiar semantics (which is why I really shouldn’t use ‘pear’)—especially since sometimes (Document.active, allComments, text) ordinary meanings are used.
I think using appropriately named variables is very important, even if the macro language itself is oblivious to those you choose. It's hard to read and understand code that uses poor or illogical variable names.
Next I’ll see if I can understand Range.
It's a pretty simple object. It really only keeps track of two things: a location and a length, both stored as regular numbers. These numbers behave just as you'd expect, holding whatever value they were assigned upon creation, regardless of what happens in the future to the elements being described.
For example, in the text "Hi James" let's say we want to describe where the word "James" resides using a Range. If we take the location (index) of the first character "H" to be zero, then the letter "J" has a location of 3. The word "James" is 5 character long, so the range is: location=3, length=5, abbreviated for convenience as (3,5). You can get such a range in the macro language in a variety of ways:
Code: Select all
# construct range explicitly, using hard-coded literal values
$range = Range.new(3, 5)
# make the same range, but using a command that searches text:
$text = "Hi James!"
$range = $text.rangeOfString("James")
Either of those give you a range (3, 5).
The thing to remember is that the range's values do not change unless you explicitly tell them to. So even if we replace the word in the text, the range is still the same, eg:
Code: Select all
$text = "Hi James!"
$range = $text.rangeOfString("James") # range is (3,5)
$text.findAndReplace("Hi", "Bye") # word "James" is now at location of 4
# the variable $range is still (3,5) even though the word "James" has shifted location
So we can see that a Range is just a pair of plain-old numbers understood to have a specific meaning. Remember that ranges can describe any kind of elements: characters in text, rows in a table, people in a line, etc. From the macro language reference:
A Range object describes a contiguous block of elements in some larger context. For example, a range of characters is a block of characters that are all adjacent to one another in the same document. However, such a range only describes the location of these character, it does not contain the actual characters.
A range can describe any kind of element, such as indexes in an array or rows in a table. The type of element being described by a range is irrelevant, the only properties a range maintains are the indexes (integers) of the elements in the larger context. This means that you can use the exact same range object to access different types of elements if you like.
Hopefully that makes some sense.