Using Macros

 Top  Previous  Next

FreeFlyer supports the use of Macros to provide "find-and-replace" functionality, allowing users to create generic sets of FreeFlyer script, using arguments to specify identifiers that will be replaced when the Macro is instantiated by the Call command. While Procedures require the user to declare the type for each argument passed to the Procedure, Macros allow users to pass any identifier without specifying the argument type. Examples of "identifiers" include FreeFlyer objects, object properties or methods, functions, variable values, and string values.

 

The following Sample Mission Plans (included with your FreeFlyer installation) demonstrate the use of Macros in FreeFlyer:

 

Interfacing with External Resources Samples

•Using Externals

 

Demos

•Kalman Filter OD - Lunar TDRS Relay

 

Syntax

•Macros may be defined in the Mission Plan or in an external file. See the Include command for more information.

•Macros are instantiated using the Call command.

•Macros are defined using the Define Macro command.

 

Details on Macro Implementation

•When a Macro is instantiated using a Call command, the contents of the Macro are executed as though they were literally copy-and-pasted into the body of the Mission Plan where the Macro was called.

oAny identifiers that were passed as arguments to the Macro are substituted into the script.

oObjects that were created in the Mission Plan also exist in the Macro. There is no need to define objects as "Global".

oObjects that are created in the Macro will continue to exist in the Mission Plan after the Macro is called.

oMacro contents are substituted in-place of the Call command at parse-time, so runtime functionality, including the use of breakpoints, is unavailable for the Macro's contents.

 

Find-and-Replace Example

The example below defines a Macro which will substitute "Spacecraft1" in every instance of the characters "SC", "ObjectCreatedInMacro" for "name", and "Spacecraft.E" for "ecc". When the Macro is instantiated using the Call command, it will change the values of Spacecraft1.A and ObjectCreatedBeforeMacro, and create a new Variable with the name "ObjectCreatedInMacro".

 

Note that the "ObjectCreatedBeforeMacro" Variable was not passed as an argument, nor is it a Global object, but it can still be accessed within the Macro.

 

Define Macro FindAndReplace(SC, name, ecc);

 

    SC.A = 8000;

    ObjectCreatedBeforeMacro = SC.I - 5;

    Variable name = ecc;

 

EndMacro;

 

// Do not need to declare this Variable as Global or include it as an argument

Variable ObjectCreatedBeforeMacro;  

 

// Call Macro

Call FindAndReplace(Spacecraft1, ObjectCreatedInMacro, Spacecraft1.E);

 

// Objects created in Macro can still be accessed after Macro is called

Report Spacecraft1.A, Spacecraft1.I, ObjectCreatedBeforeMacro, ObjectCreatedInMacro;

 

// Can't call Macro a second time with the same identifier in the second argument ("name")

// This is because an object was created with that name

// Now that it exists, it can't be created again

 

Create Object Example

This simple Macro allows the user to create an object, using the Call command to specify the type of object to create (String or Variable), the name of the object, and the value to assign to the object.

 

Define Macro CreateObject(type, name, value);

 

    type name = value;

 

EndMacro;

 

// Call Macro first time

Call CreateObject(Variable, v, 17.432);

 

// Can call Macro a second time so long as a different object name is specified

Call CreateObject(String, s, "Macro Test");

 

// Objects created in Macro can be accessed after Macro is called

Report v, s;

 

 

Call Function Example

This Macro allows the user to specify the math function to perform in a calculation. In this example, the identifier "abs" is substituted wherever "function" appears in the Macro.

 

Define Macro Function(function);

 

    Spacecraft1.I = function(-7);

 

EndMacro;

 

Call Function(abs);

 

Report Spacecraft1.I;

 

 

Macro Functions

__macro_quote__ and __macro_single_quote__

These Macro functions allow users to obtain a quoted string containing the value passed by the Call command into the specified identifier. Simply placing quotation marks around an identifier will return the literal string without substituting the value (find-and-replace is not performed). The example below illustrates how the quoted string "SC" will be reported as "SC", while __macro_quote__(SC) performs the find-and-replace and is reported as "Spacecraft1". __macro_single_quote__(SC) is reported as 'Spacecraft1'.

 

Define Macro Quote(SC);

 

    Report "SC", __macro_quote__(SC), __macro_single_quote__(SC);

 

EndMacro;

 

Call Quote(Spacecraft1);

 

 

__macro_rest_cdl__

Macros allow users to specify extra arguments when calling the Macro in addition to the arguments that were specified when the Macro was defined. The __macro_rest_cdl__ function allows users to access these additional arguments as a comma-delimited list (hence, "cdl"). In the example below, the Macro is defined with zero arguments, but three arguments are passed using the Call command. The example shows how the function __macro_rest_cdl__ can be used to capture the extra string arguments, which can be concatenated into a single string.

 

Define Macro ExtraStringArguments();

 

    String GetCDL = StringConcat(__macro_rest_cdl__);

    Report __macro_rest_cdl__;

 

EndMacro;

 

Call ExtraStringArguments("a", "b", "c");

 

// Objects created in Macro can still be used

Report GetCDL;

 

// Can't call Macro a second time because an object (GetCDL) was created

// It exists now, it can't be created again

 

 

In this example, the Macro is defined with one argument, but four arguments are passed using the Call command. The example shows how the function __macro_rest_cdl__ can be used to capture the extra variable arguments as a comma-delimited string, which can be used to set properties such as Spacecraft1.Position.

 

Define Macro ExtraVariableArguments(SC);

 

    SC.Position = {__macro_rest_cdl__};

    Report __macro_rest_cdl__;

 

EndMacro;

 

Call ExtraVariableArguments(Spacecraft1, 5000, 8000, 0);

Report Spacecraft1.Position;

 

 

This Macro creates an object and sets its name, using a combination of the __macro_rest_cdl__ and __macro_quote__ functions.

 

Define Macro SetName(a);

    Variable a;

    a.Name = __macro_quote__(__macro_rest_cdl__);

EndMacro;

 

Call SetName(ScriptName,DisplayName);

 

Report ScriptName.Name;

 

 

See Also

•Define Macro Command

•Include Command

•Call Command