Passing a command argument to a macro: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "__TOC__ <span class="f_Para">As described in Creating and running a macro, many commands require arguments when used within a macro. You can u...")
 
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 6: Line 6:
<span class="f_Para">To use the </span><span class="f_Monospace">&amp;argstring</span><span class="f_Para"> variable to pass an argument to a command in a macro: </span>
<span class="f_Para">To use the </span><span class="f_Monospace">&amp;argstring</span><span class="f_Para"> variable to pass an argument to a command in a macro: </span>


1. In the macro, specify<span class="f_Monospace">&amp;argstring</span><span class="f_ListNum1"> where you would normally specify the command argument. </span>
: 1. In the macro, specify<span class="f_Monospace">&amp;argstring</span><span class="f_ListNum1"> where you would normally specify the command argument. </span>
: For example, note the use of <var>&amp;argstring</var><span class="f_ListContinue"> in the </span><var>breaksAt</var><span class="f_ListContinue"> command in the following macro: </span>
:: For example, note the use of <var>&amp;argstring</var><span class="f_ListContinue"> in the </span><var>breaksAt</var><span class="f_ListContinue"> command in the following macro: </span>


<p class="syntax"><span class="f_CodeExList"># Run till line that matches the user-passed string </span>
<p class="syntax"><span class="f_CodeExList"># Run till line that matches the user-passed string </span>
Line 16: Line 16:
<span class="f_CodeExList">clearBreaks </span></p>
<span class="f_CodeExList">clearBreaks </span></p>


'''Note:'''<span id="arg1_arg2" class="hmanchor"></span><span class="f_ListNote"> For commands that have multiple arguments, use the numbered-argument function, </span><span class="f_Monospace">&amp;&amp;arg(</span>''n''<span class="f_Monospace">)</span><span class="f_ListNote">, to distinguish the arguments. For example: </span>
'''Note:'''<span id="arg1_arg2" class="hmanchor"></span><span class="f_ListNote"> For commands that have multiple arguments, use the numbered-argument function, </span><span class="f_Monospace">&amp;&amp;arg(</span>''n''), to distinguish the arguments.  
===== Multiple argument example =====
<p class="syntax">traceUntilVariableEqualsValue &amp;&amp;arg(1) &amp;&amp;arg(2) </p>


<span class="f_CodeExList3">traceUntilVariableEqualsValue</span><span class="f_DefListDDTable"> </span><span class="f_CodeExList3">&amp;&amp;</span><span class="f_Monospace">arg</span><span class="f_CodeExList3">(1) &amp;&amp;</span><span class="f_Monospace">arg</span><span class="f_CodeExList3">(2) </span>
: 2. Provide the actual argument value before or as you run the macro.  
 
:: <span class="f_ListNum1">This depends on how you invoke the macro: </span>
2. Provide the actual argument value before or as you run the macro.  
 
<span class="f_ListNum1">This depends on how you invoke the macro: </span>


*<span class="f_ListBul2">If you use the </span><span class="term">Run Macro</span><span class="f_Para"> </span><span class="f_ListBul2">option of the </span><span class="term">Macros</span><span class="f_ListBul2"> menu, the contents of the [[Entity name input box|Entity name text box]]  replace instances of</span><span class="f_ListBul3"> </span><span class="f_Monospace">&amp;argstring</span><span class="f_ListBul2"> in the commands in the macro. </span>
*<span class="f_ListBul2">If you use the </span><span class="term">Run Macro</span><span class="f_Para"> </span><span class="f_ListBul2">option of the </span><span class="term">Macros</span><span class="f_ListBul2"> menu, the contents of the [[Entity name input box|Entity name text box]]  replace instances of</span><span class="f_ListBul3"> </span><span class="f_Monospace">&amp;argstring</span><span class="f_ListBul2"> in the commands in the macro. </span>
Line 32: Line 31:
*<span class="f_ListBul3">If the </span><span class="f_Monospace">macro</span><span class="f_ListBul3"> command has an argument (after the name of the macro), that argument replaces </span><span class="f_Monospace">&amp;argstring</span><span class="f_ListBul3"> in the macro. For example, if this is the mapping: </span>
*<span class="f_ListBul3">If the </span><span class="f_Monospace">macro</span><span class="f_ListBul3"> command has an argument (after the name of the macro), that argument replaces </span><span class="f_Monospace">&amp;argstring</span><span class="f_ListBul3"> in the macro. For example, if this is the mapping: </span>


