Hi. While I am a home-brewed scripter, I do sometimes need an object model. In being more interested in dropping other browsers completely, and making KM my own, of course I wish to script it some. I can muddle through others and take pieces ok, but that is not understanding.

In the reference section of website, there is section called 'K-Meleon Macro Coding Guidelines'. This is a start, but I feel that it is lacking some good examples. I understand what a module is, but honestly looking at already made macros is not straight forward in seeing the buidling blocks.

Is there anyone who has the time to put together an example of the macro with comments. Something along the lines maybe of

# Give title
# here we are declaring our macro name
example
# here we are preparing to call functions
example
# here we are initializing something
example

And then also an overall view, much like a DOM

# must start with init here
example

# must have funcs between these
example

# must have these funcs here
example

# understand heirarchy of macro layout
# this is always first
# this must be used after the other is declared

I am not looking for how to write a procedure, but more when building a macro from scratch, what are the do's and don'ts and why must you put this here or that there. The resources are very fine for all the methods and functions. It is the macro structure that I can't find a good set of laws for.

Many thanks.

MrWoo.

That is a tall order. I will try put more comments into my macros. One place that has some more info is this page.
http://kmeleon.sourceforge.net/wiki/MacroLanguage2

I have not always been exact in following the guidelines when I get in a hurry to finish a macro. I need to do better.

You asked about macro titles. They should be unique. They should give some idea of the function of the macro. I have tried to use a title block in comments at the top of each macro. I suspect that I copied one from kko to use as a model.

# ---------- LoadTime.kmm
# ---------- K-Meleon Macro Language to poll the time before and after pageload ---------------
#
# Dependencies		: main.kmm
# Resources				: LoadTime.js, wscript.exe
# Preferences			:  "k-meleon_loadtime_active"
# Version					: 0.5   2008-10-05
# --------------------------------------------------------------------------------

The forum is not doing code blocks right so some lines may wrap when they should not and space created by tabs does not show.

The first line has the name given to the macro with the extension .kmm

The second line says it is the KM macro language and a brief description.

The next line is for other macros that this macro requires in order to run. Most will require main.kmm.

The next line is for resources. Other files that are needed and other programs that must be available.

The next line for preferences is to list the user_prefs that this macro might create or use. In this example LoadTime.kmm creates "k-meleon_loadtime_active".

The last line is important for users in case the macro has an upgrade. They can check their version/date against the info on another post or what is in the MacroLibrary to see if there has been a change.

I will try to be more generous with comments on my next macro for you.

I hope my previous post was helpful. I was worried about how to do this. Knowing a little about macros does not mean I am qualified to teach macros. I will try to get something new on LoadTime and will put more comments there.

For others than MrWoo, LoadTime is in this thread.
http://kmeleonbrowser.org/forum/read.php?1,84307

Not implying anything about your macros at all JamesD. At all.

I was entertaining some ideas with some practice macros to build, and then I realized that I don't understand the structure of the macro.

For instance, the # is a comment operator.

# ---------- LoadTime.kmm
# ---------- K-Meleon Macro Language to poll the time before and after pageload ---------------
#
# Dependencies : main.kmm
# Resources : LoadTime.js, wscript.exe
# Preferences : "k-meleon_loadtime_active"
# Version : 0.5 2008-10-05

Does this mean that you are declaring a dependency, or just stating it so that others know that main.kmm IS going to be needed. Thus dependency of say TEST1.kmm means that witout TEST1.kmm in the macro dir, this macro won't function.

Resources, again, is this just a comment?

I think I need to rephrase what I want. Let me give you an example from your LoadTime macro.

You give the commented description as above. That is understood if they are comments.

So next in your macro, you use LoadTime_some func. You start with RunCode, then Loaded_Run, Then others with some being global and some local in scope (or so I think, by the _ character). Then, lastly are what looks like actual KM functions. Normally I have been used to the body of the script being first.

Declare globals
Get Data, set prefs
some logic loop, for/next while do If/Else
These logic loops then call functions

Functions being listed after the main script, in any order.

So, this is probably an easy answer, I just have not seen it layed out anywhere. Then again, as my C skills are very limited, this may be a structure that is inherit to that class, and I just don't know it.

