General Purpose Utilities       

 c2html - Auto-documentation tool for models and general C-code.
	Use as:	  c2html  file.c
	Or,	  c2html  file1.c file2.c 
	Or even,  c2html  *.c
	etc..   It will produce HTML files that can be viewed from
	any web-browser.  They document C-programs by creating
	a hyper-text-linked alphabetic subroutine index, 
	calling-tree, and code listing.
  
 diff_dir - The utility compares whole directory branches looking for 
	differing files.  It helps find modified files in otherwise
	similar directories.  (Companion to Compare_dir which finds common 
	files between two specific directories; not branches.)
	This program compares the listings of two directory branches, 
	starting with two directories specified on the command line.  
	Use as:
		diff_dir  dir_A  dir_B
	It must be used with two directories on the command-line.
	It lists files that differ under them, by looking primarily at the
	file:  names, dates and sizes.
	Options:
	   -full    - Compares actual contents of files that otherwise
		      appear identical by name, size, and date.
	   -check   - Compare file contents only when dates differ but sizes match.
	   -date    - Makes diff_dir insensitive to file dates.  
		      Different dates alone will not be sufficient to
		      declare a file different with this option.
	   -size    - Makes diff_dir insensitive to differences in the
		      file sizes.  This is useful to merely check that
		      files of the same name exist in the two branches.
	   -ignore xx  - Causes diff_dir to ignore any files containing
		      the string xx.
		      Example:   -ignore .bak
	   -ignore_dir xx  - Causes diff_dir to ignore any directory 
		      branches whose directory name contains string xx.
		      Example:   -ignore_dir CVS
	   -ignore_case - Ignore differences in case of file names.
	   -ignore_gz   - Ignores size if only one of file pair is compressed.
	   -tkdiff  - Calls tkdiff on files that have differences.
		      Enables automatic examination of differing files.
	   -tkdiff-ask - For each file that differs, asks whether
		      to call tkdiff.  Useful to avoid looking at
		      differences in binary files, such as images or 
		      executable files.  At any time at the y/n prompt,
		      you may type "q" to quit.
	   -diff    - Asks to run diff on files with differences.
	   -copyover - For each differing file, asks whether to copy one
		      file over to the other to resolve differences.
		      Answering "y" copies the first file over to the
		      second directory.  Answering "r", does the reverse,
		      copying the second file to the first directory.
		      And answering "n" does nothing.  In each case, it
		      shows the command to be applied, if any.
		      At any time in an "ask" mode during a y/r/n prompt,
		      you may type "q" to quit.
	   -copyover_newer - Copies only newer mismatching files without asking.
	   -copyover_all - Copies all mismatching files without asking, from
			first to second directory.
	   -single  - Forces non-recursive operation.  It compares
		      only the files within each of the two directories
		      given, and will not descend into subdirectories
		      with this option.
	   -filter xx - Looks only at files having 'xx' in their name.
	   -only xx   - Same as '-filter' above.
	   -asym         - Shows only files newer in the first directory.
	   -existingonly - Compares only files existing in both directories.
	   -subset1      - Compares files existing in first directory only.
	   -subset2      - Compares files existing in second directory only.
	   -showmatch_only - Causes diff_dir to display only files that
		      appear identical in the two directory branches.
		      Does not display differing files.  In other words,
		      it inverts the operation of diff_dir.
	   -help    - Shows these and more options.
	Options can be combined in any order.  For example, by combining 
	-tkdiff-ask with -copyover, you may visually examine differences with
	tkdiff, before deciding to copy a file from one directory to the other.

 compare_dir - The utility compares two directories file-by-file.
	It is analogous to the standard "diff" and "cmp" utilities,
	which compare the contents of individual files, but compare_dir
	operates on the contents of file-directories.  It provides
	several summaries listing the files which are in common between
	the two directories, files contained in one but not the other,
	files of the same name but newer version dates, etc..
	(It is similar to the "dircmp" function, but less cryptic and 
	 more useful.)  By default, compare_dir operates by comparing 
	directory listing information only, which consists of the file 
	names, sizes, and dates.  It does not look at the actual file 
	contents, unless the -full option is invoked.
	Compare_dir is especially useful for consolidating or updating
	directories which have been copied and perhaps deviated over time.

 disk_usage - Shows disk-space used for major directory branches.
	Lets you limit the depth of branches to display down to (-levels).
	Accounts for all space below truncation level, and shows space
	exactly once.  Lets you screen-out branches smaller than a given 
	KB amount (-screen).  Displays in clear convenient KB units.
	By default, disk_usage shows down-to 3 levels.
	Use as:	
		disk_usage -levels 2 directory_xx
		disk_usage -screen 1000 -levels 3 directory_xx

 draw_tree - This utility draws the directory tree, or branches,
	under a specified starting directory.  It draws it to the
	screen at the same time it saves the tree to a file called,
	"tree.".  It draws the tree in ascii-text in an 80-column
	format that can be conveniently printed to any printer, or
	viewed from any screen.  To use it, type for example:
		draw_tree  your_directory
	It will show the tree of directories below "your_directory",
	with each directory's file-space.  Use dot (.) to specify your
        current directory.   This tool is especially useful when it is
	time to clean-up your file system, for finding what directories
	are consuming the majority of space.  -- Options enable showing 
	the owner and date (most recent file) for each directory, by
	the command-line options:  -owner and -date.  The most
	important option is for limiting the number of levels expanded:
	-levels xx.  Use as:
		draw_tree  -levels 3  your_directory
	This will show down-to only n (three) levels, but will sum
	the space used below those levels to the lowest level shown.
	Draw_tree provides a total roll-up of all space under the
	specified directory branch.
	
 filter - A general purpose file-filtering utility.  It does global 
	search and replaces on files of any size.
	It expects the source file to be the first file on the 
	command-line.  If no files are specified, on the command-line, 
	it will prompt you.  By default, if no destination file name 
	is specified, it will write the filtered output to a file of
	the same root-name as the source, but with ".new" suffix.
	If you wish to write the file to a specific name, then specify 
	that name as the second command-line argument.
	Filter correctly handles replacing a file by itself.
	(It automatically uses a temporary file.)
	You may specify the search and/or replacement string(s) on
	the command line also by prefacing them with the "-s" or
	"-r" command-line options respectively.  If you do not supply
	them, filter will prompt you for them.
	Example-1:
	        filter file1 -s was -r is
	This would create "file1.new".
	Example-2:
	        filter file1 file1 -s was -r is 
	This replaces "file1" with it's filtered version.
	Using the "-v" verbose option will show the replacement 
	lines as they occur (after replacement).  Filter always
	provides a summary of the number of replacements made.
	To search and/or substitute arbitrary ASCII characters, use
	the %xxx special escape, where xxx is the decimal value.
	For example, you must specify % character as %037.
	Carriage-return is %010.

 line_diff - This utility produces a line-by-line difference between
	two files.  It is similar to the standard "diff" utility,
	except that instead of presenting file-differences as large
	blocks of differences, it displays the differences line-by-line
	for easy visual comparison.  It is most useful when two data
	files stay in line-sync, but you want to see the comparative
	differences between the individual lines which differ.
	Use as:
		line_diff  file1  file2   |  more 

 nesting_list - This utility produces an annotated listing of C-code
	programs.  The listing is annotated on the left side by the
	nesting level of each line of code, as defined by the bracket
	"{" and "}" block structure.  
	Use as:
		nesting_list  your_program.c
	By default, nesting_list always produces the annotated listing
	to a file called "your_program.lis".  It does not affect your
	source files in any way.  This utility is often helpful for
	finding missing or extra brackets in code.  (The bracket-level
	between subroutines should always be zero, if all brackets are
	balanced.) 

 simdiff - SimDiff compares two CSIM xml-diagram files, and shows any logical
	differences between them.  Ignores diagram positioning (geometry vertices).
	Logical differences include:
		- Box names, types, or attributes differ,
		- Port names or link-attributes differ differ,
		- Connections differ (topology differs).
		- Global attributes (macros/variables) differ.
	Examples of the topology differences include:  Boxes having differing
	number of connections, or that connect to different boxes than they
	do in the other diagram-set.

	SimDiff is meant to be used to compare two versions of a given diagram
	file that are expected to correspond closely, but perhaps not exactly.
	This situation occurs frequently in projects in which experimental variants
	are sometimes created or evolve.  SimDiff is helpful in determining what
	the relevant differences are.  Being a logical-compare, it is insensitive
	to differences in order, sequence, formatting, geometry, or positioning.

	SimDiff contains extra checks of consistency for each input file. 
	The regular CSIM tools, like the GUI and preprocessor have some integrity
	checks, but expect input files that are reasonably well-formed, assuming
	they are generated by the CSIM tool-set.  However, SimDiff contains extra
	checks that are useful when debugging diagram-files translated from foreign
	sources.  Some of these checks are more time-consuming and would not
	normally be necessary for files generated by the CSIM-GUI, but can be
	useful in catching errors from other sources or translators.  These extra
	checks are not detrimental in any case.  Checks are made for duplicate
	modules, boxes, links, and attributes.  Simdiff can be use to validate
	the contents of a single diagram file by using the -checkonly option.

	Usage:
	        simdiff  diagram1.sim  diagram2.sim

	        simdiff  -checkonly diagram1.sim

	Note that the input file(s) are expected to be the top-level file, which
	may %include other files.  SimDiff will expand and compare all included
	files in a given diagram-set.  Included files will often be in separate
	directory branches but otherwise have the same names.  SimDiff reports
	differences relative to the top-level file and module name.

	Options:
	        -v               - Increase diagnostic messages.
	        -suppress_links  - Do not report link differences.
		-checkonly	 - Single-file validation check for redundant 
				   objects, etc., ...

	On files with differing boxes, there will also be many reports of their
	connecting links which do not match.  It is often useful to suppress the
	link-mismatch reports until the box-differences are resolved.  Therefore, 
	the -suppress_links option helps de-clutter the output.

	If there are any differences between diagram-sets, SimDiff will report on
	each one.  It will then report on any inconsistencies within the individual
	files.  Finally, it will always produce a summary of the number of
	differences, and objects examined.  If there are no logical differences,
	SimDiff will report: "0 Differences".  It always shows the number of modules, 
	boxes, links, and attributes examined.



