// function AppendWaves(parentDF, DFpattern, killChildDFs, [sortedAppend, sortOptions, modelDF])
//
// 	Given a data folder parentDF that contains wave1, Vwave and w3, AppendWaves appends
//	waves with the same name (i.e. wave1, Vwave and w3) found in any child data folder of parentDF, 
//	if those childDFs match a name pattern DFpattern. If killChildDFs is true (non-zero), the childDFs 
//	from which data were appended are killed. The sequence in which data folders are cycled (and thus
//	data are appended) can be influenced by setting sortedAppend=1 and sortOptions (see help for
//	SortList). If parentDF is empty initially, a modelDF may be specified to determine which waves are
//	to be extracted by AppendWave.
//
//	- if parentDF is an empty string, AppendWaves uses the current data folder
//	- if DFpattern is an empty string, AppendWaves uses the match-all pattern "*"
//	- if killChildDFs is non-zero, AppendWaves will kill child data folders with "exploited" data
//	- if sortedAppend is non-zero, AppendWaves will sort the child data folders before appending
//	- if sortedAppend is non-zero, sortOptions as used by SortList may be specified
//	- if modelDF is specified, AppendWaves uses it to determine which waves should be appended
//	- if modelDF is not specified, AppendWaves uses the parentDF as a model instead
//
//	Thus, AppendWaves("", "", 0) called with "root:" as the current data folder tries to append to all 
// 	waves currently living in "root:"; it collects waves from all top-level data folders and then kills those 
//	data folders from which it collected waves. Use these "wildcards" with care...
//
//	The intended use is to load e.g. time series data spread over many files into separate folders called
//	"day1", "day2", etc. The folders can be put into a master folder called "alldays" so that we have a
//	folder structure like this:
//	>alldays
//	>>day1
//	>>--wave1 (0,1,2)
//	>>--wave2 (2,3,4)
//	>>day2
//	>>--wave1 (100, 101, 102)
//	>>--wave2 (202, 203, 204)
//	Now, call AppendWaves("alldays", "day*", 1) in order to collapse all runs into one:
//	>alldays
//	>--wave1 (0,1,2,100,101,102)
//	>--wave2 (2,3,4,202,203,204)
//
function AppendWaves(parentDF, DFpattern, killChildDFs, [sortedAppend, sortOptions, modelDF])
string parentDF, DFpattern
variable killChildDFs, sortedAppend, sortOptions
string modelDF
// get list of childDFs matching DFpattern
	if( strlen(parentDF) == 0 )
		parentDF = GetDataFolder(1)
	endif
	string childDFs = ListMatch( ChildDFList(parentDF), DFpattern+"*" )
	if( sortedAppend )		// default is 0 = false
		childDFs = SortList(childDFs, ";", sortOptions)	// default is 0 = ascending case-sensitive 
	endif											// alphabetic ASCII sort
	variable numChildren = ItemsInList(childDFs)		// count the "good" children
	if( numChildren == 0 )						// ...none -- abort
		Abort "AppendWave found no child data folders"
	endif
// build WList from waves in modelDF or in parentDF
	string WList, saveDF = GetDataFolder(1)
	if( !ParamIsDefault(modelDF) )	// use modelDF if specified
		SetDataFolder modelDF
		WList = WaveList("*", ";", "")
	else
		SetDataFolder parentDF	// default to parentDF
		WList = WaveList("*", ";", "")
	endif
	variable numWaves = ItemsInList(WList)		// count waves to append to
	if( numWaves == 0 )						// ...none -- abort
		Abort "AppendWave found no waves to append to in data folder \""+GetDataFolder(1)+"\""
	endif
 
	variable k, m, childDataAppended
	string childDF, currentWave, sourceWave, destWave
// cycle through childDFs
	for( k = 0; k < numChildren; k += 1 )
		childDF = StringFromList(k, childDFs)
		SetDataFolder childDF
		childDataAppended = 0	// don't want to kill childDFs that contained no data to append
// ... cycle through WList
		for( m = 0; m < numWaves; m += 1 )
			currentWave = StringFromList(m, WList)
			sourceWave = childDF+currentWave
			if( exists(sourceWave) == 1 )	// not all waves in child data folder may be relevant
				destWave = parentDF+currentWave
				if( exists(destWave) == 1 )	// parentDF may be empty initially
					Concatenate/NP sourceWave+";", $destWave
					print "C "+sourceWave+","+destWave
				else
					Duplicate $sourceWave, $destWave
					print "D "+sourceWave+","+destWave
				endif
				childDataAppended = 1
			endif
		endfor
		if( childDataAppended && killChildDFs )
			KillDataFolder childDF
		endif
	endfor
	SetDataFolder saveDF
end
 
// function/S ChildDFList(parentDF) 
// returns a list of full paths to child data folders of data folder specified by parentDF
//	* if parentDF is an empty string, ChildDFList uses the current data folder 
function/S ChildDFList(parentDF)
string parentDF
	if( strlen(parentDF) == 0 )
		parentDF = GetDataFolder(1)
	elseif( !DataFolderExists(parentDF) )
		Abort "ChildDFList cannot find specified data folder \""+parentDF+"\""
	endif
	parentDF = RemoveEnding(parentDF, ":") + ":"	// make sure parentDF ends in a colon
	variable k
	string CDFList = ""
	for( k = 0; k < CountObjects(parentDF,4); k += 1)
		CDFList += parentDF+GetIndexedObjName(parentDF, 4, k)+":;"
	endfor
	return CDFList
end