Named arguments and argument defaults

In your code that calls functions, you can specify argument names explicitly rather than relying on matching the declaration order of the arguments. This helps make your code more readable. For example, typical method calls might look like the following:

someMethod(true, false)

If you pass series of one or more comma-separated arguments, it is difficult or impossible to tell what each value represents. It can be difficult to visually confirm the argument order in code that was written long ago or written by others.

Alternatively, for each argument you can explicitly specify the argument name. Instead of just the argument value, pass the following items in this order:

1. A colon character
2. The argument name
3. The equal sign
4. The value

For example:

someMethod(:redisplay=true, :sendUpdate=false)

You can optionally provide default argument values in function declarations. By providing a default argument value, you permit a function caller optionally to omit that argument. To declare a default, follow the argument name with an equal sign and then the value. If the function caller passes the argument, the passed-in value overrides any declared default value.

For example, consider the following function that prints String values with a prefix:

class MyClass {
  var _names : java.util.ArrayList<String>

   construct(strings : java.util.ArrayList<String>) {
    _strings = strings
  }

  function printWithPrefix(prefix : String = " ---> ") {
    for (n in _strings) {
      print(prefix + n) // used a passed-in argument, or use the default " ---> " if omitted
    }
  }
}

In the printWithPrefix declaration, the prefix value has the default value " ---> ". To use the default values, call the printWithPrefix method and omit the optional arguments.

The following example calls the printWithPrefix method using the default value:

var c = new MyClass({"hello", "there"})

// Because the argument has a default, it is optional -- you can omit it
c.printWithPrefix()

The following example calls the printWithPrefix method providing an explicit value:

var c = new MyClass({"hello", "there"})

// Specify the parameter explicitly (ignores default) as traditional unnamed argument
c.printWithPrefix(" next string is:") 

// Specify the parameter explicitly (ignores default) as named argument
c.printWithPrefix(:prefix= " next string is:")

The Gosu named arguments feature requires that the method name is not already overloaded on the class.

When you call a function with a multiple arguments, you can explicitly name some of the arguments and not others. The following are the rules for the calling convention of functions using the named argument convention and argument defaults:

• The named arguments can appear in any order.
• For any non-named arguments in the function call, the order must match in left-to-right order any arguments without defaults. Gosu considers any additional passed-in non-named arguments as representing the arguments with defaults, passed in the same order (left-to-right) as they are declared in the function.

If you use a named parameter in a function call, all following parameters must be named parameters.