I am most interested about the dependencies and resources, as other than what I think is a comment at the top, I see nowhere that implicitly states "if not exist X then exit macro"

And thanks for the help btw.

MrWoo.

EDIT: Are there any arrays available in the macro language? As in, can I create an array ($arr = xyz)? I see you can view array by the index though.



Edited 1 time(s). Last edit at 10/08/2008 08:23PM by MrWoo.

Short on time right now so I cannot answer all.

Yes, everything with one or more # at start of line is a comment. In my last post everything was just a big comment.

We don't declare variables. A variable is set up when you first set it equal to something. $_MacroName_String = "Column a"; or $_MacroName_Number = 8;

We do not have arrays.

What you see with this form is a module. I don't think we have functions.

_MacroName_ModuleName {
< one or more code line >
< a line here may call another module ie. &_MacroName_ModuleName2 >
}

In the Macro Guidelines there is a section how the use of $ and _ make modules local or global.

@ MrWoo

You said -------
I am most interested about the dependencies and resources, as other than what I think is a comment at the top, I see nowhere that implicitly states "if not exist X then exit macro"
----------------

This is done with special global variables. In the following example the macro is to work on tabs. Therefore it should not display it's memu item unless tabs are running.

code -------
_FileAllTabs_BuildMenu{
# add another option to the File menu
$kTabs?setmenu("&File",macro,"File All Tabs",_FileAllTabs_RunCode,3):0;
}
end code ----

$kTabs is the variable. It has a boolen value, true or false. Here it is used in a conditional statement. The part of the statement after the ? and before the : is executed if the condition, $kTabs, is true. If the $kTabs value was false the part of the statement after the : would be executed. In this case 0, a zero, means do nothing.

There is no "exit" statement. Instead your code must not start on a condition like the above example or you must reach to bottom of the executing module without doing anything that you do not wish done.

Since a conditional statement can call other modules, you put the things to be done in modules. If there can be a condition where some code should not execute then a conditional statement in the currently executing module would decide whether to call the other module. I will try to find time to make an example.

Oops, forgot to say that the list of variables like $kTabs can be found in k-meleon\macros\main.kmm somewhere about line 35.

@ MrWoo

This little macro is an example of modules calling modules and needing to finish the macro under certain conditions without calling some modules. For space I have left off the title block. Once you have it, feel free to ask question about any part.

Because the forum is not resolving code blocks right now you will have to "fix" this code after you copy it to your computer. All lines except comments and those that have a { or } on them must end in a semi-colon. The forum is wrapping lines so you will have to go to the end of each line without a ; and hit del key until the line below connects.

WaterUse.kmm

--- code starts -------
## WaterUse.kmm (comment block omitted for space)

WaterUse_RunCode{
$_WaterUse_UnitsPerBottle = 3 ;
$_WaterUse_BottlesOnHand = prompt( "Enter number of available.", "Water Bottles" );
$_WaterUse_BottlesOnHand > 0 ? &_WaterUse_Possible : &_WaterUse_ImPossible ;
}
_WaterUse_Possible{
$_WaterUse_PeopleOnHand = prompt( "Enter number", "People on station" ) ;
$_WaterUse_BottlesOnHand < $_WaterUse_PeopleOnHand ? &_WaterUse_Units : &_WaterUse_Bottles ;
}
_WaterUse_Units{
$_WaterUse_UnitsOnHand = $_WaterUse_BottlesOnHand * $_WaterUse_UnitsPerBottle ;
$_WaterUse_Distribution = $_WaterUse_UnitsOnHand / $_WaterUse_PeopleOnHand ;
$_WaterUse_Remainder = $_WaterUse_UnitsOnHand % $_WaterUse_PeopleOnHand ;
alert( "Each person gets " . $_WaterUse_Distribution . " units.\n" . $_WaterUse_Remainder . " units reserved", "Water Distribution", INFO) ;
}
_WaterUse_Bottles{
$_WaterUse_Distribution = $_WaterUse_BottlesOnHand / $_WaterUse_PeopleOnHand ;
$_WaterUse_Remainder = $_WaterUse_BottlesOnHand % $_WaterUse_PeopleOnHand ;
alert( "Each person gets " . $_WaterUse_Distribution . " bottles.\n\n" . $_WaterUse_Remainder . " bottles reserved", "Water Distribution", INFO) ;

}
_WaterUse_ImPossible{
alert( "Nobody gets to drink.", "- WATER -",EXCLAIM );
}
_WaterUse_BuildMenu{
# add another option to Favorites menu
$kFavorites?setmenu("F&avorites",macro,"Water Use",WaterUse_RunCode,3) : 0;
}
_WaterUse_SetAccels{
$kFavorites?setaccel("CTRL ALT W", "macros(WaterUse_RunCode)") : 0;
}
$OnInit=$OnInit."_WaterUse_SetAccels;";
$OnInit=$OnInit."_WaterUse_BuildMenu;";
$macroModules=$macroModules."WaterUse;";
--- code ends --------



