## p4add-groupspec
## aaron bockelie

<#
	.SYNOPSIS
	Returns a valid groupspec that can be fed into p4.exe
	.DESCRIPTION
	This function creates a valid perforce group spec given a minimum set of parameters.
	.EXAMPLE
	This is the minimum required parameters needed to create a group:
	[PS] p4add-groupspec -group groupname -users user.name
	Note that not supplying information for integer attributes will result in values of unset or zero, except for timeout which will default to 43200 seconds. Define the value timeout to override the default.
	.EXAMPLE
	This example adds multiple users to the group. Seperate usernames with a comma:
	[PS] p4add-groupspec -group groupname -users user.name,another.user,onemore.user
	.EXAMPLE
	It is possible to define all attirbutes of the group:
	[PS] p4add-groupspec -group groupname -maxresults 1000 -maxscanrows 1000 -maxlocktime 50000 -timeout 1000 -subgroups group1,group2,group3 -owners username1,username2,username3 -users username1,username2,username3, username4
	.PARAMETER group
	The name of the group
	.PARAMETER maxresults
	Limits the rows (unless 'unlimited' or 'unset') any one operation can return to the client.
	.PARAMETER maxscanrows
	Limits the rows (unless 'unlimited' or 'unset') any one operation can scan from any one database table.
	.PARAMETER maxlocktime
	Limits the time (in milliseconds, unless 'unlimited' or 'unset') any one operation can lock any database table when scanning data.
	.PARAMETER timeout
	A time (in seconds, unless 'unlimited' or 'unset') which determines how long a 'p4 login' session ticket remains valid (default is 12 hours).
	.PARAMETER subgroups
	Other groups automatically included in this group.
	.PARAMETER owners
	Users allowed to change this group without requiring super access permission.
	.PARAMETER users
	The users in the group.
	.FUNCTIONALITY
	Use this function return a groupspec to the console, or feed into further Perforce commands.
#>

