Getting my head around the Pymol documentation brackets

Question

[underoath006]

I don't understand this bracket notation here at all:

cmd.load( filename [,object [,state [,format [,finish [,discrete [,multiplex ]]]]]] )

I've been trying to use the Pymol API but I find the documentation to be very confusing. How do you recommend I go about understanding it?

Answer 1

[jonasmst]

Usually, [ ] means the argument is optional, but I've never seen it nested like this before. Anyway, I found this documentation to be a bit more clear:

cmd.load(string filename, string object-name, integer state,
         string format, int finish, int discrete, int quiet,
         int multiplex, int zoom, int partial)

It even shows how the function is implemented:

def load(filename, object='', state=0, format='', finish=1,
         discrete=-1, quiet=1, multiplex=None, zoom=-1, partial=0):

To summarize, filename is mandatory, the rest is optional with the above default values and types.

[John]

When it's nested like that it just means the inner argument is conditional on the outer argument being present, but the inner argument is optional.

For example, the Unix tool for changing your password "passwd" has a syntax on OSX like:

passwd [-i infosystem [-l location]] [-u authname] [user]

Where you can only use -l if you first use -i.