Command Reference2. FPGA Express Shell Commands history _N_A_M_E history Displays or modifies the commands recorded in the history list. SYNTAX string history [-h] [-r] [args...] string _a_r_g_s ARGUMENTS -h Displays the history list without the leading numbers. You can use this for creating scripts from existing history. You can then sourse the script with the source command. You only can combine this option with a single numeric argument. Note that this option is a non-standard extension to Tcl. -r Reverses the order of output so that most recent history entries display first rather than the oldest entries first. You only can combine this option with a single numeric argument. Note that this option is a non-standard extension to Tcl. _a_r_g_s Additional arguments to history (see DESCRIPTION). DESCRIPTION The history command performs one of several operations related to recently-executed commands recorded in a history list. Each of these recorded commands is referred to as an ``event''. The most commonly used forms of the command follow. You can combine each with either the -h or -r option, but not both. +o With no arguments, the history command returns a formatted string (intended for you to read) giving the event number and contents for each of the events in the history list. +o If a single, integer argument _c_o_u_n_t is specified, only the most recent _c_o_u_n_t events are returned. Note that this option is a non-standard extension to Tcl. v3.0 Synopsys Inc. 1988-1998. All rights reserved. 2-1 history 2. FPGA Express Shell Commands Command Reference +o Initially, 20 events are retained in the history list. You can change the length of the history list using the following: history keep _c_o_u_n_t Tcl supports several additional forms of the history command. See the following ADVANCED TCL HISTORY section. 2-2 Synopsys Inc. 1988-1998. All rights reserved. v3.0 Command Reference2. FPGA Express Shell Commands history EXAMPLES The following examples show the basic forms of the history command. First, you can limit the number of events shown using a single numeric argument. prompt> history 3 7 set base_name "my_file" 8 set fname [format "%s.db" $base_name] 9 history 3 Using the -r option creates the history listing in reverse order. prompt> history -r 3 9 history -r 3 8 set fname [format "%s.db" $base_name] 7 set base_name "my_file" Using the -h option removes the leading numbers from each history line. prompt> history -h 3 set base_name "my_file" set fname [format "%s.db" $base_name] history -h 3 ADVANCED TCL HISTORY The history command has many advanced features. Recently-executed commands record in a history list. Each of these recorded commands is referred to as an ``event''. When specifying an event to the history command, you can use the following forms: +o A number: If positive, it refers to the event with that number (all events are numbered starting at 1). If the number is negative, it selects an event relative to the current event (-1 refers to the previous event, -2 to the one before that, and so on). +o A string: Selects the most recent event that matches the string. An event matches the string either if the string is the same as the first characters of the event or if the string matches the event in the sense of the string match command. v3.0 Synopsys Inc. 1988-1998. All rights reserved. 2-3 history 2. FPGA Express Shell Commands Command Reference The history command can take any of the following forms: history Same as history info, described later. history add _c_o_m_m_a_n_d ?_e_x_e_c? Adds the _c_o_m_m_a_n_d argument to the history list as a new event. If you specify (or abbreviate) exec, the command also executes and its result is returned. If you do not specify exec, an empty string returns as result. history change _n_e_w_V_a_l_u_e ?_e_v_e_n_t? Replaces the value recorded for an event with _n_e_w_V_a_l_u_e. _E_v_e_n_t specifies the event to replace and defaults to the _c_u_r_r_e_n_t event (not event -1). This intention of this command is for your use with commands that implement new forms of history substitution and you want to replace the current event (which invokes the substitution) with the command created through substitution. The return value is an empty string. history event ?_e_v_e_n_t? Returns the value of the event given by _e_v_e_n_t. _E_v_e_n_t defaults to -1. This command causes history revision to occur. See the following HISTORY REVISION section for details. history info ?_c_o_u_n_t? Returns a formatted string (intended for you to read) giving the event number and contents for each of the events in the history list except the current event. If you specify _c_o_u_n_t, only the most recent _c_o_u_n_t events are returned. history keep _c_o_u_n_t You can use this command to change the size of the history list to _c_o_u_n_t events. Initially, 20 events are retained in the history list. This command returns an empty string. history nextid Returns the number of the next event to record in the history list. Use this for things like printing the 2-4 Synopsys Inc. 1988-1998. All rights reserved. v3.0 Command Reference2. FPGA Express Shell Commands history event number in command-line prompts. history redo ?_e_v_e_n_t? Re-executes the command indicated by _e_v_e_n_t and return its result. _E_v_e_n_t defaults to -1. This command results in history revision. See HISTORY REVISION for details. history substitute _o_l_d _n_e_w ?_e_v_e_n_t? Retrieves the command given by _e_v_e_n_t (-1 by default), replaces any occurrences of _o_l_d by _n_e_w in the command (only simple character equality is supported; no wild cards), execute the resulting command, and return the result of that execution. This command results in history revision. See HISTORY REVISION for details. history words _s_e_l_e_c_t_o_r ?_e_v_e_n_t? Retrieves from the command given by _e_v_e_n_t (-1 by default) the words given by _s_e_l_e_c_t_o_r, and returns those words in a string separated by spaces. The selector argument has three forms. If it is a single number, it selects the word given by that number (0 for the command name, 1 for its first argument, and so on). If it consists of two numbers separated by a dash, it selects all the arguments between those two. Otherwise selector is treated as a pattern; all words matching that pattern (in the sense of string match) are returned. In the numeric forms you can use $ to select the last word of a command. For example, suppose the most recent command in the history list is format {%s is %d years old} Alice [expr $ageInMonths/12] The following are some history commands and the results they would produce. history words $ [expr $ageInMonths/12] history words 1-2 {%s is %d years old} Alice history words *a*o* {%s is %d years old} [expr $ageInMonths/12] History words results in history revision. See the following for details. HISTORY REVISION The history options event, redo, substitute, and words result in ``history revision''. When you invoke one of these options, the current event is modified to v3.0 Synopsys Inc. 1988-1998. All rights reserved. 2-5 history 2. FPGA Express Shell Commands Command Reference eliminate the history command and replaced with the result of the history command. For example, suppose that the most recent command in the history list is set a [expr $b+2] and that the next command invoked is one from the left side of the following table. The command actually recorded in the history event is the corresponding one on the right side of the table. history redo set a [expr $b+2] history s a b set b [expr $b+2] set c [history w 2] set c [expr $b+2] History revision is needed because event specifiers like -1 are only valid at a particular time; once more events are added to the history list, a different event specifier is needed. History revision occurs even when you invoke history indirectly from the current event (such as, you type a command that invokes a Tcl procedure that invokes history): the top-level command whose execution eventually results in a history command is replaced. If you want to invoke commands like history words without history revision, you can use history event to save the current history event then use history change to restore it later. SEE ALSO None. 2-6 Synopsys Inc. 1988-1998. All rights reserved. v3.0