/*
Written by Afsheen Ghorashy
October 9, 2013

Last updated by Afsheen Ghorashy
Oktober 17, 2013

The functions in this module help simplify the process of cycling through 
the links of an object.

Note: Some of the functions below open modules (some many at a time).  In order to 
avert memory saturation and instability, check the notes accompanying each function 
to determine which ones open modules.  It might be wise to combine use of those functions 
with trackOpenModules.dxl to be able to close opened modules safely and conserve memory. 

swa a,
Afsheen

Use example (the alternate functions below are better because it is easier
close modules afterwards with them):

// Better because it is possible to close each module opened by 
// getOneIncomingLinkedObject(Object, int) without interfering 
// with the objects of other links...  Here trackOpenModules.dxl
// is used.  Though it adds no value here, in more complex link
// exploration programs, use of this module in this manner is essential!

// For performing a task on each object an object, o, links to.

	#include <lib/trackOpenModules.dxl>

	int k = 0
	for (k = 0; k >= 0; k++)
	{
		Object outObj = getOneOutgoingLinkedObject(o,k+1)
		if (null outObj) break
		addOpenModule(module(outObj))
		task(outObj)
		closeOpenModule(module(outObj))
	}
		
// For performing a task on each object an object, o, is linked to.

	int k = 0
	for (k = 0; k >= 0; k++)
	{
		Object inObj = getOneIncomingLinkedObject(o,k+1)
		if (null inObj) break
		addOpenModule(module(inObj))
		task(inObj)
		closeOpenModule(module(inObj))
	}

* The problem being that with the old funcitons, a whole bunch of modules
will be opened at the same time and so, if multiple calls to those functions
are being made in a staggered manner (because links are being explored 
recursively, for example) it becomes impossible to close any links without 
risking 

*/


// Potentially opens many modules per call
int getNumOfIncomingLinks(Object o)
{
	LinkRef lr
	Link l
	Object tobj
	ModName_ mn
	Module tg 
	int count = 0
		
	int ind = 0	
	
	for lr in all(o <- "*") do
	{
        mn = source lr
        string name1 = fullName(mn)
        if(!open mn) {tg = read(name1, false)}
	}
	for l in o <- "*" do 
	{
		count++
	}
	return count	
	
}


int getNumOfOutgoingLinks(Object o)
{
	Link l
	int count = 0;
	for l in o -> "*" do
	{
		count++
	}
	return count


}

// Opens at most 1 module per call
Object getOneIncomingLinkedObject(Object o, int rank)
{
	LinkRef lr
	Link l
	Object tobj
	ModName_ mn
	Module tg 

	int count = getNumOfIncomingLinks(o);

	if (rank <= count)
	{
		int ind = 0
		for lr in all(o <- "*") do
		{
			ind++
			if (rank == ind)
			{
				mn = source lr
				string name1 = fullName(mn)
				if(!open mn) {tg = read(name1, false)}
			}

		}
		ind = 0
		for l in o <- "*" do 
		{
			ind++
			if (rank == ind)
			{
				tobj = source l	

				return tobj
			}
			
		}
	}
	else
	{
		return null
	}

}

// Opens at most 1 module per call
Object getOneOutgoingLinkedObject(Object o, int rank)
{
	LinkRef lr
	Link l
	Object tobj
	ModName_ mn
	Module tg 

	int count = getNumOfOutgoingLinks(o);

	if (rank <= count)
	{
		int ind = 0
		for l in o -> "*" do 
		{
			ind++
			if (rank == ind)
			{
				mn = target l
				string name1 = fullName(mn)
				if(!open mn) {tg = read(name1, false)}				
				tobj = target l	
				return tobj
			}
			
		}

	}
	else
	{
		return null
	}

}