<span class="f_CodeExList3">&lt;mapping command=&quot;macro stooge moe&quot; key=&quot;f2&quot; /&gt; </span>
<p class="syntax">&lt;mapping command=&quot;macro stooge moe&quot; key=&quot;f2&quot; /&gt; </p>


<span class="f_ListContinue3">Pressing the F2 key invokes the </span><span class="f_Monospace">stooge</span><span class="f_ListContinue3"> macro with </span><span class="f_Monospace">moe</span><span class="f_ListContinue3"> as the replacement argument for instances of </span><span class="f_Monospace">&amp;argstring.</span><span class="f_ListContinue3"> </span>
<span class="f_ListContinue3">Pressing the F2 key invokes the </span><span class="f_Monospace">stooge</span><span class="f_ListContinue3"> macro with </span><span class="f_Monospace">moe</span><span class="f_ListContinue3"> as the replacement argument for instances of </span><span class="f_Monospace">&amp;argstring.</span><span class="f_ListContinue3"> </span>
Line 70: Line 69:
<span class="f_Para">You can use the </span><span class="f_Monospace">&amp;&amp;prompt</span><span class="f_Para"> function wherever an argument to a command may appear, as shown in the following example: </span>
<span class="f_Para">You can use the </span><span class="f_Monospace">&amp;&amp;prompt</span><span class="f_Para"> function wherever an argument to a command may appear, as shown in the following example: </span>


<p class"syntax">traceUntilVariableEqualsValue &amp;&amp;prompt('var') &amp;&amp;prompt(&quot;val&quot;) </p>
<p class="syntax">traceUntilVariableEqualsValue &amp;&amp;prompt('var') &amp;&amp;prompt(&quot;val&quot;) </p>


<span class="f_Para">When this command executes, it produces two consecutive prompts, one for each of the command arguments.  </span>
<span class="f_Para">When this command executes, it produces two consecutive prompts, one for each of the command arguments.  </span>
[[Category:Debugger Home]]
[[Category:Debugger Home]]

Latest revision as of 17:53, 9 March 2023

As described in Creating and running a macro, many commands require arguments when used within a macro. You can use either a standard macro variable or a standard Client function to pass an argument to a command at the time the macro runs.

Using the &argstring variable

To use the &argstring variable to pass an argument to a command in a macro:

1. In the macro, specify&argstring where you would normally specify the command argument.
For example, note the use of &argstring in the breaksAt command in the following macro:

# Run till line that matches the user-passed string  top  clearBreaks   breaksAt &argstring  run  clearBreaks 

Note: For commands that have multiple arguments, use the numbered-argument function, &&arg(n), to distinguish the arguments.

Multiple argument example

traceUntilVariableEqualsValue &&arg(1) &&arg(2) 

2. Provide the actual argument value before or as you run the macro.
This depends on how you invoke the macro:
  • If you use the Run Macro option of the Macros menu, the contents of the Entity name text box  replace instances of &argstring in the commands in the macro.
  • If you use the Command Line option of the Macros menu, you explicitly specify in the command line tool the replacement for &argstring.
  • If you use an associated button or key, the &argstring replacement depends on whether the macro command in the mapping in the ui.xml file is specified with or without arguments:
  • If the macro command has an argument (after the name of the macro), that argument replaces &argstring in the macro. For example, if this is the mapping:

<mapping command="macro stooge moe" key="f2" /> 

Pressing the F2 key invokes the stooge macro with moe as the replacement argument for instances of &argstring.

  • If the macro command is specified without an argument, the contents of the Entity name text box replace &argstring.

Using the &&prompt function

The &&prompt function causes a macro to:

  1. Pause, to accept a user supplied argument value for a command that is specified within the macro
  2. Continue, to execute the command with the supplied value

The format of the &&prompt function is:

&&prompt(prompt

where prompt is either:

  • A single- or double-quoted character string with 80 or fewer characters.

As an example, the following macro clears all breaks in the current source code, prompts for the string it will use as the argument for the breaksAt command, then executes the code from its current position until it reaches a line that contains the user-supplied string, after which it clears the break:  

# Run till first line that has the string entered at the prompt  top  clearBreaks  breaksAt &&prompt("Enter the string at which to break:") run  clearBreaks 

When the macro command that contains &&prompt executes, the Client displays a Macro prompt dialog box like the following, which shows the prompt string from the preceding example macro:

macroPrompt

You can use the &&prompt function wherever an argument to a command may appear, as shown in the following example:

traceUntilVariableEqualsValue &&prompt('var') &&prompt("val") 

When this command executes, it produces two consecutive prompts, one for each of the command arguments.