Edited 1 time(s). Last edit at 10/09/2008 09:57PM by JamesD.

Those are great examples. I will have to inspect them a bit closer and then make some simple ones myself to digest it. Thanks.

It seems after looking at lots of macros in the resources and yours, that the word modular in KM macro is really a procedure, or in vb would be sub (subroutine), or in autoit a func (function).

Modules in respect to vb would be a comprehensive set of code, where specific fucntions or routines would take place. For example you might have a module for all print functions that the application might need.

I think it is easier to understand this script language when I understand how it differs from others. KM modules, call them whatever one desires, are simply routines. They are named, and can be global or private. They seem to have no return value at all unless you have variables set within them, or a setting somewhere in KM is changed within them.

So it would seem then, that you write your modules for the macro, and then to start it out, you use the oninit functions at the bottom. In loose terms, you declare your code in the modules, they are loaded into memory, and then the bottom secion sets the action, whether it is setting prefs, or accelerator keys, or waiting for specific menu item, or even starting one of the modules right away.

Does this sound like a correct assumption?

Again, thanks for the time to expound on this.

MrWoo.

I think you are getting this very good. The bottom section, your discription, is only in the macro. It is not in a macro module. Therefore that code is executed when the macro is first read, ie when KM starts. The modules only get executed when they are called. They can be called by menu, accel keys, button press, or other modules.

MrWoo wrote:
-------------------------------------------------------
> [...]
>
> Does this sound like a correct assumption?

No, you are mixing up the terms "macro" and "module". A "macro" is a named block of code - like a sub in VB or a func in AutoIt, just that you cannot pass any parameters to it (at least not from a macro) and that it cannot return any value. A "module" is a set of macros encapsulated in a KMM file. So, modules are more like independent VBS files that you embed into a WSH file for instance.

Macros are always global, variables can be both global and local depending where you declare them. All macros are public - any macro can call any other macro. All global variables are public - any macro can access any global variable. The differentiation between public and private macros/variables in the Macro Coding Guidelines is meant in regard to their intended purpose (intended by the author), not in regard to the way the macro parser is handling them. The sense of the Macro Coding Guidelines is to improve the readability of the code and to avoid problems in conjunction with other custom-made modules.

Modules (KMM files) are parsed top to bottom. It doesn't matter where exactly inside a module you define a macro or where exactly you assign a value to a variable. Parsing takes place once at application startup. The main module (main.kmm) is parsed first. Then the other modules in the default macros folder are parsed (in alphabetical order). Then the modules in the user macros folder are parsed (in alphabetical order aswell). The result is like copying the contents of all the modules into a single file (in the order in which they are parsed).

Overall: I guess it's less complicated than you think. Just go play!

No, you are mixing up the terms "macro" and "module". A "macro" is a named block of code - like a sub in VB or a func in AutoIt, just that you cannot pass any parameters to it (at least not from a macro) and that it cannot return any value. A "module" is a set of macros encapsulated in a KMM file. So, modules are more like independent VBS files that you embed into a WSH file for instance.
=---------------=

Ok. This explains some then. You say then that the kmm file is a module basically, and is comprised of the macros within. I understand there is no parms or returns to the macros. This is almost like VB where you have the typical modMain (module), which contains different subs, whereas in this case the kmm is the module, and the code within are the subs.

You are correct, this is easy. However, as in any language, one may know how to speak the individual words or what they mean, but structuring a sentence is not always the same.

Thanks for the input.

MrWoo