English is tough language for everyone, because so many words can vary greatly in meaning according to the context in which they are used. And, one of the first things I was taught in technical writing was to avoid these two things:
Use of common terms in an uncommon way
Use of uncommon terms in a common way.
Add to that the fact that KM very much has users from all over the world, make it be quite challenging to produce clear writing.
But in your case, I see your definition of "standing for" to be very close to the dictionary definition of "a piece resembling a coin issued for use (as for fare on a bus) by a particular group on specified terms".
IOW, the token for bus fare is standing for the actual cash one might have to pay.
IMO, it is not good, not intuitive, for any software to use a term of art that is inconsistent with common usage in the computing world. So, to use "token" for something that "walks, talks, and acts" like a "function" is confusing.
By that definition, since functions typically can also have side effects, everything is a function.
Actions are a function. Certainly Conditions are just functions that return booleans and Collections are functions returning lists. Heck, with side effects, macros are functions.
Yes, tokens are sort of functions that return text, but they are also different to Functions based on their usage, context and interpretation. Calling them functions just confuses the issue.
There is a Hex token and a HEX function and they are very different because their context is very different. Since functions return only numbers, you know that a HEX function is going to return a number, so you know it is for turning hex characters in to a number. Tokens are for providing text, so then it is clear that the Hex token will provide text characters.
No, they do quite different things. One produces a numerical answer from text, one produces text, especially the CalculateFormat version, from a numerical expression.
There is a reason for the terminology, and while some people on earth may have a different interpretation of what a token means in some other dictionary, using a token to mean something that stands in for something is certainly the common usage here.
And Keyboard Maestro defines terminology for a purpose, so that clarity can be provided when talking about its behaviour. It has very specific terminology which is worth learning if you want to use Keyboard Maestro well. As does any subject of any complexity.
Editor
Engine
Macro Groups
Smart Groups
Macros
Trigger
Actions
Conditions
Collections
Tokens
Functions
Filters
There is a purpose to the terminology, and arguing that everything is a function runs entirely counter to that purpose.
A day ago, I did not understand anything. Thanks to re.reading the wiki and Tom's explanations I had a mental flash and now think that I understand. Like you, I graduated in math and physics years ago.
forget about constants (speed of light in a void). There are no constants in this discussion.
you already know what variables are : numbers, words or groups (arrays, like (pencil, eraser, pen))
Consider variables are something personal defined by the user: name of Tom's cat, number of apples in his fridge
Consider tokens as similar to variables but common to all observers. For purposes of practicality, names of tokens are 'reserved'. Example: all participants in this discussion use computers: we all have browser front windows, files with filenames and paths, etc. Just look at the list of tokens below and it will be obvious. Wee all have front windows which have a certain size, we all have emails to 'to' recipients, etc
I think that you may be confused by reading that tokens are unchangeable ... but cannot be changed. The reason is simple and obvious.
We all use browsers and are in a front browser window at any point in time:
Tokens cannot be changed: the name %FrontBrowser% is reserved by KBM to describe the front browser window. You cannot use that same name %FrontBrowser% as a variable equal to the name of Tom's cat. You have many equivalents in math. You can call a mathematical variable x,y,z etc, but you will not call a variable in an equation LOG or EXP. LOG and EXP are like tokens: the are 'reserved' to describe specific things. You can write x = a+b but you will never write LOG = a+b
Tokens change all the time. Although the token name is reserved, its value changes. If your front browser window changes from KBM forum to Youtube, the value assigned to %FrontBrowser% will change
Well yes they can, even I can do it with the one token, dates, I seem to be able to use and find very useful.
My example:- the token " short date " in the drop down menu " insert token " is, as a string,
%ShortDate%
You can change that to
%ICUDateTime%MMM d, yyyy%
In fact it will take any ICUDateTime properly written string and change in fact "short date" to "long date" if you wish to create that kind of confusion for yourself using ICU syntax.
I would say that the 'MMM' in that expression is a kind of variable within the Token. All you are doing probably is entering the machinery at a slightly lower level as it were? I wish now I knew programming, Peter's comment on string interlopation and the link he provided was illuminating: as you say ronald, it is a sequence of 'flashes' !
The change to the ICU formatted string produces exactly the same result as the %ShortDate% token. Now I have no idea where or when I got that other format from or why I tried it instead of the date token. I suppose I inferred or intuited that the ICU formats were what Peter is calling 'tokens'. I have the impression I was led to the ICU format from the KM wiki itself in fact.
My guess is that one is entering the machinery as it were at a different level. I take @peternlewis ' point about terminology and he is right. It is very hard to get terms which are fail safe though in any field. Mine is full of similar problems. I have actually taught people excel, very few went away with any understanding of 'function'. I returned to one group I showed stuff to some time later and they just had a kind of hard copy sheet with the formulae I had used written out for mechanical copying into a cell. Some had already degenerated into ill formed versions, brackets left out that kind of thing... By then the formulae were already, anyway, built in to excel and one just had to insert them from a drop down: they required no understanding what so ever of the principles or issues we are discussing. I can't seem to apply that 'can do' method in KM though.
I take points here from all of you and I don't want to skew the discussion to my very particular, in fact peculiar niche of experience. Until I have thought or worked at this a bit more I will stay schtumm and try to pinpoint what I don't understand. Because I still don't really 'get it', I think the fault is in me frankly.
By the by @ronald , a constant is a symbol that stands for an unique number too, it is not that number. In your example if we found we had made a mistake in calculating the speed of light, we could still use "c" for that new number but only that number. In fact constants have been revised. It isn't, as you say, relevant and I didn't mention constants anyway did I?
Sorry, that doesn't fly. You are introducing a broader use of functions in programming that does NOT apply here. So, your follow-on statements about "Actions", "Conditions" does not follow.
I'll stand by my above statement:
Both KM Tokens and KM Functions return some information, some with parameters, and some without parameters.
KM Tokens return text data that can contain numbers
KM Functions return only numbers
In most languages, functions can return numbers or text (and other types), but you have limited KM Functions to return ONLY numbers.
Yes, you have restricted where KM Tokens can be used, and where KM Functions can be used, and this also is a constant source of confusion among new users.
But other than that, how are they functionally different?
Let's think about this from a non-programmers POV:
I need some information about some object, some thing. How do I get it?
I Need
KM Tool
Example
Results
The width of the main screen
FUNCTION
SCREEN(main,width)
2560
The frame coordinates of the main screen
TOKEN
%Screen%Main%
0,0,2560,1440
So now, both Tokens and Functions return info about the screen.
How can I remember which list to look in for what I need?
Edit > Insert Token
OR
Edit > Insert Function
So, Peter, please tell me how KM Tokens are NOT very much like KM Functions?
Or, put another way, what is a better way to describe KM Token than to say they are very much like Functions, but always return text data, and can only be entered into KM Text fields?
I'm afraid I don't have time for a debate on the subject.
I have explained how they are different, and why they have different terminology. “function” is a generic term that covers any mapping from inputs to outputs, and when including side effects, encompasses everything. So fine, everything is a function. Which is useless as far as terminology goes. There are many differences between what Keyboard Maestro classes as a function and what Keyboard Maestro classes as a token.
Sorry, I don't see "many" differences. I only see two:
Type of data that is returned (numeric vs text)
Where the command can be used (numeric field vs text field)
More importantly, is that ==the primary purpose of both is to return information about some object in the user's environment==. (Yes, I know that KM Functions also have a few that are just pure math functions).
Do you disagree with the primary purpose I have stated?
I don't wish to debate this either. My ONLY objective is to come up with a revision to the Wiki article for Tokens that will be clear to most KM users.
The best way to to make it easier for novice Keyboard Maestro users to understand what a token is is with more examples that show how they would be used to solve problems they want to solve.
Currently the page (like most of the wiki) is heavy on reference (which is good, because that helps with clarity and precision), but light on usage. It does a good job of documenting the specifics of “what?”, but it does a poor job of answering the “why?” and “how?” questions.
For someone to understand what a token is, they primarily need to understand what problem they would use it to solve, and how they would use it to solve that problem.
I have made a major rewrite of the Wiki Tokens page.
I have tried to address all of the concerns posted in this thread, as well as other concerns that have been identified.
My sincere thanks to all that have participated here.
Please review and feel free to submit your comments and suggestions at:
Since it might now be relevant. I found the 'debate' between @JMichaelTX and @peternlewis very enlightening as a matter of fact. Some discussions are like that, one learns a lot from them unwittingly from the point of view of the debaters you might say. Thanks for the time and trouble all of you on this thread. As I said I don't want to bend this discussion to much my way being a very narrow niche user. Looking at the discourse pages over all I am guessing that most, maybe nearly all the users who post much here have programming experience?
I will look carefully at your rewrite @JMichaelTX when I can over the next week or so. I and I think others really appreciate the efforts you guys put into this. With much IT these days it is 'sink or swim' or pay me x dollars to do it though I could show you in one minute...
Just to show you what lies behind what I say and doing exactly what you say should clarify things: it didn't though Peter to be fair to Jim here.
This macro is REALLY useful to me. I modified it from the short date token in the drop down menu. As I said I don't really know how I got there. I added two other actions here just to show what I mean to folk. The first action is what I want, formatted as I want, the other one is what %ShortDate% gives and the other one gives the same result but with an explicit format. I maybe confused myself here? Even the question of what the name is a bit vague to me, is it the name in the drop down menu or is it " %ShortDate% " ? Same goes for variables which I think are dawning on me slowly in KM usage. It is fine to delelop ones own usages as you say and as you also rightly say, happens all the time in science and technology.
Thanks for your time, I am now going to re-edit that macro back to just the first action.
@ronald I created a new topic, I thought it best for this. It is relevant I think to this thread but I think it is getting over complicated, partly due to me I confess. I hope folk don't mind me opening a new topic. It shows really how one can modify the date format from the date tokens. If you like. Something a lot of people on this site take for granted I think to be honest. I think it is kind of programming abc?
For triggers, to repeat what I say in the new thread, I would stick with the one that Sparks and others tend to use. $ is used a lot for markup in some places. I think I have LaTeX stuff uses it a lot so I avoid it for other things. double letters I use a lot and make sure I have them only trigger AFTER a space. Works ok. For example I have "p p e n" expand to Pennsylvania but only after a space. Otherwise I get it trigger in the middle of "happen" things like that one can usually sort out when they come up I have found, no need to plan too far ahead. I put the caveat that most of the experts here put in. If you have a large number of expansions it is best to use a dedicated app like TextExpander. I have found KM is better for me actually. More control somehow?
One way to create a new Topic that is related to an existing topic/post, is to click on the Link button at the bottom of the post. This will cause a link to be placed on both the old and new topics connecting the two.
@JMichaelTX Thanks! I really think that has clarified a lot for me since the re write. I really think you have re written it usefully.
It helped me understand how "variables" in KM terminology work at the same time. FYI it clarified, I am not sure what you changed, this one for me;
% Variable % < VariableName > %
see I was reading that as
%Variable%VariableName%
The use/mention distinction is one I know well too, but I just didn't click until I saw your rewrite. I might just have read it wrong initially of course: too much 'speed reading'
and it made no sense to me and examples I tried just wouldn't work, I think that might have been for other reasons now though: you can see how hard it is for a beginner to work through this.
things like that one can usually sort out when they come up I have found, no need to plan too far ahead. I put the caveat that most of the experts here put in. If you have a large number of expansions it is best to use a dedicated app like TextExpander. I have found KM is better for me actually. More control somehow?