[Sandweb-commit] CVS: sandweb/lib/SandWeb Auth.pm,1.23,1.24 Browse.pm,1.80,1.81 Diff.pm,1.10,1.11 File.pm,1.61,1.62

[Rob H. <for...@us...>]

Update of /cvsroot/sandweb/sandweb/lib/SandWeb
In directory sc8-pr-cvs1:/tmp/cvs-serv13992

Modified Files:
	Auth.pm Browse.pm Diff.pm File.pm 
Log Message:
started copying the real API docs into the files as POD


Index: Auth.pm
===================================================================
RCS file: /cvsroot/sandweb/sandweb/lib/SandWeb/Auth.pm,v
retrieving revision 1.23
retrieving revision 1.24
diff -U2 -r1.23 -r1.24
--- Auth.pm	5 Jan 2003 08:59:07 -0000	1.23
+++ Auth.pm	6 Jan 2003 09:41:09 -0000	1.24
@@ -36,4 +36,65 @@
 use SandWeb::Auth::FlatFile;
 
+=head1
+
+--------------------------------------------------------------------------------
+
+METHOD
+	new
+
+SYNOPSIS
+
+	my $login = $auth->login(
+                'log_obj' => $log,
+                'data_dir' => $config->{'paths'}->{'data_dir'},
+                'cookie_path' => $config->{'cookie'}->{'path'},
+                'cookie_domain' => $config->{'cookie'}->{'domain'},
+        );
+
+
+DESCRIPTION
+
+	This method is a constructor.
+
+PARAMETERS
+
+    log_obj (type: string) (required)
+        
+	This contains a reference to an instantiated log object.
+
+        Default: none.
+
+    data_dir (type: string) (required)
+
+        This is the path to SandWeb's data directory.
+
+        Default: none.
+
+    cookie_path (type: string) (required)
+
+    	This is the path on the server side where cookie data is stored.
+
+        Default: none.
+        
+    cookie_domain (type: string) (required)
+
+	This is the domain that we tell the browser this cookie belongs to.
+
+        Default: none.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
+
+=cut
+
 sub new {
     my $class = shift;
@@ -51,4 +112,52 @@
 }
 
+=head1
+METHOD
+
+	login
+
+SYNOPSIS
+
+	my $status = $auth->login(
+		username => $username,
+		password => $password,
+		salt => $salt,
+        );
+
+
+DESCRIPTION
+
+	This method checks the username, password and salt
+	sent to it for validity.
+
+PARAMETERS
+
+    username (type: string) (required)
+
+	Contains a username to check for authenticity.
+    
+        Default: none.
+
+    username (type: string) (required)
+
+	Contains an encrypted password to check for authenticity.
+
+        Default: none.
+
+    username (type: string) (required)
+
+    	Contains the salt for the encrypted password.
+        
+        Default: none.
+
+RETURN CODES
+
+    1 = The user is authentic.
+ 
+    0 = The user is not authentic.
+ 
+--------------------------------------------------------------------------------
+
+=cut
 
 sub login {
@@ -81,4 +190,35 @@
 } 
 
+=head1 
+
+METHOD
+	load_user
+
+SYNOPSIS
+
+	my $status = $auth->load_user( 
+		$cookie, 
+	);
+
+DESCRIPTION
+
+	Attempts to validate user's auth cookie, and load the user's
+	settings into the global hashes.
+
+PARAMETERS
+
+	Takes value of the user's cookie as an argument.
+        
+RETURN CODES
+
+    1 = The cookie is valid, and the load completed successfully.
+ 
+    0 = The cookie is not valid, the user info was not loaded.
+ 
+
+--------------------------------------------------------------------------------
+
+=cut
+
 sub load_user {
     # verifies cookie
@@ -98,4 +238,32 @@
 }
 
+=head1
+
+METHOD
+	logout
+
+SYNOPSIS
+
+	my $stat = $auth->logout();
+
+DESCRIPTION
+
+	Logs a user out of SandWeb by removing their cookie.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+    	Maybe the cookie file could not be written to?
+ 
+--------------------------------------------------------------------------------
+
+=cut
+
 sub logout {
     my $self = shift;
@@ -106,4 +274,31 @@
 }
 
