# pam_vars cut-down first-pass documentation
#
# $Log$
#
	Options:
		* file=/etc/pam.service
		
	No /etc/passwd or pam_env
		
	pam_var
		
		PVF Rev 0.00
		
		Followed by multiple GROUPs, where a GROUP is defined thusly:
		
		GROUP is:
			GUARD:GROUPNAME:
			(GROUP|GUARD SETTING)*
			::GROUPNAME

			:IDENTIFIER:
			  GROUP
			| [IDENTIFIER[, IDENTIFIER] VAR=EXPRESSION [VAR=EXPRESSION]*]*
			::IDENTIFIER

		QUALIFIEDGROUPNAME is:
			GROUPNAME(QUALIFIER)*

		QUALIFIER is:
			/IDENTIFIER

		IDENTIFIER is:
			[a-zA-Z][a-zA-Z0-9_]+

		GROUPNAME is:
			IDENTIFIER
			(note that GROUPNAMEs starting with _ are all reserved)
		
		KEY is:
			an EXPRESSION

		GUARD is: 
			a comma-separated list of REXPRESSIONS
		
		SETTING is:
			a whitespace-separated list of ASSIGNMENTS
		
		If a GROUP's KEY evaluates to the null string, it will still
		be sent through the GROUP and compared against GUARDS, but will
		only match an explicit "" null-string GUARD or the * anything GUARD.

		QUALIFIERS are not currently used, but /nomatch is tentatively
		mentioned as a way to set complex defaults without actually causing
		a GUARD match.
		
		ASSIGNMENTS look like this:
		
		VAR  =	EXPRESSION	is a simple assignment
		VAR .=	EXPRESSION	is a simple concatenation assignment
		VAR ?=	EXPRESSION	is a simple assignment, if EXPRESSION is non-null
		VAR |=	EXPRESSION	is a set-addition assignment (appends to end)
		VAR &=	REXPRESSION	is a set-removal assignment
		VAR ~=	REXPRESSION	is a complement-set-removal assignment
		
		`set' operations work on IFS-separated lists.
		
		VAR is just an IDENTIFIER. An all-uppercase IDENTIFIER is assumed
		to be an environment variable; lower-case makes it a PAM variable.
		
		For the moment, I'm putting pam-items in as read-only values, 
		with the same identifiers as they're addressed in pam.h. This makes
		their names PAM_USER PAM_TTY PAM_RHOST PAM_CONV PAM_RUSER,
		PAM_USER_PROMPT, PAM_AUTHTOK and PAM_OLDAUTHTOK. All PAM_ names are
		reserved, unless I put them into Pam_ instead, later. :)

		Notice that using PAM_USER or PAM_AUTHTOK may cause interrogation of
		the application. There is no crypt() support in the module (yet).
		
		EXPRESSION is currently just a string-replacement operation with
		operators akin to the Bash variable operators, but works with both
		${} environment variables and @{} PAM variables:

			${VAR}       is the plain expansion.
			${VAR:-default string if VAR is null}
			${VAR:+replace non-null string}
			${#VAR}      is the length of VAR in characters
			${##VAR}     is the length of VAR in fields (using IFS)
			${VAR#word}  is the value of VAR, with the shortest
			${VAR##word} longest matching value of word stripped from the start
			${VAR%word}  is the value of VAR, with the shortest
			${VAR%%word} longest matching value of word stripped from the end
			
			${?message to syslog}
			${??message to user if not quiet, always to syslog}
			${!as ? above, but terminate immediately, returning @{deny}}
			${!!as ?? above, but terminate immediately, returning @{deny}}
			
			$[]          is a special, to do arithmetic.
			
		Once EXPRESSION has been expanded, and if the context is appropriate,
		the wildcard matching is invoked. This occurs in GUARDS and in the
		set operations above.  If an expression is to contain spaces, colons,
		comment characters, or equals signs, it must be surrounded by unescaped
		"" double quotes. Literal double quotes, \escapes, $ signs, and @ signs
		must be \escaped, whether in double quotes, or not.

		
		REXPRESSIONS are regular expressions, currently only basic REs
		are available:
		
			* matches any number of characters
			? matches only one character
			! negates the expressions, but binds more strongly than ,
		
		GUARD:_INCLUDE:INCLUDEFILE
			Includes the file if GUARD succeeds, and the file is not world-
			writeable. If INCLUDEFILE is a string containing spaces, the first
			block of non-spaces is the filename, but the rest of the string
			may specify options almost exactly like pam.conf, allowing easy
			inclusion of /etc/passwd type files:

			:_INCLUDE:"/etc/passwd fields=USER::UID:GID:GECOS:HOME:SHELL" 
			::_INCLUDE
			
			_INCLUDE's body may contain defaults for the file.
			The `almosts' are these extra options:
			
			- class may be made equal to any expression (which currently can't
			- fromid is a `fail-weak', and so it must be specified if the UID
			- nest checks the depth of the file, and raises an error if the
			- modeokay sidesteps the `not world readable' check.
			- userset takes a colon-separated list of env-vars which may be set
		
		GUARD:_LOOP/maxit=50:WHILE
			Enters the loop (ended with a trailing ::_LOOP) if GUARD succeeds,
			iterates once, and repeats the _LOOP if WHILE evaluates true.
		
		GUARD?:_NEW:CONFIGURATIONCLASS
		GUARD?:_NEW/configurationclass:otherstuff
			This group is under consideration.