AM is in desperate need of better documentation

[Econdoc]

While I love AM, I am often frustrated by its lack of documentation and, as importantly, examples, examples, and more examples. Please take this message as a plea for better documentation and not a rant.
Since one cannot see the flows that are discussed in the forum, it is very difficult to decrypt some of the logic.

Here are a few of the issues that I have run across lately. Some I have resolved (at a loss of some head hair) and some remain a mystery.
• The trigger “WiFi Scan Results Available,” is described this way: “The trigger WiFi Scan Results Available is executed when the results of a WiFi access point scan are available.” What does that mean? What triggers this trigger? Totally lost as to how to use this.
• Functions are found only under Actions-Script. That implies that such functions can only be used in scripts. If I am not mistaken, one can include functions in notifications, both on screen and on the statusbar. This is not really made clear anywhere, nor are there examples that I can find showing how this might be done. Under notifications, it says that variables are supported, but does not mention functions. (I like notifications like this: “Stopped at {GetDate(),dateformat,HH:mm:ss}”. There is no documentation about this and many other helpful things.
• Glob pattern are never defined not could I find a single example of them. Can they be used in the contains() function? Can they be used in matches()? When can they be used? What are the restrictions on their use?
• It is not clear that (apparently) all variables except those declared global, are static. For example, variables like location_name, ssid, etc. are static. They only exist in the current flow. I guess that if you want to save a variable like ssid you need to create a global variable like global_ssid=ssid. Examples like this are immensely helpful! If an action creates a variable like ssid, can it be used several actions/conditions later in the same flow?
• What are maps? I could not find any definition for them. How can I use them if I don’t know what they are?

AM would be open to a vastly larger audience if users had a better idea of what thing did in AM. I suspect that my frustration is shared by many and that many have given up because of lack of direction. Please help those of us who are still struggling.

[Bushmills]

The trigger WiFi Scan Results Available is executed when the results of a WiFi access point scan are available.
What does that mean?
What triggers this trigger?

The logic behind this is similar to the logic of this sentence:
The device "light bulb" is turned on when the switch is flicked

Let's decompose the sentence:

Code: Select all

The trigger                                              //             (Automagic knows of triggers, actions, conditions. This clarifies that next line refers to a trigger)
   WiFi Scan Results Available               //            <- that's the trigger
is executed                                             //           (or, "fired", or "triggered")
  when the results of a                            //            <- results can't be provided before they are available 
  WiFi access point scan                        //            <- "when your device collected available SSIDs" - this happens sometimes by itself, without your doing,
                                                               //                 but you can force this yourself by executing the Automagic action, "WLAN scan"
are available.                                         //             ("have been attained, acquired. ")

Functions are found only under Actions-Script.

Script actions are the most likely place to use functions, followed by expression conditions. In notifications, as mentioned in your question, and elsewhere execution functions need to be "forced", by enclosing them in curly brackets { }, as you would with variables, where against in scripts and expressions, interpretation defaults to evaluation of functions and variables. Therefore it is more natural to find description of functions with script actions (but could/should also be available with expression conditions).

Glob pattern

As far as I remember, actions and triggers say in their definition dialog where and when use of wildcards is legal and supported, but I can't make any statement about the completeness of these mentionings.

What are maps?

Akin to "hashes", "associative arrays" and what other names have been given to them in other languages. Essentially data structures resembling arrays, but indexed by text strings. For addressing a map element, the text string is hashed, then some anti-collision method is employed. Where an array with numeric indexes associates data with numbers, a map associates data with strings.

variables

I think it's the so-called "scoping" (https://en.wikipedia.org/wiki/Scope_(computer_science)) you refer to here: Where and when is a variable visible? It appears you have figured that out already: global_.. are global (visible beyond flow boundaries), others aren't (visible within flow boundaries only).

The information conveyed in these answers has been gathered by reading the lacking Automagic documentation, as no other source of information has been available (apart from some experimentation, which was needed where the documentation wasn't clear. One case I remember is function getValue(name, default) where name is a quoted string or result of variable substitution, if unquoted).

[Bushmills]

Since one cannot see the flows that are discussed in the forum, it is very difficult to decrypt some of the logic.

There's a small "trick" Martin told me about, if you're weary of downloading flows into your working environment:
In Automagic settings, change main directory from "Standard" to "User defined", prior to importing flows from forum. User defined main directory defaults to "AM", contrasting with standard "Automagic". Import, examine, modify those imported flows to your heart's delight - your working Automagic environment remains unaffected.
When done, switch back to "Standard".