+=head1
+
+METHOD
+	get_username
+
+SYNOPSIS
+
+	my $username = $auth->get_username()
+
+DESCRIPTION
+
+	Returns the current user's full username.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    Returns a string.
+ 
+    0 = This means that the method got an error proccessing your request.
+ 
+--------------------------------------------------------------------------------
+
+=cut
+
 sub get_username {
     my $self = shift;
@@ -111,4 +306,30 @@
 	return $self->{user_info}->{'username'};
 }
+
+=head1
+
+METHOD
+	set_auth_cookie
+
+SYNOPSIS
+
+	my $cookie = $auth->set_auth_cookie();
+
+DESCRIPTION
+
+	Generates random auth cookie.	
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+
+    Returns a randomly generated string.
+ 
+    0 = This means that the method got an error proccessing your request.
+
+=cut
 
 sub set_auth_cookie {

Index: Browse.pm
===================================================================
RCS file: /cvsroot/sandweb/sandweb/lib/SandWeb/Browse.pm,v
retrieving revision 1.80
retrieving revision 1.81
diff -U2 -r1.80 -r1.81
--- Browse.pm	5 Jan 2003 08:59:07 -0000	1.80
+++ Browse.pm	6 Jan 2003 09:41:10 -0000	1.81
@@ -44,7 +44,94 @@
 use strict;
 
+=head1
+
+uses SandWeb::File, SandWeb::Security
+
+=cut
+
 use SandWeb::File;
 use SandWeb::Security;
 
+=head1
+
+METHOD
+	new
+
+SYNOPSIS
+
+	my $browse = SandWeb::Browse->new(
+        	'username' => $username,
+		'module_name' => $module_name,
+		'repo_name' => $repo_name,
+		'vcs_commands' => \@vcs_commands,
+		'sort' => $sort,
+		'users_dir' => $users_dir,
+		'log_obj' => $log,
+	);
+
+DESCRIPTION
+
+	This method is a constructor.
+
+PARAMETERS
+
+    username (type: string) (required)
+
+    	The current user's full username.
+        
+        Default: none.
+
+    module_name (type: string) (required)
+
+    	The name of the VCS module that the user is wants to browse.
+        
+        Default: none.
+
+    repo_name (type: string) (required)
+
+    	The name of the repository that contains the module that the
+	user wants to browse.
+        
+        Default: none.
+
+    vcs_commands (type: array) (required)
+
+    	Contains all valid VCS commands for the current module ( for use
+	by the tool bar ).
+        
+        Default: none.
+
+    sort (type: string) (required)
+
+    	The sorting order for the files.
+
+	FIXME - this should only be for the get_browse method, not the
+	constructor.
+        
+        Default: none.
+
+    users_dir (type: string) (required)
+
+    	The path to the user's home directory.
+        
+        Default: none.
+
+    log_obj (type: string) (required)
+
+	Contains a reference to an instantiated log object.
+        
+        Default: none.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+--------------------------------------------------------------------------------
+
+=cut
+
 sub new {
 	my $class = shift;
@@ -71,4 +158,70 @@
 }
 
+=head1
+
+METHOD
+
+	get_browser
+
+SYNOPSIS
+
+	my %browser = $browse->get_browser(
+		'location' => $location,
+		'progname' => $progname,
+		'repo_type' => $repo_type,
+		'repo_name' => $repo_name,
+		'sort' => $sort,
+	);
+
+DESCRIPTION
+
+	This returns HTML depicting the directories and files that
+	the user wishes to browse, with traverse deeper into the
+	heirarchy.
+
+PARAMETERS
+
+    location (type: string) (required)
+
+    	The location that the user wants to start browsing from, relative
+	to the homedir/reponame/module.
+        
+        Default: none.
+
+    progname (type: string) (required)
+
+    	The name of the CGI ( sandweb.cgi for example ).
+        
+        Default: none.
+
+    repo_type (type: string) (required)
+
+    	The type of repository ( e.g. CVS, RCS, SVN, etc. ).
+        
+        Default: none.
+
+    repo_name (type: string) (required)
+
+    	The name of the current repository.
+        
+        Default: none.
+
+    sort (type: string) (required)
+
+	This is the sort order for files/directories ( alphabetically or 
+	reverse alphabetically ).
+        
+        Default: none.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+--------------------------------------------------------------------------------
+
+=cut
 
 sub get_browser {
@@ -206,4 +359,52 @@
 }
 
+=head1
+
+METHOD
+
+	get_tool_bar
+
+SYNOPSIS
+
+	my %toolbar = $browse->get_tool_bar(
+		'location' => $location,
+		'progname' => $progname,
+	);
+
+DESCRIPTION
+
+	Returns an HTML template depicting the Browse toolbar,
+	which allows you to create/remove files/directories and
+	run VCS commands.
+
+	FIXME - the calling application shouldn't have to run
+	this template object through a loop and insert the VCS
+	commands, this should happen inside the Browse object.
+
+PARAMETERS
+
+    location (type: string) (required)
+
+    	The current browsing location.
+        
+        Default: none.
+
+    progname (type: string) (required)
+
+    	The name of the CGI ( e.g. sandweb.cgi )
+        
+        Default: none.
+
+RETURN CODES
+
+    Returns a hash reference to an HTML::Template object.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+--------------------------------------------------------------------------------
+
+=cut
+
 sub get_tool_bar {
 	my $self = shift;
@@ -245,4 +446,31 @@
 }
 
+=head1
+
+METHOD
+
+	get_current_location
+
+SYNOPSIS
+
+	my $current_location = $browse->get_current_location();
+
+
+DESCRIPTION
+
+	Returns the current location of the browse object.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    Returns the current location of the browse object as a string.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+
+=cut
 
 sub get_current_location {

Index: Diff.pm
===================================================================
RCS file: /cvsroot/sandweb/sandweb/lib/SandWeb/Diff.pm,v
retrieving revision 1.10
retrieving revision 1.11
diff -U2 -r1.10 -r1.11
--- Diff.pm	5 Jan 2003 08:59:07 -0000	1.10
+++ Diff.pm	6 Jan 2003 09:41:10 -0000	1.11
@@ -54,4 +54,41 @@
 =cut
 
+=head1
+
+METHOD
+        new
+
+SYNOPSIS
+
+        my $diff = $diff->new(
+		diff => $context_diff_format-data;
+	);
+
+DESCRIPTION
+
+	This method is a constructor.
+
+PARAMETERS
+
+    diff (type: string) (required)
+        
+	this contains data in context diff format
+
+        Default: none.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
+
+=cut
+
 sub new {
 	my $class = shift;
@@ -71,4 +108,37 @@
 colored_diff
 	returns an HTML-colorized output of the difference between two files
+
+=cut
+
+=head1
+
+METHOD
+        colored_diff
+
+SYNOPSIS
+
+ 	my $output = $diff->colored_diff();
+
+DESCRIPTION
+
+	This method colorizes and returns the data that was provided via
+	the constructor ( green for additions, red for removals, blue
+	for all else ).
+
+PARAMETERS
+
+        None
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut

Index: File.pm
===================================================================
RCS file: /cvsroot/sandweb/sandweb/lib/SandWeb/File.pm,v
retrieving revision 1.61
retrieving revision 1.62
diff -U2 -r1.61 -r1.62
--- File.pm	5 Jan 2003 08:59:07 -0000	1.61
+++ File.pm	6 Jan 2003 09:41:10 -0000	1.62
@@ -63,4 +63,52 @@
 =cut
 
+=head1
+
+METHOD
+        new
+
+SYNOPSIS
+
+	my $file = SandWeb::File->new( 
+		location => $location;
+		filename => $filename;
+	);
+                                  
+
+DESCRIPTION
+
+    This method is a constructor. It needs to know the location of the
+    file as well as the name of the file.
+
+PARAMETERS
+
+    location (type: string) (required)
+        
+	This contains the full ( absolute or relative ) path
+	to the file, as far as the file system is concerned.
+
+	Default: none.
+
+    filename (type: string) (required)
+	
+	This contains the full name of the file, as far as the
+	file system is concerned.
+
+	Default: none.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
+
+=cut
+
 sub new {
 	my $class = shift;
@@ -95,4 +143,30 @@
 =head1
 
+METHOD
+        get_owner
+
+SYNOPSIS
+
+	my $owner = $file->get_owner();
+
+DESCRIPTION
+
+	Returns the UID of the owner of the file.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 get_owner
 
@@ -108,7 +182,30 @@
 =head1
 
-get_group
+METHOD
+        get_group
+
+SYNOPSIS
 
-	returns the group ownership of the current file
+	my $group = $file->get_group();
+
+DESCRIPTION
+
+	Returns the GID of the group membership of the file.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -121,7 +218,30 @@
 =head1
 
-get_filename
+METHOD
+        get_filename 
+
+SYNOPSIS
+
+	my $filename = $file->get_filename();
 
-	returns the name of the current file
+DESCRIPTION
+
+	Returns the full name of the file.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -134,7 +254,31 @@
 =head1
 
-get_location
+METHOD
+        get_location
+
+SYNOPSIS
+
+	my $location = $file->get_location();
+
+DESCRIPTION
+
+	Returns the full ( absolute or relative ) path
+	to the file.
 
-	returns the location (directory) of the current file
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -147,7 +291,31 @@
 =head1
 
-get_permissions
+METHOD
+        get_permissions
+
+SYNOPSIS
+
+	my $permissions = $file->get_permissions();
+
+DESCRIPTION
+
+	Returns the current file system permissions,
+	as an octal value.
+
+PARAMETERS
 
-	returns the permissions of the current file
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -160,7 +328,32 @@
 =head1
 
-get_file_type
-	
-	returns the type of the current file
+METHOD
+        get_file_type
+
+SYNOPSIS
+
+	my $file_type = $file->get_file_type();
+
+DESCRIPTION
+
+	Returns Perl's guess as to what type of file
+	this is. Type returned one of : Binary, Text,
+	Directory or Unknown.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -185,7 +378,30 @@
 =head1
 
-get_mime_type
-	
-	returns the mime type of the current file
+METHOD
+        get_size
+
+SYNOPSIS
+
+	my $file_size = $file->get_size();
+
+DESCRIPTION
+
+	Returns the size of the file, in bytes.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -227,7 +443,31 @@
 =head1
 
-get_age
-	
-	returns the age of the current file
+METHOD
+        get_age
+
+SYNOPSIS
+
+	my $age = $file->get_age();
+
+DESCRIPTION
+
+	Returns the date of the last modification to this
+	file, in local time ( day month date time year ).
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -315,7 +555,30 @@
 =head1
 
-create_file
-	
-	creates a file at the current location with the current filename
+METHOD
+        create_file
+
+SYNOPSIS
+
+	my $return = $file->create_file();
+
+DESCRIPTION
+
+	Creates a file, using the filename passed to the constructor.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -341,7 +604,31 @@
 =head1
 
-create_folder
-	
-	creates a folder at the current location with the current filename
+METHOD
+        create_folder
+
+SYNOPSIS
+
+	my $return = $file->create_folder();
+
+DESCRIPTION
+
+	Creates a folder ( also known as a directory ) using the
+	filename passed to the constructor.
+
+PARAMETERS
+
+	None.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -365,7 +652,30 @@
 =head1
 
-delete
-	
-	deletes the current file
+METHOD
+        delete
+
+SYNOPSIS
+
+	my $return = $file->delete();
+
+DESCRIPTION
+
+	Removes the file specified in the constructor.
+
+PARAMETERS
+
+	none.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -390,7 +700,29 @@
 =head1
 
-delete_folder
-	
-	deletes the current folder
+METHOD
+        delete_folder
+
+SYNOPSIS
+
+	my $return = $file->delete_folder();
+
+DESCRIPTION
+
+	Removes the folder specified in the constructor.
+
+PARAMETERS
+
+	none.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
 
 =cut
@@ -417,7 +749,31 @@
 =head1
 
-copy
-	
-	copies the current file
+METHOD
+        copy
+
+SYNOPSIS
+
+	my $return = $file->copy( tofile => "alternate_name.c" );
+
+DESCRIPTION
+
+	Creates an exact copy of the file.
+
+PARAMETERS
+
+	tocopy (type: string) (required)
+		Contains the full path and filename of the copy.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut
@@ -443,7 +799,32 @@
 =head1
 
-rename
-	
-	renames the current file
+METHOD
+        rename
+
+SYNOPSIS
+
+	my $return = $file->rename( tofile => "alternate_name.c" );
+
+DESCRIPTION
+
+	Renames an existing file. This is the same thing as a move,
+	as far as the file system and operating system are concerned.
+
+PARAMETERS
+
+	tocopy (type: string) (required)
+		Contains the full path and filename of the new file.
+
+RETURN CODES
+
+    1 = The operation completed successfully.
+ 
+    0 = This means that the method got an error proccessing your request.
+        Perhaps an invalid parameter?
+ 
+   -1 = This return value means that there was not sufficient permision to
+        read the files specified, or they did not exist.
+
+--------------------------------------------------------------------------------
 
 =cut