Function p4add-groupspec
{param([parameter(Mandatory = $true)][string]$group,$maxresults,$maxscanrows,$maxlocktime,$timeout,$passwordtimeout,[array]$subgroups,[array]$owners,[array]$users)#begin function p4add-groupspec
$ErrorActionPreference = "SilentlyContinue"
#form the submit dialog for perforce. When updating groups in perforce, you update the ENTIRE group, not just an atomic change.
#when p4 reports data in tagged format (-ztag) any options set to "unlimited" are reported as -1. Great, except you can't actually use that number in a submit dialog. It expects to see the literal string "unlimited".
#So, if these values equal -1, re-cast to the word "unlimited" and store in the var, othrewise just store the actual value.

#maxresults
if (!$maxresults)
{
	$maxresults = "unset"
}
else
{
	if (($maxresults -eq "unset") -or ($maxresults -eq "unlimited"))
	{
		$maxresults = $maxresults #noop
	}
	else
	{
		try
		{
			[void][int]$maxresults
		}
		catch
		{
			write-warning "maxresults must be one of the following values: unset, unlimited, or an integer. Defaulting to `'unset`'."
			$maxresults = "unlimited"
		}
	}
	#if ([void][int]$maxresults -le 0)
	#{
	#	$maxresults = "unlimited"
	#}
}

#maxscanrows
if (!$maxscanrows)
{
	$maxscanrows = "unset"
}
else
{
	if (($maxscanrows -eq "unset") -or ($maxscanrows -eq "unlimited"))
	{
		$maxscanrows = $maxscanrows #noop
	}
	else
	{
		try
		{
			[void][int]$maxscanrows
		}
		catch
		{
			write-warning "maxscanrows must be one of the following values: unset, unlimited, or an integer. Defaulting to `'unset`'."
			$maxscanrows = "unset"
		}
	}
	#if ([void][int]$maxscanrows -le 0)
	#{
	#	$maxscanrows = "unlimited"
	#}
}


#maxlocktime
if (!$maxlocktime)
{
	$maxlocktime = "unset"
}
else
{
	if (($maxlocktime -eq "unset") -or ($maxlocktime -eq "unlimited"))
	{
		$maxlocktime = $maxlocktime #noop
	}
	else
	{
		try
		{
			[void][int]$maxlocktime
		}
		catch
		{
			write-warning "maxlocktime must be one of the following values: unset, unlimited, or an integer. Defaulting to `'unset`'."
			$maxlocktime = "unset"
		}
	}
	#if ([void][int]$maxlocktime -le 0)
	#{
	#	$maxlocktime = "unlimited"
	#}
}

#timeout
if (!$timeout)
{
	$timeout = "unset"
}
else
{
	if (($timeout -eq "unset") -or ($timeout -eq "unlimited"))
	{
		$timeout = $timeout #noop
	}
	else
	{
		try
		{
			[void][int]$timeout
		}
		catch
		{
			write-warning "timeout must be one of the following values: unset, unlimited, or an integer. Defaulting to `'unset`'."
			$timeout = "unset"
		}
	}
	#if ([void][int]$timeout -le 0)
	#{
	#	$timeout = "unlimited"
	#}
}

#passwordtimeout
if (!$passwordtimeout)
{
	$passwordtimeout = "unset"
}
else
{
	if (($passwordtimeout -eq "unset") -or ($passwordtimeout -eq "unlimited"))
	{
		$passwordtimeout = $passwordtimeout #noop
	}
	else
	{
		try
		{
			[void][int]$passwordtimeout
		}
		catch
		{
			write-warning "password timeout must be one of the following values: unset, unlimited, or an integer. Defaulting to `'unset`'."
			$passwordtimeout = "unset"
		}
	}
	#if ([void][int]$passwordtimeout -le 0)
	#{
	#	$passwordtimeout = "unlimited"
	#}
}

#users
$usersarray = @()
foreach ($user in $users) #have to add tabs and carraige returns to submit properly.
{
	$usersarray += $user + "`t`n`r`n`r"#reformat the user list array to be happy.
}

#subgroups
$subgroupsarray = @()
foreach ($subgroup in $subgroups) #have to add tabs and carraige returns to submit properly.
{
	$subgroupsarray += $subgroup + "`t`n`r`n`r"#reformat the subgroups list array to be happy.
}

#owners
$ownersarray = @()
foreach ($owner in $owners) #have to add tabs and carraige returns to submit properly.
{
	$ownersarray += $owner + "`t`n`r`n`r"#reformat the owners list array to be happy.
}


	$datefield = (get-date).year.tostring() + "`/" + (get-date).month.tostring() + "`/" + (get-date).day.tostring() + " " + (get-date).hour.tostring() + ":" + (get-date).Minute.tostring() + ":" + (get-date).second.tostring() #format date string to exactly what perforce wants
	$spec = "`r`nGroup:`t" + $group + "`r`n`r`nMaxResults:`t" + $maxresults + "`r`n`r`nMaxScanRows:`t" + $maxscanrows + "`r`n`r`nMaxLockTime:`t" + $maxlocktime + "`r`n`r`nTimeout:`t" + $timeout + "`r`n`r`nSubgroups:`t" + $subgroupsarray + "`r`n`r`nOwners:`t" + $ownersarray + "`r`n`r`nUsers:`r`n`t" + $usersarray  #password timeout removed until it's supported on all depots. create a group issue command in a format that perforce can digest.
	#$spec = "`r`nGroup:`t" + $group + "`r`n`r`nMaxResults:`t" + $maxresults + "`r`n`r`nMaxScanRows:`t" + $maxscanrows + "`r`n`r`nMaxLockTime:`t" + $maxlocktime + "`r`n`r`nTimeout:`t" + $timeout + "`r`n`r`nPasswordTimeout:`t" + $passwordtimeout + "`r`n`r`nSubgroups:`t" + $subgroupsarray + "`r`n`r`nOwners:`t" + $ownersarray + "`r`n`r`nUsers:`r`n`t" + $usersarray  #create a group issue command in a format that perforce can digest.
	return $spec
	#some notes on creating the form. p4get groups returns a list of all objects and their attributes. We group into groups, and return all attributes. When getting attribs, we can always count on record [0] to be there, and it will always contain all attributes found for that group record set. We want to carry over particular attributes that may have been customized, not stomp over them with a default setting.

}