calc - Command-line calculator.  How many times have you
	needed to perform some calculations on numbers displayed on your
	screen, and either did not have a calculator handy, or found re-typing
	all the numbers into a hand-held or  calc-app too tedious ?

	The Command-line calculator utility within CSIM lets you interactively
	perform calculations on numbers you copy&paste from simulation
	outputs, other documents and presentations, or simply type in.  Since
	it is a command-line tool, you get the full power of command-line
	editing/deleting, etc..   You also get to see a  running log of your
	calculations, and you can re-edit or cut&paste parts of previous
	expressions into new expressions, other tools, or into reports or
	presentations.

	Calc can perform complicated expressions with multiple levels of
	parenthesis. You can use variables and macros.  Normal operation
	precedence is honored.  For example, 3 + 2 * 8 = 3 + 16 = 19; not 5 * 8
	= 40, as on some simple calculators. Calc is based on the same
	recursive descent parser used within CSIM's attribute value evaluator.
	So Calc can also be used to test model attribute expression evaluation.

	Calc enables you to use meaningful variable names, unlike spread-sheets
	which force you to use awkward cell coordinates.  All the functions
	documented under CSIM's  attribute evaluator are
	available.


	Usage: 	(User input is in black. Program output is in blue.)
		calc
		  Calc v2.0:    (Enter expressions.  Quit with 'q'.)

		  34.8 * SIN( 0.22 ) + (85 * SQRT( 29 - 7.3 ))

		  Answer = 403.552091

		  A = B * 39.0
		  B = 22

		  A + 6 * B

		  Answer = 990.0

		  A

		  Answer = 858.0

		  B = 100

		  A

		  Answer = 3900.0

		  A + 6 * B

		  Answer = 4500.0

		  q


 findall - Findall is a utility in CSIM's general_utilities directory 
	for quickly finding files in directory branches, based on a large variety
	of rules, such as date-ranges, file-types, name substrings, content
	search-words, and to see rankings based on date or file sizes.  For
	example, it can quickly find the newest or largest files in deep
	directory branches.  Findall is operating-system independent, so it
	provides the same capability to every computer.

	   Below is the list of findall command-line options:

		FindAll version 1.0 - 
		   -since       - Supply month day year  
				   (month day year, or month/day/yr, or month-day-year).
		   -before      - Supply month day year.
		   -log         - Save results to 'findall.log' file too.
		   -case        - Be case-sensitive.  Default is case insensitive.
		   -recent      - Finds the 10 most recent files, and ranks them by age.
		   -newest x    - Find the x most recent files, and rank them by age.
		   -biggest x   - Find the x largest files, and rank them by size.
		   -nlevels x   - Restricts search down to only x directory levels.
		   -single      - Look at single level, do not descend.
		   -search xx   - Look for occurance of words {xx} in files, 
					like grep, but shows file name; not lines.
		   -search_nocase xx - Like 'search', but case insensitive matching.
		   -cleanse     - Removes files matching search.
		   -cleanse-ask - Asks first, before removing each file matching search.
		   -ignore xx   - Ignore any files or directories containing the 
					string(s) { xx }.
		   -dirsonly    - Find directories, not files.
		   -dirs2       - Find files and directories too.
		   -ni          - Not interactive.  Does not prompt for questions.
		   -orword xx   - Accepts { xx } as "or" word(s), and does not prompt.
		   -andword xx  - Accepts { xx } as "and" word(s), and does not prompt.
		   -notword xx  - Accepts { xx } as "not" word(s), and does not prompt.
		   -nodotfiles  - Ignores files or directories beginning with (.) dot.
					(-ignore_dot_anthing)
		   -apply xx    - Apply command xx to each file found. 
					Example: -apply dos2unix 
		   -quiet       - Do not print 'could not open' messages.
					(Usually occurs on broken sym-links.)
		   -v           - Verbose
		   -h           - Print this list of options and version.
	

	    Example usages:
		findall -ni -recent

		findall -ni -since Jul 20 2018 -after Mar 3 2018  dir1  dir2  dir3

		findall -or .doc  

		findall -or { .doc .ppt .odp }  dir1 dir2

		findall -and .txt -apply more

		findall -biggest 40 dir1 dir2 dir3

		findall -or { .txt .doc } -not { project_y project_x }