CHDK Script Header — chdk

The Script Header

At the start of each uBASIC or Lua script there is a script header section. The script header section is used to define the script name, to identify which version(s) of CHDK the script is compatible with, may contain comments or user notes needed, and defines user parameter variables that can be set at run time from the CHDK Script menu.

For uBASIC scripts, each line of the script header starts with a keyword that begins with the @ symbol. Valid uBASIC keywords are: @title, @chdk_version, @param, @default, @range, @values, and from CHDK 1.4.0 @subtitle.

For Lua scripts, the header is enclosed in a standard Lua long comment delineated by "--[[" and "]]". Valid script header keywords used within the comment field for Lua are the same as those for uBASIC although Lua also includes a "shorthand" notation that offers a more compact format and additional functionality.

Example Script Headers

Lua

 --[[
 20080815 test script by xxx
 @title test script
 @chdk_version 1.3.0
 @param a Duration (min)/-1 disable
   @default a -1
   @range   a -1 3600
 @param     b Mode
   @default b 2
   @values  b None Night Day
 @param     h Endless?
   @default h 0
   @range   h 0 1
 --]]

uBASIC

 @title Interval shooting
 @chdk_version 1.3.0
 @param a Shoot count
 @default a 5
 @param b Interval (Minutes)
 @default b 1
 @range b 0 10

Header Keywords

@title Your Script Title: Defines the title used for the currently loaded script. The title appears on the CHDK <ALT> screen and in the "Scripting Parameters" menu selection of the "Script" menu. Keep your title short (24 characters or less) or the title will overlap the <ALT> symbol. If there is no @title command the file name of script is used.

@subtitle Section Comment: Defines a subtitle that will appear only in the list of script parameters. Used to delineate different sections or groups of script parameters. (CHDK 1.4.0 or later only)

@chdk_version: Used to specify the version of CHDK for which the script was written. A warning is displayed if the user attempts to run the script on a CHDK version older than specified. In Lua, changes the behavior of several functions that return 0/1 in CHDK 1.3 or older and true/false in CHDK 1.4 or newer. Use 2 digit value (i.e. 1.3 1.4 1.5 etc) to specify a release. A full version with build number (i.e. 1.4.0.1234) can be used to specify a minimum build.

@param x (label): Defines the user parameters that can be user entered (or set) from the "Scripting Parameters" menu selection of the "Script" menu. Typical uses include things like setting the number of exposures needed, a time delay needed, or how many bracketing steps to use. "x" is the name of the variable to be set. The (label) is the text string that will appear in your "----Script Parameters----" list, to let the end user know which of the variables they are changing (i.e. number of shots, how many steps, etc.).; If there are no @param values specified, CHDK assumes that there are three adjustable variables: a, b and c.

@default x n: An optional statement that set a default value for variable "x", where "x" is a variable in an @param statement and "n" is the default value to use. This value is set when the script is first loaded.

@range x n m: An optional statement defines the minimum and maximum allowed values for script parameter "x". If the range is set to 0..1 the parameter is displayed in the script menu as a boolean on/off toggle instead of an integer value (the actual parameter value is still an integer though). It is up to the script writer to ensure that the @default value lies within @range - this is not validated when the script is loaded.

@values x aaa bbb ccc ddd eee: An optional statement that specifies a list of strings that are can be scrolled by the user to select a parameter value. The "x" parameter value will be set to the position of the chosen string in the list (starting with 0). String values will only be assigned if there is no "@range" statement.

Notes :

CHDK 1.3.0 or older :

up to 26 @param statements (or user-controllable variables), may be used in any one script.
in uBASIC, there are a total of 52 variables available to use, a to z and A to Z, but the user-definable variables must be lower-case if used for that purpose. Lua allows longer variable names but user parameter variables must still be only a to z
be aware that lower and uppercase variables are unrelated.

CHDK 1.4.0 or newer :

uBASIC programs may use both a to z and A to Z as user parameters.
Lua scripts may use any valid Lua variable name (up to 64 characters in length) that starts with an alpha character (a to z or A to Z) as a user parameter.

Lua Shorthand Parameter Syntax

Starting with CHDK 1.4.0, the Lua header file can also be configured using a "shorthand" syntax that allows a more compact format and a few additional input modes.

Shorthand Parameter syntax:

#varnam=defval "prompt"

for entry of simple numeric parameters without any defined range
if deval is true or false then varnum will be treated as a Boolean variable

#varnam=defval "prompt" [min max]

for entry of simple numeric parameters within a specified range
replaces @range

#varnam=deval "prompt" {opt1 opt2 ... optN}

gives a list of options for user to select from
sets varnam to the index of the option selected by the user
- note: values are zero based. In this example, the returned value of 'opt1'=0, 'opt2=1, etc.
replaces @values

#varnam=defval "prompt" {opt1 opt2 ... optN} table

uses a Lua table for options
the user selected value is returned as varnam.value
the index of the user selected index is returned as varnam.index
- note: Lua table indexes start at 1. In this example, the index of 'opt1' = 1, 'opt2' = 2, etc.
defval sets the default value for varnam.index
varnam[n] returns the table entry indexed by n

#varnam=defval "prompt" long

assigns a long number to varnam
allows assigning a long number to a variable (i.e. greater that 65535)

Notes:

a "#" at the start of a line designates "shorthand" syntax
varnam is the variable name to be used
defval is the default value to be assigned to the variable.
prompt is the string that will be displayed in the Script menu parameter list
the '=' between varnam and defval is optional (if not present use a space)
spaces can be inserted before and after varname if desired
single or double quotes can be used for title but should match (quoting is mandatory).

Sample Scripts

Simple uBasic test sample:

 @title Param Test
 @chdk_version 1.3.0
 @param   a Dial Position
 @default a 2
 @range   a 1 12
 @param   b Mode
 @default b 0
 @values  b Off Stop Start
 @param   c Debug?
 @default c 0
 @range   c 0 1 
 print a b c
 end

The script will also work for Lua with a few modifications:

 --[[
 @title Param Test
 @chdk_version 1.3.0
 @param     a Dial Position
   @default a 2
   @range   a 1 12
 @param     b Mode
   @default b 0
   @values  b Off Stop Start
 @param     c Debug?
   @default c 0
   @range   c 0 1 
 --]]
 print(a,b,c)

And here's a version of the same script using header shorthand format :

--[[
@title Shorthand Test
@chdk_version 1.4.0
# dialpos= 3    "Dial Position" [1 12]
# mode   = 1    "Mode"          {Off Stop Start}
# dbug   = true "Debug?"
# fstop  = 6    "f-stop"        {2.8 5.6 8.0 11.0 16.0} table
--]]
print(dialpos, mode, dbug)
print(fstop.index,fstop.value)
print(fstop[2])

Finally, here's a little script that shows the difference in returned index between the two methods of picking from a list of values. Run the script with default values selected and notice the different values that will show in the Script Parameters menu items.

--[[
@title Zero/One Base Test
@chdk_version 1.4.0
# fstop1  = 6    "f-stop1"        {2.0 2.8 3.2 3.8 4.0 5.6 8.0 11.0 16.0}
# fstop2  = 6    "f-stop2"        {2.0 2.8 3.2 3.8 4.0 5.6 8.0 11.0 16.0} table
--]]
print(fstop1)
print(fstop2.index)