User Defined Functions Standards

This Page contains instructions on submitting UDF's for AutoIt3, it helps me if code is submitted following the below standards and include those 1 +2*n files::

  1. NewUDF.au3 (the actual UDF in the proposed include filename)
  2. FunctionName.txt (the text file to be used to build.the helpfile page of AutoIt.chm)
  3. FunctionName.au3 (the example script to be used in the helpfile)

There is as many 2+3 as function to be described.

You will appreciate that we can only include those UDF's that are useful to a larger group of scripter's.
When you still like your UDF to be included :-) then:

  1. Follow the below instructions for the files.
  2. Ensure your UDF is error free by running AU3Check with options:-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w 7.
  3. Ensure your UDF code is Tidy.
  4. Send me a PM that contains the files in a zip file. (guinness or  jpm) .

Thanks,
guinness and jpm

User Defined Function coding standards

Function Names
All function names must start with an underscore (“_”). *
Each word in the function name should be capitalized.
The first word of the function name should start with a word describing a general category such as “Date”, “String”, “Array”, “Network”, etc.. If the word is too long like “Window”, then an obvious abbreviation may be used (e.g. “Win” for “Window” or “Net” for “Network”).
All function names must closely resemble the established naming convention for "internal" AutoIt functions.

Variable Names
The first set of characters after the dollar sign (“$”) should be used to specify the type of data that will be held in it. The following list signifies the different prefixes and their data type significance.
    $a<letter> - Array (the following letter describes the data type taken from the rest of the data types below)
    $d - Binary data
    $h - File or window handle
    $id - An AutoIt control Id (GUI)
    $i - Integer
    $b - Boolean
    $f - Floating point number
    $n - general number with no preference for floating point or integer
    $s - String
    $v - Variant (unknown/variable type of data)
    $o - COM object
    $p - Pointer. It is assumed that it points to a struct so no further letters are needed
    $t - Structure returned from DllStructCreate()
    $tag - Struct definition string. Structure definitions should conform to the structure guidelines
The rest of the name uses capitalized words to describe the function of the variable. Names like “$iC” are unacceptable. "$aiWeekDayNames" or "$iCounter" are much preferable.
All variables must be declared at the beginning of the UDF with a “Local” scope and before they are used for the first time.
This convention apply also to Local/Global variables. Global variables must have an extra first letter "g". UDF global variables must start with underscore.
Const/Enum variables are better if they are defined in UpperCase to illustrate that they cannot be changed. First letter of the constant is optional, $e can be used.

Note: Global variables should only be used if they are called from more than one function or used in another scope. For example if the variable is only used in main scope regardless of not in a fuction, then it should be declared using Local.

The “Dim” or “Global” keywords are ambiguous inside of a UDF and as such should be avoided, all variables should be transferred via the Function Parameters using Byref when the updated value needs to be returned.

Parameters
The parameter names must use the same naming conventions as variables.
All parameters must be checked for validity and return appropriate error codes.
If parameters are used to pass data back to the calling script (ByRef), then the documentation should explicitly describe said behavior.

Function Documentation
All UDFs must have a documentation header in the script in the following form:

; #FUNCTION# ;===============================================================================
; Author ........: Jos van der Zande
; Modified.......:
; ===========================================================================================
Func _DateDiff($sType, $sStartDate, $sEndDate)
...

 

Function Helpfile Documentation

All submitted UDFs must include 1 extra file to be able to incorporate them in the Helpfile:

FunctionName.txt. This is the example to be used to build the  Helpfile page for AutoIt.chm

###User Defined Function###
Name goes here.

###Description###
One-line description

###Syntax###
#include <NewUDF.au3>
One-line syntax spec. ###Parameters### @@ParamTable@@ Description ParamTables are special, two-column tables where the first column is only one line, but the second column can be many lines. How To Denote Any information that appears in the second column must be indented with at least one tab. Each entry that is NOT indented begins a new row. DO NOT LEAVE ANY BLANK LINE BETWEEN HERE AND "@@End@" @@End@@ Parameters naming as described above. ###ReturnValue### @@ReturnTable@@ Success: @TAB followed by info for second column as 1. ; If several line are needed to describe they must start with @TAB. More than one @TAB allows small extra indentation. Failure: @TAB followed by info for second column as 0. @error: @TAB followed by value explanation. @@End@@ ###Remarks### In general, whitespace outside of tables is ignored. @TAB are converted to 4 blanks which allow small identation. IN the Remarks Section: non-consecutive blank lines are converted as HTML <br />'s. You can also use <strong>bold</strong> and <em>italic</em> tags. Pretty much any HTML formatting can be used, since this text is more or less copied directly over to the htm file. Remarks go here. Here's a standard table; each line is a new row, and columns are tab-separated: @@StandardTable@@ row1col1 row1col2 row1col3 row1col4 row2col1 row2col2 row2col3 row2col4 @@End@@ ###Related### Foo, Bar (Option), <a href="whatever/baz.htm">Baz</a> ; the above will be converted to the following HTML: <a href="foo.htm">Foo</a>, <a href="AutoItSetOption.htm#Bar">Bar (Option)</a>, <a href="whatever/baz.htm">Baz</a> ###See Also### @@MsdnLink@@ stringToBeSearched ; A Link that will search on the Msdn Online library will be inserted.

;This section is optional.

###Example### @@IncludeExample@@ [NameOfDuplicateUDF] ; All examples should pass #AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7 without errors or warning. ; If the optional name is defined it will be the file NameOfDuplicateUDF.au3 will be used.

FunctionName.txt. This is the example to be used to build the  Helpfile page for AutoIt.chm
(Example):

###User Defined Function###
_DateDiff

###Description###
Returns the difference between 2 dates, expressed in the type requested

###Syntax###
#include <Date.au3>
_DateDiff ( $sType, $sStartDate, $sEndDate )


###Parameters###
@@ParamTable@@
$sType
	One of the following:
	D = Difference in days between the given dates
	M = Difference in months between the given dates
	Y = Difference in years between the given dates
	w = Difference in Weeks between the given dates
	h = Difference in hours between the given dates
	n = Difference in minutes between the given dates
	s = Difference in seconds between the given dates
$sStartDate
	Input Start date in the format "YYYY/MM/DD[ HH:MM:SS]"
$sEndDate
	Input End date in the format "YYYY/MM/DD[ HH:MM:SS]"
@@End@@

###ReturnValue###
@@ReturnTable@@
Success:	Difference between the 2 dates.
Failure:	0 and sets the @error flag to non-zero.
@error:	1 - Invalid $sType
	2 - Invalid $sStartDate
	3 - Invalid $sEndDate
@@End@@


###Remarks###
See <a href="_DateTimeSplit.htm">_DateTimeSplit()</a> for other possible variations of the start and end date formats.


###Related###
_DateAdd, _DateTimeSplit, _DateToDayOfWeek, _DateToDayOfWeekISO, _DateToDayValue, _DayValueToDate, _NowCalc


###Example###
@@IncludeExample@@ _NowCalc

FunctionName.au3. This is the example to be included in the Helpfile

#include <Date.au3>

; Calculated the number of seconds since EPOCH (1970/01/01 00:00:00)
$iDateCalc = _DateDiff( 's',"1970/01/01 00:00:00",_NowCalc())
MsgBox( 4096, "", "Number of seconds since EPOCH: " & $iDateCalc )

; Calculated the number of Hours this year
$iDateCalc = _DateDiff( 'h',@YEAR & "/01/01 00:00:00",_NowCalc())
MsgBox( 4096, "", "Number of Hours this year: " & $iDateCalc )