path: root/doc/README.DGAWK

INVOKING:

	Invoking dgawk is similar to gawk. Run dgawk with all options and arguments as
you would supply to gawk. Command line scripts can not be debugged using dgawk.
dgawk expects at least one program text included via the -f option. If you include
programs using the --source option, dgawk will not stop at instructions originating
from that source. 

USAGE:

	$> dgawk -f foo.awk
	dgawk> list
	...
	dgawk> break 5
	...
	dgawk> run
	...
	dgawk> next
	...
	dgawk> continue
	...
	dgawk> quit


COMMANDS:

	* help [command]
		prints a list of all commands and short descriptions.
		'help command' prints the information about command 'command'. 

	* info source|sources|variables|functions|break|frame|args|locals|display|watch
		* source
			name of the current source file. Each time the program stops, the
			current source file is the file containing the current instruction.
			When dgawk first starts, the current source file is the first file
			included via the -f option. The 'list filename:lineno' command can
			be used at any time to change the current source.
		* sources
			list all program sources.
		* variables
			list all global variables.
		* functions
			list all function definitions including source file names and
			line numbers.
		* break
			list all currently set breakpoints.
		* frame
			description of the selected stack frame.
		* args
			arguments of the selected frame.
		* locals
			local variables of the selected frame.
		* display
			list of all items in the automatic display list.
		* watch
			list of all items in the watch list.

	* list [-|+|n|filename:n|m-n|function]
		prints specified lines (default 15) from the current source file
		or file named 'filename'.
			-			print lines before the lines last printed. 	 
			+			print lines after the lines last printed.
						list without any argument does the same thing.
			n			print lines centered around line number 'n'.
			m-n			print lines from 'm' to 'n'.
			filename:n	print lines centered around line number 'n' in
						source file 'filename'. May change current source file.
			function	print lines centered around beginning of the
						function 'function'. May change current source file.

	* break [[filename:]n|function]
		Without any argument, sets a breakpoint at the next instruction
		to be executed in the selected stack frame.
			n			set a breakpoint at line number 'n' in the current
						source file.
			filename:n	set a breakpoint at line number 'n' in source file
						'filename'.
			function	set a breakpoint at entry to function (first instruction)
						'function'.

	* tbreak [[filename:]n|function]
		set a temporary breakpoint (enabled for only one stop).

	* disable [n1 n2 ...] [m-n]
		disable specified breakpoints or a range of breakpoints. Without
		any argument, disables all breakpoints.

	* enable [once|del] [n1 n2 ...] [m-n]
		enable specified breakpoints or a range of breakpoints. Without
		any argument, enables all breakpoints.
			once		enable breakpoint(s) temporarily, then disable it when
						the program stops at the breakpoint.
			del			enable breakpoint(s) tempoarily, then delete it when
						the program stops at the breakpoint.

	* delete [n1 n2 ...] [m-n]
		delete specified breakpoints or a range of breakpoints. Deletes
		all defined breakpoints if no argument is supplied.

	* clear [[filename:]n|function]
		without any argument, deletes any breakpoint at the next instruction
		to be executed in the selected stack frame. If the program stops at
		a breakpoint, this will delete that breakpoint so that the program
		does not stop at that location again.
			n			delete breakpoint(s) set at line number 'n' in current
						source file.
			filename:n	delete breakpoint(s) set at line number 'n' in source
						file 'filename'.
			function	delete breakpoint(s) set at entry to function 'function'.

	* ignore N COUNT
		ignore breakpoint N COUNT times before stopping.

	* run
		starts/restarts execution of the program. When restarting, dgawk retains
		current breakpoints, watchpoints, command history, automatic display
		variables and debugger options.

	* frame [N]
		select and print (frame number, function and argument names, source file,
		and the source line) stack frame N. Frame 0 is the currently executing
		or innermost frame (function call), frame 1 is the frame that called the
		innermost one. The highest numbered frame is the one for 'main'.

	* up [COUNT]
		move COUNT (default 1) frames up the stack toward the outermost frame.
		selects and prints the frame.

	* down [COUNT]
		move COUNT (default 1) frames down the stack toward the innermost frame.
		selects and prints the frame.

	* backtrace [COUNT]
		print backtrace of all function calls (stack frames), or innermost COUNT
		frames if COUNT > 0. Prints outermost -COUNT frames for COUNT < 0.
		Displays name and arguments to each function, source filename and line number.

	* continue [COUNT]
		resume program execution. If continued from a breakpoint and COUNT is
		specified, ignores the breakpoint at that location next COUNT times before
		stopping.
 		
	* step [COUNT]
		continue execution until control reaches a different source line in the
		current stack frame. Step steps inside any function called within the line.
		If the argument COUNT is supplied, steps that many times before stopping,
		unless it encounters a breakpoint (or watchpoint).

	* next [COUNT]
		continue execution to the next source line, stepping over function calls.
		The argument COUNT controls how many times to repeat the action as
		in step.
		
	* stepi [COUNT]
		execute one (or COUNT) instruction(s), stepping inside function calls.

	* nexti [COUNT]
		execute one (or COUNT) instruction(s), stepping over function calls.

	* finish
		execute program until the selected stack frame returns.
		Prints the returned value.

	* return [value]
		cancel execution of a function call. If 'value' (either string or number)
		is specified, it is used as the function's return value. If used in a
		frame other than the the innermost one (currently executing function i.e.
		frame number 0), discards all outer frames in addition to the selected one,
		and the caller of that frame becomes the innermost frame.

	* until [[filename:]n|function]
		without any argument, continues execution until a line past the current
		line in current stack frame is reached. With argument,
		continues execution until the specified location is reached, or the current
		stack frame returns.

	* print var1[,|\s|\t var2 ...]
		print the value of a gawk variable or field. Fields must be referenced by
		constants:
			dgawk> print $3
		prints the third field in the input record (if the specified field does not
		exist, it will print 'Null field'). Variable can be an array element, with
		the subscripts being constant values. To print the contents of an array,
		prefix the name of the array with the '@' symbol:
			gawk> print @a
		prints the index and the corresponding value for all elements in array 'a'.

	* printf format, [arg], ...
    	print formatted text. May include escape sequences, such as `\n'.
		No newline is printed unless specified one.

	* set var=value
		assign a constant (number or string) value to a gawk variable or field.
		String values must be enclosed between double quotes(").

	* display [var|$n]
		add variable 'var' (or field $n) to the automatic display list. The
		value of the variable or field is displayed each time the program stops.
		Each variable added to the list is identified by a unique number:
			dgawk> display x
			10: x = 1
		displays the assigned item number, the variable name and its current value.
		If the display variable refers to a function parameter, it is silently
		deleted from the list as soon as the execution reaches a context where
		no such	variable of the given name exists.
		Without argument, displays the current values of items on the list.

	* undisplay [N]
		remove item number N (or all items) from the automatic display list.

	* watch var|$n
		add variable 'var' (or field $n) to the watch list. dgawk will stop whenever
		the value of the variable or field changes. Each watched item is assigned a
		number which can be used to delete it from the watch list using the
		unwatch command.

	* unwatch [N]
		remove item number N (or all items) from the watch list.

	* option [name[=value]]
		without argument, displays the available debugger options
		and their current values. 'option name' shows the current
		value of the named option. 'option name=value' assigns
		a new value to the named option.
		Available options:
		* listsize
			the number of lines that list prints. The default is 15.
		* prompt
			debugger prompt. The default is "dgawk> ".
		* trace [on|off]
			turns instruction tracing on or off. The default is off.
		* outfile
			sends gawk output to a file; debugger output still goes
			to stdout. An empty string ("") resets output to stdout.
		* save_history [on|off]
			save command history to file ./.dgawk_history. The default is 'on'.
		* history_size
			maximum no of lines to keep in history file ./.dgawk_history.
			The default is 100.
		* save_options [on|off]
			save current options to file ./.dgawkrc on quit. The default is 'on'.
			Options are read back in next session on startup.

	* commands [N]
	* silent
	* end
		'commands' sets list of commands to be executed when stopped at
		a breakpoint or	watchpoint. N is the breakpoint or watchpoint number.
		Without a number, refers to the last one set. The actual commands follow
		starting on the next line and are terminated by the 'end' command.
		If the command 'silent' is in the list, the usual messages about stopping
		at a breakpoint and the sourceline are not printed. Any command
		in the list that resumes execution (e.g. continue) terminates the list
		(an implicit end), and subsequent commands are ignored.
  			
			dgawk> commands
			> silent
			> printf "A silent breakpoint; i = %d\n", i
			> info locals
			> set i = 10
			> continue
			> end
			dgawk>

	* source filename
		run command(s) from a file; an error in any command does not
		terminate execution of subsequent commands. Comments (lines starting
		with #) are allowed in a command file. Empty lines are ignored, does not
		repeat last command. Can't restart program by having more than one run
		command in the file.
		Can also use the '-R file' OR '--command=file' command line option to
		execute commands from a file non-interactively.  

	* save filename
		saves the commands from the current session to the given filename,
		so it can be replayed using the source command.

	* quit
		quit debugger.

 
READLINE SUPPORT:

	If compiled with readline library, you can take advantage of its command
completion and history expansion feature. The following types of completion
are available:
		* command completion
			command names.
		* source filename completion
			source file names. Relevant commands are list, break, tbreak, until,
			and clear. 
		* argument completion
			non-number arguments to a command. Relevant commands are info and enable.
		* variable name completion
			global variable names, and function arguments in the current context
			if the program is running. Relevant commands are print, set, watch,
			and display.

REFERENCES:

	* Debugging with GDB, the manual for the GNU Source-Level Debugger.
	Much of the contents of this README shamelessly stolen and adapted from it.
	* GNU Readline User's Manual
	* GNU History User's Manual