Parameters in PHP documentation, squared brackets?

Question

This function for example...

int preg_match_all ( string $pattern , string $subject [, array &$matches [, int $flags = PREG_PATTERN_ORDER [, int $offset          


        

Answer 1

This is an old convention from Unix systems' Usage messages:

On Unix-like platforms, usage messages tend to follow the same commonly-used pattern users are familiar with. They often begin with "Usage:" (hence possibly the name), the command, followed by a list of arguments. To indicate optional arguments, Square brackets are commonly used, and can also be used to group parameters that must be specified together. Exclusive parameters can be indicated by separating them with vertical bars within groups.

Here is a thorough example based on the NetBSD source code style guide:

Usage: program [-aDde] [-f | -g] [-n number] [-b b_arg | -c c_arg] req1 req2 [opt1 [opt2]]

This would indicate that "program" should be called with:

• options without operands: a, D, d, e (any of which may be omitted). Note that in this case some parameters are case-sensitive
• exclusive options: f, g (denoted by the vertical bar)
• options with operands: n
• exclusive options with operands: b, c
• required arguments: req1, req2
• optional argument opt1, which may be used with or without opt2 (marked optional within the group by using another set of square brackets)
• optional argument opt2, which requires opt1