[Gmat-developers] GMAT: Function Requirements, paths, creation lines, and all that

[Darrel J Conway]

I thought of another way to handle the Create / path issues - guess I
should have got out and walked around a muttering to myself sooner in
the day today! Let me know what you think of doing it like this (#5 and
7 are the key elements here):

1. No need to Create GmatFunctions; they'll be gleaned from the
CallFunction lines in a script. Any function call that uses a function
name not found in the configuration is set as a GmatFunction. Functions
found in the configuration are set as the type of the configured object
-- either a GmatFunction or a MatlabFunction (until we add other
function types).

2. GmatFunctions must be on a specified path. That path can include
multiple directories. The first function found with the name specified
in the CallFunction will be used.

3. A Create line is always required for MatlabFunctions.

4. Function calls that return data must place the return parameters in
square braces, even if there is only one. (MATLAB does not require
this. I want it to make distinguishing function calls from assignment
commands simple -- without it, a line like "myValue = myCall" is very
difficult to figure out how to parse.)

5. On the GUI, the CallFunction comboBox is populated by
MatlabFunctions and previously gleaned GmatFunctions. Similarly for the
Functions shown on the Resource tree. There is an additional button on
the GUI panel, labeled "Add GMAT Function" (or something similar).
Pressing that button opens a file selection dialog set to the first
directory in the GmatFunction path, and populated by the .m and .gmf
files in that folder. The user selects the GmatFuction from those
displayed, or by navigating to a different folder. (This resolves the
issue with GUI population of the ComboBoxes basically by not populating
them with undiscovered functions, but instead providing a users with a
mechanism to go find the function for themselves.)

6. It is up to the user to ensure that GmatFunctions found using the
file selection dialog navigation in #5 are actually in the GmatFunction
path. (I'm not sure that there is a way to restrict where the user
looks for the function. We could automatically add new directories to
the path, but I don't like doing it that way -- it could have side
effects we do not want, like replacing a function with an unwanted one
of the same name.)

7. Functions are parsed on build. Loading a script located the
corresponding functions, gleaned from the CallFunction commands in a
script, but does not parse the actual function files. (I think we may
be able to do a partial parse here -- enough to check syntax -- but
don't see how we can do a full check outside of the Sandbox without a
LOT of work.)

8. As functions are gleaned, they are added to the resource tree and
the configuration.

9. Writing a script does not write out the object creation lines for
the GmatFunctions. It does write out creation lines for MatlabFunctions.

10. Building a script populates and initializes the corresponding
Sandbox. (That ensures that all object types are validated. I think
the current implementation only populates the configuration and mission
control sequence. This change is the equivalent of going through step
11 of Figure 3.16 in the current Design spec when you build a script.)

11. Loading a script does not populate a Sandbox; it does populate the
configuration and (default) Mission Control Sequence. The implication
is that when you load a script, GmatFunctions are not checked for
syntax. You have to build for this. (Might be relaxed if the partial
parse in #7 works the way I think it will.)

12. Global objects declared (that is, built using a Create command) in
functions are not automatically visible on the GUI. Users will have to
add these by hand, typing the global names into a TBD GUI panel. (The
partial parse in #7 may let us relax this piece.)

13. Objects at the Configuration level all need a "Global" checkbox,
which is initially unchecked except for the objects that are
automatically global. Automatic globals check the box and make it
uneditable.

14. MatlabFunctions cannot call GmatFunctions. (This is never stated
in the current requirements.)

I think this is all workable, and has minimal impact on the current
structure of the components. Does this look workable for you? If so,
we can figure out where the requirements changes need to be made in
tomorrow's review.

- Darrel